docyard 0.9.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51b2adfdb7f77c4366592cc3eea5a160fc42f85f17e44593e9bf192c3b470b48
-  data.tar.gz: 439d82b762c7bc6f485ab627365522b7e202833fc841c6b8655fb28e1e9b3e55
+  metadata.gz: 9ea61eefa97dc9199d17929def1315fdf2ce71f75ddf4f03833b9291fa64ce75
+  data.tar.gz: '0538fae77efffb84a8aac4ba979510419ff2a8cd8eec1b5aaf9effc2950595d8'
 SHA512:
-  metadata.gz: a66355efb4615ae4552aa8656e63078989cdec734f41670dc172936060954a065fefb1a2733e51494747ef0ab9a1dbee399b3c8f37daf2718e92ba03c315df9f
-  data.tar.gz: be3cea82f91b60cc7e7c35be142b6c2ccd9be4323cbf1c5190987b6ba6894d4c8da38f55c141abda43211a5ac2b70d38283e1b340d62071ee5c22c87c9c35a51
+  metadata.gz: f184c67f1be8766cdd6339da6b25ccd8b7f1d0150ce3f6c0db0de8dd68c590b82e29f76a4ec1928c29151018d318225f2769cea58be9ad1dc2c721a2593663d5
+  data.tar.gz: 982f4bdcd4170dd013dd5ee10fb21db935eeafcb486372a45db7ae58a3f8d75e6c716555585695ea9527cc7fbd2bf0e43c5a7982894160ec6832c591c2db45a1

data/CHANGELOG.md

@@ -7,6 +7,60 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.1] - 2026-01-22
+
+### Added
+- **Root Fallback Redirect** - Auto-redirect to first page when no index.md exists (#127)
+
+### Fixed
+- Breadcrumb sections without index pages now link to first navigable child (#126)
+- Error pages (404/500) now use custom branding colors (#125)
+- Base URL now correctly applied to all assets including fonts and search (#124)
+- Dev server no longer applies build.base config, always uses root path (#123)
+
+## [1.0.0] - 2026-01-22
+
+### Added
+- **Custom Social Links** - Add custom social icons with Phosphor icons or inline SVG via `socials.custom` config (#119)
+- **Branding Colors** - Customize primary color theme with `branding.color` supporting light/dark variants (#115)
+- **Custom Hero Visuals** - Use custom images/components in landing page hero sections (#114)
+- **Feedback Widget** - Collect user feedback on documentation pages (#107)
+- **Phosphor Icons CDN** - Load icons from CDN for smaller bundle size (#106)
+- **LLMs.txt Generation** - Auto-generate llms.txt files for AI indexing (#105)
+- **Copy Page Button** - One-click copy entire page content for LLM context (#104)
+- **Configurable Docs Path** - Customize source directory with `source` config option (#101)
+- **Parallel Builds** - Multi-threaded site generation for faster builds (#89)
+- **Analytics Integration** - Support for Google Analytics, Plausible, Fathom, and custom scripts (#77)
+- **Git Integration** - "Edit on GitHub" links and "Last updated" timestamps from git history (#76)
+- **Open Graph Meta Tags** - Auto-generated social sharing metadata (#75)
+- **Custom Error Pages** - Styled 404 and error pages (#78)
+- **GitHub Pages Workflow** - CI workflow for automated deployments (#117)
+
+### Changed
+- **Domain Migration** - Project domain changed from docyard.org to docyard.dev (#118)
+- **Init Command Revamp** - Improved scaffolding with better defaults (#109)
+- **Puma Web Server** - Migrated to Puma for better performance (#84)
+- **Search Optimization** - Improved search indexing and relevance (#86)
+- **Sidebar Caching** - Faster rebuilds with sidebar state caching (#85)
+
+### Fixed
+- Video embed dimension validation (#103)
+- Mobile navigation issues (#102)
+- Banner layout padding on tablet/mobile (#88)
+- TOC dropdown behavior (#87)
+- Flash of unstyled content (FOUC) prevention (#79)
+- Security and error handling improvements (#99, #100)
+
+### Performance
+- Parallel build support for multi-core systems (#89)
+- Batch git operations for faster metadata lookup (#91)
+- Dev server cache headers (#92)
+- Passive event listeners for smoother scrolling (#93)
+- Analytics domain preconnect hints (#83)
+- CSS will-change hints for animations (#82)
+- Font display swap for faster text rendering (#81)
+- Deferred script loading (#80)
+
 ## [0.9.0] - 2026-01-15
 
 ### Added
@@ -162,7 +216,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.9.0...HEAD
+[Unreleased]: https://github.com/sanifhimani/docyard/compare/v1.0.1...HEAD
+[1.0.1]: https://github.com/sanifhimani/docyard/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/sanifhimani/docyard/compare/v0.9.0...v1.0.0
 [0.9.0]: https://github.com/sanifhimani/docyard/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/sanifhimani/docyard/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/sanifhimani/docyard/compare/v0.6.0...v0.7.0

data/README.md

@@ -3,272 +3,27 @@
 [![CI](https://github.com/sanifhimani/docyard/actions/workflows/ci.yml/badge.svg)](https://github.com/sanifhimani/docyard/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/docyard.svg)](https://badge.fury.io/rb/docyard)
 
-> Documentation generator for Ruby
-
-Build beautiful documentation sites with hot reload, dark mode, and powerful markdown components.
-
-## Features
-
-### 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
-- **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 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
-
-### 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
+Beautiful documentation sites from Markdown. Fast, simple, no configuration required.
 
 ## Quick Start
 
 ```bash
-# Install
 gem install docyard
-
-# Initialize
-docyard init
-
-# Start dev server
-docyard serve
-# → 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:
-
-```ruby
-gem 'docyard'
-```
-
-Or install directly:
-
-```bash
-gem install docyard
-```
-
-## Usage
-
-### Initialize a New Project
-
-```bash
-docyard init
-```
-
-This creates:
-```
-docs/
-  index.md                          # Home page
-  getting-started/
-    installation.md                 # Installation guide
-  guides/
-    markdown-features.md            # Markdown features showcase
-    configuration.md                # Configuration guide
-docyard.yml                         # Optional configuration
-```
-
-### Commands
-
-```bash
-# Development server with hot reload
+docyard init my-docs
+cd my-docs
 docyard serve
-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
-
-Create markdown files in the `docs/` directory:
-
-```markdown
----
-title: Getting Started
----
-
-# Getting Started
-
-\`\`\`ruby
-class User
-  def initialize(name)
-    @name = name
-  end
-end
-\`\`\`
-```
-
-### Frontmatter
-
-Add YAML frontmatter to customize page metadata:
-
-```yaml
----
-title: My Page Title
-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
-
-Write links with `.md` extension, they'll be automatically cleaned:
-
-```markdown
-[Getting Started](./getting-started.md)  → /getting-started
-[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
-
-```
-docs/
-  index.md              # / (root)
-  getting-started.md    # /getting-started
-  guide/
-    index.md            # /guide
-    setup.md            # /guide/setup
-    advanced.md         # /guide/advanced
-```
-
-## Architecture
-
-Clean separation of concerns:
-
-```
-lib/docyard/
-  cli.rb              # Command-line interface (Thor)
-  initializer.rb      # Project scaffolding (init command)
-  server.rb           # Server lifecycle (WEBrick, signals)
-  rack_application.rb # HTTP request handling (routing, rendering)
-  router.rb           # URL → file path mapping
-  renderer.rb         # Markdown → HTML conversion
-  markdown.rb         # Markdown parsing & frontmatter extraction
-  file_watcher.rb     # Live reload file monitoring
-  asset_handler.rb    # Static asset serving
-```
-
-Each class has a single, clear responsibility. Easy to test, easy to extend.
-
-## Development
-
-```bash
-git clone https://github.com/sanifhimani/docyard.git
-cd docyard
-bundle install
-
-# Run tests
-bundle exec rspec
-
-# Run linter
-bundle exec rubocop
-
-# Use local version
-./bin/docyard init
-./bin/docyard serve
 ```
 
-## Roadmap
+Open http://localhost:4200 and start writing.
 
-**v0.5.0 - Just shipped:**
-- Table of Contents with heading anchors
-- Previous/Next page navigation with auto-detection
+## Documentation
 
-**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
+Visit [docyard.dev](https://docyard.dev) for the full documentation.
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md)
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+[MIT](LICENSE)

data/exe/docyard

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/docyard"
+
+Docyard::CLI.start(ARGV)

data/lib/docyard/build/asset_bundler.rb

@@ -17,7 +17,7 @@ module Docyard
       end
 
       def bundle
-        puts "\nBundling assets..."
+        Docyard.logger.info("\nBundling assets...")
 
         css_hash = bundle_css
         js_hash = bundle_js
@@ -37,6 +37,7 @@ module Docyard
         minified = CSSminify.compress(css_content)
         minified = fix_calc_whitespace(minified)
         minified = fix_css_math_functions(minified)
+        minified = replace_css_asset_urls(minified)
         hash = generate_hash(minified)
 
         write_bundled_asset(minified, hash, "css")
@@ -58,6 +59,11 @@ module Docyard
         css.gsub(/\bmax\(0,/, "max(0px,").gsub(/\bmin\(0,/, "min(0px,)")
       end
 
+      def replace_css_asset_urls(css)
+        base_url = normalize_base_url(config.build.base)
+        css.gsub(%r{/_docyard/fonts/}, "#{base_url}_docyard/fonts/")
+      end
+
       def resolve_css_imports(css_content)
         css_content.gsub(/@import url\('([^']+)'\);/) do |match|
           import_file = Regexp.last_match(1)
@@ -86,6 +92,7 @@ module Docyard
         components_js = concatenate_component_js
         js_content = [theme_js, components_js].join("\n")
         minified = Terser.compile(js_content)
+        minified = replace_js_asset_urls(minified)
         hash = generate_hash(minified)
 
         write_bundled_asset(minified, hash, "js")
@@ -94,6 +101,12 @@ module Docyard
         hash
       end
 
+      def replace_js_asset_urls(js_content)
+        base_url = normalize_base_url(config.build.base)
+        js_content.gsub(%r{"/_docyard/pagefind/}, "\"#{base_url}_docyard/pagefind/")
+          .gsub(%r{baseUrl:\s*["']/["']}, "baseUrl:\"#{base_url}\"")
+      end
+
       def concatenate_component_js
         components_dir = File.join(ASSETS_PATH, "js", "components")
         return "" unless Dir.exist?(components_dir)
@@ -123,6 +136,15 @@ module Docyard
           .gsub(%r{/_docyard/js/theme\.js}, "#{base_url}_docyard/bundle.#{js_hash}.js")
           .gsub(%r{/_docyard/js/components\.js}, "")
           .gsub(%r{<script src="/_docyard/js/reload\.js"></script>}, "")
+          .then { |html| replace_content_image_paths(html, base_url) }
+      end
+
+      def replace_content_image_paths(content, base_url)
+        return content if base_url == "/"
+
+        content.gsub(%r{(<img[^>]*\ssrc=")/(?!_docyard/)([^"]*")}) do
+          "#{Regexp.last_match(1)}#{base_url}#{Regexp.last_match(2)}"
+        end
       end
 
       def write_bundled_asset(content, hash, extension)
@@ -147,7 +169,7 @@ module Docyard
       end
 
       def log(message)
-        puts message
+        Docyard.logger.info(message)
       end
     end
   end

data/lib/docyard/build/error_page_generator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Build
+    class ErrorPageGenerator
+      attr_reader :config, :docs_path, :renderer
+
+      def initialize(config:, docs_path:, renderer:)
+        @config = config
+        @docs_path = docs_path
+        @renderer = renderer
+      end
+
+      def generate
+        output_path = File.join(config.build.output, "404.html")
+        html_content = load_content
+
+        FileUtils.mkdir_p(File.dirname(output_path))
+        File.write(output_path, html_content)
+      end
+
+      private
+
+      def load_content
+        custom_error_page = File.join(docs_path, "404.html")
+        return File.read(custom_error_page) if File.exist?(custom_error_page)
+
+        branding = BrandingResolver.new(config).resolve
+        renderer.render_not_found(branding: branding)
+      end
+    end
+  end
+end

data/lib/docyard/build/file_copier.rb

@@ -13,7 +13,7 @@ module Docyard
       end
 
       def copy
-        puts "\nCopying static assets..."
+        Docyard.logger.info("\nCopying static assets...")
 
         count = 0
         count += copy_public_files
@@ -26,7 +26,7 @@ module Docyard
       private
 
       def copy_public_files
-        public_dir = Constants::PUBLIC_DIR
+        public_dir = config.public_dir
         return 0 unless Dir.exist?(public_dir)
 
         files = find_files_in_dir(public_dir)
@@ -104,11 +104,18 @@ module Docyard
         %w[logo favicon].sum { |asset_key| copy_single_branding_asset(asset_key) }
       end
 
+      def branding_asset_path(asset_key)
+        case asset_key
+        when "logo" then config.branding.logo
+        when "favicon" then config.branding.favicon
+        end
+      end
+
       def copy_single_branding_asset(asset_key)
-        asset_path = config.branding.send(asset_key)
+        asset_path = branding_asset_path(asset_key)
         return 0 if asset_path.nil? || asset_path.start_with?("http://", "https://")
 
-        full_path = File.join("docs", asset_path)
+        full_path = File.join(config.source, asset_path)
         return 0 unless File.exist?(full_path)
 
         dest_path = File.join(config.build.output, asset_path)
@@ -120,7 +127,7 @@ module Docyard
       end
 
       def log(message)
-        puts message
+        Docyard.logger.info(message)
       end
     end
   end

data/lib/docyard/build/file_writer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Build
+    module FileWriter
+      def safe_file_write(path)
+        yield
+      rescue Errno::EACCES => e
+        raise BuildError, "Permission denied writing to #{path}: #{e.message}"
+      rescue Errno::ENOSPC => e
+        raise BuildError, "Disk full, cannot write to #{path}: #{e.message}"
+      rescue Errno::EROFS => e
+        raise BuildError, "Read-only filesystem, cannot write to #{path}: #{e.message}"
+      rescue SystemCallError => e
+        raise BuildError, "Failed to write #{path}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/docyard/build/llms_txt_generator.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative "../rendering/markdown"
+
+module Docyard
+  module Build
+    class LlmsTxtGenerator
+      attr_reader :config
+
+      def initialize(config)
+        @config = config
+      end
+
+      def generate
+        pages = collect_pages.sort_by { |page| page[:path] }
+        generate_llms_txt(pages)
+        generate_llms_full_txt(pages)
+      end
+
+      private
+
+      def collect_pages
+        Dir.glob(File.join(config.source, "**", "*.md")).map { |f| build_page_data(f) }
+      end
+
+      def build_page_data(file_path)
+        content = File.read(file_path)
+        markdown = Markdown.new(content, config: config, file_path: file_path)
+
+        {
+          title: markdown.title || url_path_for(file_path),
+          description: markdown.description,
+          path: url_path_for(file_path),
+          content: strip_frontmatter(content)
+        }
+      end
+
+      def url_path_for(file_path)
+        relative = file_path.delete_prefix("#{config.source}/").delete_suffix(".md")
+        relative == "index" ? "/" : "/#{relative}"
+      end
+
+      def strip_frontmatter(content)
+        return content unless content.start_with?("---")
+
+        parts = content.split(/^---\s*$/, 3)
+        parts.length >= 3 ? parts[2].strip : content
+      end
+
+      def generate_llms_txt(pages)
+        output_path = File.join(config.build.output, "llms.txt")
+        File.write(output_path, build_llms_txt_content(pages))
+        Docyard.logger.info("[✓] Generated llms.txt (#{pages.size} pages)")
+      end
+
+      def build_llms_txt_content(pages)
+        lines = header_lines
+        lines << "## Docs"
+        lines << ""
+        lines.concat(pages.map { |page| format_page_link(page) })
+        lines.join("\n")
+      end
+
+      def format_page_link(page)
+        line = "- [#{page[:title]}](#{page_url(page[:path])})"
+        line += ": #{page[:description]}" if page[:description]&.length&.positive?
+        line
+      end
+
+      def generate_llms_full_txt(pages)
+        output_path = File.join(config.build.output, "llms-full.txt")
+        File.write(output_path, build_llms_full_txt_content(pages))
+        Docyard.logger.info("[✓] Generated llms-full.txt")
+      end
+
+      def build_llms_full_txt_content(pages)
+        lines = header_lines
+        lines << "This file contains the complete documentation content."
+        lines << ""
+        pages.each { |page| lines.concat(format_page_content(page)) }
+        lines.join("\n")
+      end
+
+      def format_page_content(page)
+        ["---", "", "## #{page[:title]}", "", "URL: #{page_url(page[:path])}", "", page[:content], ""]
+      end
+
+      def header_lines
+        lines = ["# #{config.title}", ""]
+        return lines unless config.description&.length&.positive?
+
+        lines << "> #{config.description}"
+        lines << ""
+        lines
+      end
+
+      def page_url(path)
+        base = config.url || config.build.base
+        "#{base.chomp('/')}#{path}"
+      end
+    end
+  end
+end