docyard 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0614d285d89d4f529607c5e4bdb50c823cce769a5628b90100234c9513f98690
-  data.tar.gz: 2f7c134bca20f17766e54fb4bc3b02b602e735cf4d8c7e11f83f9158773bec22
+  metadata.gz: db5ddabfe4a3b7bf25c24876b915188bd4768ca543772ad0a8cfc971ee791fee
+  data.tar.gz: d906b1c2ab33102c9ade6e2cb23f6d067fdbf240d6a4a8e2aa27a52a9ba62b42
 SHA512:
-  metadata.gz: 1259470e5245ff3ffc8796144a1e48fae46d851b44ca2c6cbeda0e8f83c782ebb815cfdfe0bdb3fa36fc25744a050859df44e5451376c8dadb4601ad9c3e2e98
-  data.tar.gz: 90281b4af9dd20425d26d6ea14214de5a79237ddeec9038546b9142819e363051850c64942a1b56459e5e8e1c509d08a36b323c2e01e3bacd4353fc39755915a
+  metadata.gz: 2abc1d991cade7059cfaa0b54c2b6f88b33625937e8073cee9d8f61948149567a209a378efd225e9fe85b45b7579ef4e1d81599be5a8cbee970e9cb6e5218a3c
+  data.tar.gz: dcd2baa65fcdd4c00825c6f895c035ffd53603ec22503233b600925084b6512b651c9a009687682f1f5cab3a0c8d8e3d0a5c7586634d6da174e4e4c5a95f9a53

data/CHANGELOG.md

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2025-01-16
+
+### Added
+- **Static site generation** - Build system with `docyard build` command (#27)
+- **Preview server** - Test builds locally with `docyard preview` command (#27)
+- **Asset bundling** - CSS/JS minification with content hashing for cache busting (#27)
+- **SEO files** - Automatic generation of sitemap.xml and robots.txt (#27)
+- **Base URL support** - Deploy to subdirectories with configurable base_url (#27)
+- **Sidebar customization** - Config-driven navigation with custom ordering, icons, and external links (#26)
+- **Improved init templates** - Practical, helpful templates showcasing all features (#28)
+- **Clean init output** - Minimal, helpful success message with clear next steps (#28)
+
+### Changed
+- Init command now creates focused, practical templates (4 files vs 9 previously) (#28)
+- Templates now only include implemented features (no images/HTML/escaping) (#28)
+- Config file (docyard.yml) is cleaner with better comments and examples (#28)
+
+### Fixed
+- Code block CSS transition performance with GPU acceleration (#25)
+- Component CSS accessibility and performance improvements (#24)
+- Table responsive styling with proper wrapper element (#23)
+
+## [0.3.0] - 2025-01-09
+
+### Added
+- Configuration system with optional `docyard.yml` file (#20)
+- Logo and favicon support with light/dark mode switching (#21)
+- Dark mode with theme toggle and system preference detection (#14)
+- Icon system with 24 Phosphor icons and `:icon:` syntax (#15)
+- Callouts/Admonitions with 5 types (note, tip, important, warning, danger) (#16)
+- Tabs component with keyboard navigation and icon auto-detection (#17, #18)
+- Copy button for code blocks with visual feedback (#19)
+- Component-based architecture with processors for extensibility
+- Asset handler with dynamic concatenation of component files
+
+### Changed
+- CSS architecture now uses CSS variables for comprehensive theming
+- Markdown processing enhanced with preprocessor/postprocessor pattern
+
 ## [0.2.0] - 2025-11-08
 
 ### Added
@@ -46,7 +85,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Initial gem structure
 - Project scaffolding
 
-[Unreleased]: https://github.com/sanifhimani/docyard/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/sanifhimani/docyard/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/sanifhimani/docyard/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/sanifhimani/docyard/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/sanifhimani/docyard/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/sanifhimani/docyard/compare/v0.0.1...v0.1.0
 [0.0.1]: https://github.com/sanifhimani/docyard/releases/tag/v0.0.1

data/LICENSE.vscode-icons

@@ -0,0 +1,42 @@
+File Type Icons from VSCode Icons
+=====================================
+
+The file type icons embedded in lib/docyard/icons/file_types.rb are from the VSCode Icons project:
+https://github.com/vscode-icons/vscode-icons
+
+License: Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
+https://creativecommons.org/licenses/by-sa/4.0/
+
+Copyright (c) 2016 Roberto Huertas
+
+Icons included:
+- JavaScript (.js)
+- TypeScript (.ts)
+- JSX (.jsx)
+- TSX (.tsx)
+- Python (.py)
+- Ruby (.rb)
+- HTML (.html)
+- CSS (.css)
+- JSON (.json)
+- YAML (.yaml)
+- TOML (.toml)
+- Go (.go)
+- Rust (.rs)
+- PHP (.php)
+- SQL (.sql)
+- MySQL (.mysql)
+- PostgreSQL (.pgsql)
+- GraphQL (.graphql)
+- Vue (.vue)
+- Svelte (.svelte)
+- Protobuf (.proto)
+
+These icons are used under the terms of the CC BY-SA 4.0 license.
+You are free to:
+- Share — copy and redistribute the material in any medium or format
+- Adapt — remix, transform, and build upon the material for any purpose, even commercially
+
+Under the following terms:
+- Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made
+- ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license

data/README.md

@@ -5,33 +5,57 @@
 
 > Documentation generator for Ruby
 
-**Early development** - Core features work, but missing search and build command. See [roadmap](#roadmap).
+Build beautiful documentation sites with hot reload, dark mode, and powerful markdown components.
 
 ## Features
 
-- **Sidebar navigation** - Automatic sidebar with nested folders and collapsible sections
+### Core
+- **Static site generation** - Build static sites with `docyard build`
 - **Hot reload** - Changes appear instantly while you write
+- **Dark mode** - Beautiful light/dark theme with system preference detection
+- **Configuration system** - Optional `docyard.yml` for site metadata, branding, and build settings
+- **Custom branding** - Logo and favicon with light/dark mode support
+- **Base URL support** - Deploy to subdirectories or custom paths
+
+### Navigation
+- **Sidebar navigation** - Automatic sidebar with nested folders and collapsible sections
+- **Sidebar customization** - Custom ordering, icons, and external links via config
+- **Active page highlighting** - Always know where you are
+
+### Markdown
 - **GitHub Flavored Markdown** - Tables, task lists, strikethrough
-- **Syntax highlighting** - 100+ languages via Rouge
+- **Syntax highlighting** - 100+ languages via Rouge with copy button
+- **Markdown components**:
+  - **Callouts** - 5 types (note, tip, important, warning, danger) with GitHub alerts syntax
+  - **Tabs** - Code blocks, package managers, and custom tabs with keyboard navigation
+  - **Icons** - 24 Phosphor icons with `:icon:` syntax
 - **YAML frontmatter** - Add metadata to your pages
-- **Customizable error pages** - Make 404/500 pages your own
+
+### Production
+- **Asset bundling** - Minified CSS/JS with content hashing for cache busting
+- **SEO** - Automatic sitemap.xml and robots.txt generation
+- **Preview server** - Test production builds locally before deploying
+- **Mobile responsive** - Looks great on all devices
 
 ## Quick Start
 
 ```bash
-# Install the gem
+# Install
 gem install docyard
 
-# Create a new docs project
-mkdir my-docs && cd my-docs
+# Initialize
 docyard init
 
-# Start the dev server
+# Start dev server
 docyard serve
+# → http://localhost:4200
 
-# Visit http://localhost:4200
+# Build for production
+docyard build
 ```
 
+Your site is ready to deploy! Upload the `dist/` folder to any static host.
+
 ## Installation
 
 Add to your Gemfile:
@@ -59,21 +83,27 @@ This creates:
 docs/
   index.md                          # Home page
   getting-started/
-    introduction.md                 # Getting started guide
-    installation.md                 # Installation instructions
-    quick-start.md                  # Quick start guide
-  core-concepts/
-    file-structure.md              # File structure guide
-    markdown.md                     # Markdown guide
+    installation.md                 # Installation guide
+  guides/
+    markdown-features.md            # Markdown features showcase
+    configuration.md                # Configuration guide
+docyard.yml                         # Optional configuration
 ```
 
-### Start Development Server
+### Commands
 
 ```bash
+# Development server with hot reload
 docyard serve
-
-# Custom port and host
 docyard serve --port 3000 --host 0.0.0.0
+
+# Build for production
+docyard build
+docyard build --no-clean  # Don't clean output directory
+
+# Preview production build
+docyard preview
+docyard preview --port 4001
 ```
 
 ### Writing Docs
@@ -119,6 +149,33 @@ Write links with `.md` extension, they'll be automatically cleaned:
 [Guide](./guide/index.md)                → /guide
 ```
 
+### Using Icons
+
+Docyard includes 24 essential Phosphor icons that work out of the box. Just type `:icon-name:` in your markdown:
+
+```markdown
+:check: Zero configuration
+:lightning: Hot reload
+:rocket-launch: Fast and lightweight
+
+Use different weights:
+:heart:         → regular weight (default)
+:heart:bold:    → bold weight
+:heart:fill:    → filled version
+```
+
+Available icons: `heart`, `check`, `x`, `warning`, `info`, `question`, `arrow-right`, `arrow-left`, `arrow-up`, `arrow-down`, `code`, `terminal`, `package`, `rocket-launch`, `star`, `lightning`, `moon-stars`, `sun`, `link-external`, `copy`, `github`, `file`, `terminal-window`, `warning-circle`.
+
+Weights: `regular` (default), `bold`, `fill`, `light`, `thin`, `duotone`
+
+Icons automatically match your text size and color.
+
+**Adding new icons:**
+
+1. Get the SVG path from [phosphoricons.com](https://phosphoricons.com)
+2. Add to `lib/docyard/icons/phosphor.rb` under the appropriate weight
+3. Format: `"icon-name" => '<path d="..."/>',`
+
 ### Directory Structure
 
 ```
@@ -170,12 +227,18 @@ bundle exec rubocop
 
 ## Roadmap
 
+**v0.4.0 - Just shipped:**
+- Static site generation with `docyard build`
+- Asset bundling with minification and cache busting
+- SEO files (sitemap.xml, robots.txt)
+- Preview server for testing builds
+- Sidebar customization via config
+- Improved init templates
+
 **Next up:**
-- Dark mode with theme toggle
-- Markdown components (callouts, code groups, collapsible sections)
-- Icon system
-- Client-side search
-- Static site generation (`docyard build`)
+- Search functionality
+- Table of contents
+- More markdown components
 
 ## Contributing
 

data/lib/docyard/asset_handler.rb

@@ -3,6 +3,7 @@
 module Docyard
   class AssetHandler
     ASSETS_PATH = File.join(__dir__, "templates", "assets")
+    USER_ASSETS_PATH = "docs/assets"
 
     CONTENT_TYPES = {
       ".css" => "text/css; charset=utf-8",
@@ -21,6 +22,9 @@ module Docyard
 
       return forbidden_response if directory_traversal?(asset_path)
 
+      return serve_components_css if asset_path == "css/components.css"
+      return serve_components_js if asset_path == "js/components.js"
+
       file_path = build_file_path(asset_path)
       return not_found_response unless File.file?(file_path)
 
@@ -38,6 +42,9 @@ module Docyard
     end
 
     def build_file_path(asset_path)
+      user_path = File.join(USER_ASSETS_PATH, asset_path)
+      return user_path if File.file?(user_path)
+
       File.join(ASSETS_PATH, asset_path)
     end
 
@@ -48,6 +55,32 @@ module Docyard
       [200, { "Content-Type" => content_type }, [content]]
     end
 
+    def serve_components_css
+      content = concatenate_component_css
+      [200, { "Content-Type" => "text/css; charset=utf-8" }, [content]]
+    end
+
+    def concatenate_component_css
+      components_dir = File.join(ASSETS_PATH, "css", "components")
+      return "" unless Dir.exist?(components_dir)
+
+      css_files = Dir.glob(File.join(components_dir, "*.css"))
+      css_files.map { |file| File.read(file) }.join("\n\n")
+    end
+
+    def serve_components_js
+      content = concatenate_component_js
+      [200, { "Content-Type" => "application/javascript; charset=utf-8" }, [content]]
+    end
+
+    def concatenate_component_js
+      components_dir = File.join(ASSETS_PATH, "js", "components")
+      return "" unless Dir.exist?(components_dir)
+
+      js_files = Dir.glob(File.join(components_dir, "*.js"))
+      js_files.map { |file| File.read(file) }.join("\n\n")
+    end
+
     def detect_content_type(file_path)
       extension = File.extname(file_path)
       CONTENT_TYPES.fetch(extension, "application/octet-stream")

data/lib/docyard/build/asset_bundler.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "cssminify"
+require "terser"
+require "digest"
+
+module Docyard
+  module Build
+    class AssetBundler
+      ASSETS_PATH = File.join(__dir__, "..", "templates", "assets")
+
+      attr_reader :config, :verbose
+
+      def initialize(config, verbose: false)
+        @config = config
+        @verbose = verbose
+      end
+
+      def bundle
+        puts "\nBundling assets..."
+
+        css_hash = bundle_css
+        js_hash = bundle_js
+
+        update_html_references(css_hash, js_hash)
+
+        2
+      end
+
+      private
+
+      def bundle_css
+        log "  Bundling CSS..."
+
+        main_css = File.read(File.join(ASSETS_PATH, "css", "main.css"))
+        css_content = resolve_css_imports(main_css)
+        minified = CSSminify.compress(css_content)
+        hash = generate_hash(minified)
+
+        write_bundled_asset(minified, hash, "css")
+        log_compression_stats(css_content, minified, "CSS")
+
+        hash
+      end
+
+      def resolve_css_imports(css_content)
+        css_content.gsub(/@import url\('([^']+)'\);/) do |match|
+          import_file = Regexp.last_match(1)
+
+          if import_file == "components.css"
+            concatenate_component_css
+          else
+            file_path = File.join(ASSETS_PATH, "css", import_file)
+            File.exist?(file_path) ? File.read(file_path) : match
+          end
+        end
+      end
+
+      def concatenate_component_css
+        components_dir = File.join(ASSETS_PATH, "css", "components")
+        return "" unless Dir.exist?(components_dir)
+
+        css_files = Dir.glob(File.join(components_dir, "*.css"))
+        css_files.map { |file| File.read(file) }.join("\n\n")
+      end
+
+      def bundle_js
+        log "  Bundling JS..."
+
+        theme_js = File.read(File.join(ASSETS_PATH, "js", "theme.js"))
+        components_js = concatenate_component_js
+        js_content = [theme_js, components_js].join("\n")
+        minified = Terser.compile(js_content)
+        hash = generate_hash(minified)
+
+        write_bundled_asset(minified, hash, "js")
+        log_compression_stats(js_content, minified, "JS")
+
+        hash
+      end
+
+      def concatenate_component_js
+        components_dir = File.join(ASSETS_PATH, "js", "components")
+        return "" unless Dir.exist?(components_dir)
+
+        js_files = Dir.glob(File.join(components_dir, "*.js"))
+        js_files.map { |file| File.read(file) }.join("\n\n")
+      end
+
+      def generate_hash(content)
+        Digest::MD5.hexdigest(content)[0..7]
+      end
+
+      def update_html_references(css_hash, js_hash)
+        html_files = Dir.glob(File.join(config.build.output_dir, "**", "*.html"))
+        base_url = normalize_base_url(config.build.base_url)
+
+        html_files.each do |file|
+          content = replace_asset_references(File.read(file), css_hash, js_hash, base_url)
+          File.write(file, content)
+        end
+
+        log "  [✓] Updated asset references in #{html_files.size} HTML files"
+      end
+
+      def replace_asset_references(content, css_hash, js_hash, base_url)
+        content.gsub(%r{/assets/css/main\.css}, "#{base_url}assets/bundle.#{css_hash}.css")
+          .gsub(%r{/assets/js/theme\.js}, "#{base_url}assets/bundle.#{js_hash}.js")
+          .gsub(%r{/assets/js/components\.js}, "")
+          .gsub(%r{<script src="/assets/js/reload\.js"></script>}, "")
+      end
+
+      def write_bundled_asset(content, hash, extension)
+        filename = "bundle.#{hash}.#{extension}"
+        output_path = File.join(config.build.output_dir, "assets", filename)
+        FileUtils.mkdir_p(File.dirname(output_path))
+        File.write(output_path, content)
+      end
+
+      def log_compression_stats(original, minified, label)
+        original_size = (original.bytesize / 1024.0).round(1)
+        minified_size = (minified.bytesize / 1024.0).round(1)
+        reduction = (((original_size - minified_size) / original_size) * 100).round(0)
+        log "  [✓] #{label}: #{original_size} KB -> #{minified_size} KB (-#{reduction}%)"
+      end
+
+      def normalize_base_url(url)
+        return "/" if url.nil? || url.empty? || url == "/"
+
+        url = "/#{url}" unless url.start_with?("/")
+        url.end_with?("/") ? url : "#{url}/"
+      end
+
+      def log(message)
+        puts message
+      end
+    end
+  end
+end

data/lib/docyard/build/file_copier.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Build
+    class FileCopier
+      attr_reader :config, :verbose
+
+      def initialize(config, verbose: false)
+        @config = config
+        @verbose = verbose
+      end
+
+      def copy
+        puts "\nCopying static assets..."
+
+        count = 0
+        count += copy_user_assets
+        count += copy_branding_assets
+
+        log "[✓] Copied #{count} static files"
+        count
+      end
+
+      private
+
+      def copy_user_assets
+        user_assets_dir = "docs/assets"
+        return 0 unless Dir.exist?(user_assets_dir)
+
+        output_assets_dir = File.join(config.build.output_dir, "assets")
+        FileUtils.mkdir_p(output_assets_dir)
+
+        files = find_user_asset_files(user_assets_dir)
+        files.each { |file| copy_single_asset(file, "docs/assets/", output_assets_dir) }
+
+        log "[✓] Copied #{files.size} user assets from docs/assets/" if files.any?
+        files.size
+      end
+
+      def find_user_asset_files(assets_dir)
+        Dir.glob(File.join(assets_dir, "**", "*")).select { |f| File.file?(f) }
+      end
+
+      def copy_single_asset(file, prefix, output_dir)
+        relative_path = file.delete_prefix(prefix)
+        dest_path = File.join(output_dir, relative_path)
+
+        FileUtils.mkdir_p(File.dirname(dest_path))
+        FileUtils.cp(file, dest_path)
+
+        log "  Copied: #{relative_path}" if verbose
+      end
+
+      def copy_branding_assets
+        count = 0
+        count += copy_default_branding_assets
+        count += copy_user_branding_assets
+        log "[✓] Copied #{count} branding assets" if count.positive?
+        count
+      end
+
+      def copy_default_branding_assets
+        templates_assets = File.join(__dir__, "..", "templates", "assets")
+        count = 0
+
+        ["logo.svg", "logo-dark.svg", "favicon.svg"].each do |asset_file|
+          source_path = File.join(templates_assets, asset_file)
+          next unless File.exist?(source_path)
+
+          dest_path = File.join(config.build.output_dir, "assets", asset_file)
+          FileUtils.mkdir_p(File.dirname(dest_path))
+          FileUtils.cp(source_path, dest_path)
+
+          log "  Copied default branding: #{asset_file}" if verbose
+          count += 1
+        end
+
+        count
+      end
+
+      def copy_user_branding_assets
+        %w[logo logo_dark favicon].sum { |asset_key| copy_single_branding_asset(asset_key) }
+      end
+
+      def copy_single_branding_asset(asset_key)
+        asset_path = config.branding.send(asset_key)
+        return 0 if asset_path.nil? || asset_path.start_with?("http://", "https://")
+
+        full_path = File.join("docs", asset_path)
+        return 0 unless File.exist?(full_path)
+
+        dest_path = File.join(config.build.output_dir, "assets", asset_path)
+        FileUtils.mkdir_p(File.dirname(dest_path))
+        FileUtils.cp(full_path, dest_path)
+
+        log "  Copied user branding: #{asset_path}" if verbose
+        1
+      end
+
+      def log(message)
+        puts message
+      end
+    end
+  end
+end

data/lib/docyard/build/sitemap_generator.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Docyard
+  module Build
+    class SitemapGenerator
+      attr_reader :config
+
+      def initialize(config)
+        @config = config
+      end
+
+      def generate
+        urls = collect_urls
+        sitemap_content = build_sitemap(urls)
+
+        output_path = File.join(config.build.output_dir, "sitemap.xml")
+        File.write(output_path, sitemap_content)
+
+        puts "[✓] Generated sitemap.xml (#{urls.size} URLs)"
+      end
+
+      private
+
+      def collect_urls
+        html_files = Dir.glob(File.join(config.build.output_dir, "**", "index.html"))
+
+        html_files.map do |file|
+          relative_path = file.delete_prefix(config.build.output_dir).delete_suffix("/index.html")
+          url_path = relative_path.empty? ? "/" : relative_path
+          lastmod = File.mtime(file).utc.iso8601
+
+          { loc: url_path, lastmod: lastmod }
+        end
+      end
+
+      def build_sitemap(urls)
+        base_url = config.build.base_url
+        base_url = base_url.chop if base_url.end_with?("/")
+
+        xml = ['<?xml version="1.0" encoding="UTF-8"?>']
+        xml << '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">'
+
+        urls.each do |url|
+          xml << "  <url>"
+          xml << "    <loc>#{base_url}#{url[:loc]}</loc>"
+          xml << "    <lastmod>#{url[:lastmod]}</lastmod>"
+          xml << "  </url>"
+        end
+
+        xml << "</urlset>"
+        xml.join("\n")
+      end
+    end
+  end
+end