docyard 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eab96fe7bde5b0471a5a60996f818f5909d159e34a96034506e5095730e64988
-  data.tar.gz: 319e4251a18b40c28960c2854079420feac035e472bf9f5f03845cccfc310879
+  metadata.gz: 52a27eaf396879abae3d0b091e5a488629022bb777838fafc17c0bb07e15d65b
+  data.tar.gz: ec6a567e2e411800f67f96351a80f7e60823ac399df8cac7e82b7c3a9a1370b5
 SHA512:
-  metadata.gz: 25c8f7d91d19d3905141894e7cf8f2968b7d7d20343f9fda48e5f105f952ba3f627227063a888dd70b7c17187950ac83e649196afbbde215e643e5f723157c1f
-  data.tar.gz: 338baa09ab053ffba20f745263f6bed124276ce707d8b2adc4d96ebf0a18b0b195f7097edfba8ffcde9265abe7cda3eaefd6710f01e3bf71b3836b87c21eb429
+  metadata.gz: 6e0d9995254e35e291250db40c9572d3bde1a76d86433d0fbcfb6e2a8602d6e68ad6be910d7a03036814dcdc0fba64289d68c760d9d6f1336376e2f709ec35b8
+  data.tar.gz: 127131f44ea7140f227a8e95468b96e09256b5fced9ef557e37e5a1caefc888adb902a8b2d164474cb1f31ae0ddd4b76b1c4684b39e5125ddce17c84bbd754e7

data/CHANGELOG.md

@@ -7,7 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.3.0] - 2025-01-09
+## [0.5.0] - 2025-11-18
+
+### Added
+- **Table of Contents** - Auto-generated TOC from h2-h4 headings with clickable anchor links and smooth scrolling (#30)
+- **Previous/Next Navigation** - Auto-detection from sidebar order with frontmatter override support and configurable labels (#31)
+
+## [0.4.0] - 2025-11-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-11-09
 
 ### Added
 - Configuration system with optional `docyard.yml` file (#20)
@@ -63,7 +91,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.3.0...HEAD
+[Unreleased]: https://github.com/sanifhimani/docyard/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/sanifhimani/docyard/compare/v0.4.0...v0.5.0
+[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

data/README.md

@@ -5,41 +5,59 @@
 
 > Documentation generator for Ruby
 
-**Early development** - Core features and components work, but missing search and build command. See [roadmap](#roadmap).
+Build beautiful documentation sites with hot reload, dark mode, and powerful markdown components.
 
 ## Features
 
-- **Configuration system** - Optional `docyard.yml` for site metadata, branding, and build settings
+### 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
-- **Hot reload** - Changes appear instantly while you write
+- **Sidebar customization** - Custom ordering, icons, and external links via config
+- **Table of Contents** - Auto-generated TOC with heading anchors and smooth scrolling
+- **Previous/Next navigation** - Auto-detection from sidebar with frontmatter override support
+- **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
-- **Code block enhancements** - Copy button with visual feedback
-- **Custom branding** - Logo and favicon with light/dark mode support
 - **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:
@@ -67,21 +85,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
@@ -117,6 +141,32 @@ description: Page description
 
 Currently supported:
 - `title` - Page title (shown in `<title>` tag)
+- `prev` - Customize or disable previous link
+- `next` - Customize or disable next link
+
+### Customizing Navigation
+
+Control previous/next links per page via frontmatter:
+
+```yaml
+---
+title: My Page
+prev: false                  # Disable previous link
+next:
+  text: Custom Next Page
+  link: /custom-path
+---
+```
+
+Configure labels globally in `docyard.yml`:
+
+```yaml
+navigation:
+  footer:
+    enabled: true
+    prev_text: "← Back"
+    next_text: "Forward →"
+```
 
 ### Linking Between Pages
 
@@ -205,18 +255,15 @@ bundle exec rubocop
 
 ## Roadmap
 
-**v0.3.0 - Recently shipped:**
-- Configuration system (docyard.yml)
-- Logo and favicon support
-- Dark mode with theme toggle
-- Icon system (24 Phosphor icons)
-- Callouts/Admonitions
-- Tabs component
-- Copy button for code blocks
-
-**Next up (v0.4.0):**
-- Sidebar customization
-- Static site generation (`docyard build`)
+**v0.5.0 - Just shipped:**
+- Table of Contents with heading anchors
+- Previous/Next page navigation with auto-detection
+
+**Next up (v0.6.0+):**
+- Code block enhancements (line numbers, highlighting, diffs)
+- Search functionality (client-side with Cmd/K)
+- Details/collapsible blocks
+- More markdown extensions
 
 ## Contributing
 

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

data/lib/docyard/build/static_generator.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "tty-progressbar"
+
+module Docyard
+  module Build
+    class StaticGenerator
+      attr_reader :config, :verbose, :renderer
+
+      def initialize(config, verbose: false)
+        @config = config
+        @verbose = verbose
+        @renderer = Renderer.new(base_url: config.build.base_url)
+      end
+
+      def generate
+        markdown_files = collect_markdown_files
+        puts "\n[✓] Found #{markdown_files.size} markdown files"
+
+        progress = TTY::ProgressBar.new(
+          "Generating pages [:bar] :current/:total (:percent%)",
+          total: markdown_files.size,
+          width: 50
+        )
+
+        markdown_files.each do |file_path|
+          generate_page(file_path)
+          progress.advance
+        end
+
+        markdown_files.size
+      end
+
+      private
+
+      def collect_markdown_files
+        Dir.glob(File.join("docs", "**", "*.md"))
+      end
+
+      def generate_page(markdown_file_path)
+        output_path = determine_output_path(markdown_file_path)
+        current_path = determine_current_path(markdown_file_path)
+
+        sidebar_html = build_sidebar(current_path)
+        html_content = renderer.render_file(
+          markdown_file_path,
+          sidebar_html: sidebar_html,
+          branding: branding_options
+        )
+
+        FileUtils.mkdir_p(File.dirname(output_path))
+        File.write(output_path, html_content)
+
+        log "Generated: #{output_path}" if verbose
+      end
+
+      def determine_output_path(markdown_file_path)
+        relative_path = markdown_file_path.delete_prefix("docs/")
+        base_name = File.basename(relative_path, ".md")
+        dir_name = File.dirname(relative_path)
+
+        output_dir = config.build.output_dir
+
+        if base_name == "index"
+          File.join(output_dir, dir_name, "index.html")
+        else
+          File.join(output_dir, dir_name, base_name, "index.html")
+        end
+      end
+
+      def determine_current_path(markdown_file_path)
+        relative_path = markdown_file_path.delete_prefix("docs/")
+        base_name = File.basename(relative_path, ".md")
+        dir_name = File.dirname(relative_path)
+
+        if base_name == "index"
+          dir_name == "." ? "/" : "/#{dir_name}"
+        else
+          dir_name == "." ? "/#{base_name}" : "/#{dir_name}/#{base_name}"
+        end
+      end
+
+      def build_sidebar(current_path)
+        SidebarBuilder.new(
+          docs_path: "docs",
+          current_path: current_path,
+          config: config
+        ).to_html
+      end
+
+      def branding_options
+        default_branding.merge(config_branding_options)
+      end
+
+      def default_branding
+        {
+          site_title: Constants::DEFAULT_SITE_TITLE,
+          site_description: "",
+          logo: Constants::DEFAULT_LOGO_PATH,
+          logo_dark: Constants::DEFAULT_LOGO_DARK_PATH,
+          favicon: nil,
+          display_logo: true,
+          display_title: true
+        }
+      end
+
+      def config_branding_options
+        site = config.site
+        branding = config.branding
+
+        {
+          site_title: site.title || Constants::DEFAULT_SITE_TITLE,
+          site_description: site.description || "",
+          logo: resolve_logo(branding.logo, branding.logo_dark),
+          logo_dark: resolve_logo_dark(branding.logo, branding.logo_dark),
+          favicon: branding.favicon
+        }.merge(appearance_options(branding.appearance))
+      end
+
+      def appearance_options(appearance)
+        appearance ||= {}
+        {
+          display_logo: appearance["logo"] != false,
+          display_title: appearance["title"] != false
+        }
+      end
+
+      def resolve_logo(logo, logo_dark)
+        logo || logo_dark || Constants::DEFAULT_LOGO_PATH
+      end
+
+      def resolve_logo_dark(logo, logo_dark)
+        logo_dark || logo || Constants::DEFAULT_LOGO_DARK_PATH
+      end
+
+      def log(message)
+        puts message if verbose
+      end
+    end
+  end
+end