docyard 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0614d285d89d4f529607c5e4bdb50c823cce769a5628b90100234c9513f98690
-  data.tar.gz: 2f7c134bca20f17766e54fb4bc3b02b602e735cf4d8c7e11f83f9158773bec22
+  metadata.gz: eab96fe7bde5b0471a5a60996f818f5909d159e34a96034506e5095730e64988
+  data.tar.gz: 319e4251a18b40c28960c2854079420feac035e472bf9f5f03845cccfc310879
 SHA512:
-  metadata.gz: 1259470e5245ff3ffc8796144a1e48fae46d851b44ca2c6cbeda0e8f83c782ebb815cfdfe0bdb3fa36fc25744a050859df44e5451376c8dadb4601ad9c3e2e98
-  data.tar.gz: 90281b4af9dd20425d26d6ea14214de5a79237ddeec9038546b9142819e363051850c64942a1b56459e5e8e1c509d08a36b323c2e01e3bacd4353fc39755915a
+  metadata.gz: 25c8f7d91d19d3905141894e7cf8f2968b7d7d20343f9fda48e5f105f952ba3f627227063a888dd70b7c17187950ac83e649196afbbde215e643e5f723157c1f
+  data.tar.gz: 338baa09ab053ffba20f745263f6bed124276ce707d8b2adc4d96ebf0a18b0b195f7097edfba8ffcde9265abe7cda3eaefd6710f01e3bf71b3836b87c21eb429

data/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +63,8 @@ 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.3.0...HEAD
+[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,14 +5,22 @@
 
 > Documentation generator for Ruby
 
-**Early development** - Core features work, but missing search and build command. See [roadmap](#roadmap).
+**Early development** - Core features and components work, but missing search and build command. See [roadmap](#roadmap).
 
 ## Features
 
+- **Configuration system** - Optional `docyard.yml` for site metadata, branding, and build settings
+- **Dark mode** - Beautiful light/dark theme with system preference detection
 - **Sidebar navigation** - Automatic sidebar with nested folders and collapsible sections
 - **Hot reload** - Changes appear instantly while you write
 - **GitHub Flavored Markdown** - Tables, task lists, strikethrough
 - **Syntax highlighting** - 100+ languages via Rouge
+- **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
 
@@ -119,6 +127,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,11 +205,17 @@ bundle exec rubocop
 
 ## Roadmap
 
-**Next up:**
+**v0.3.0 - Recently shipped:**
+- Configuration system (docyard.yml)
+- Logo and favicon support
 - Dark mode with theme toggle
-- Markdown components (callouts, code groups, collapsible sections)
-- Icon system
-- Client-side search
+- 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`)
 
 ## 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/components/base_processor.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Components
+    class BaseProcessor
+      class << self
+        attr_accessor :priority
+
+        def inherited(subclass)
+          super
+          Registry.register(subclass)
+        end
+      end
+
+      def preprocess(content)
+        content
+      end
+
+      def postprocess(html)
+        html
+      end
+    end
+  end
+end

data/lib/docyard/components/callout_processor.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "../icons"
+require_relative "../renderer"
+require_relative "base_processor"
+require "kramdown"
+require "kramdown-parser-gfm"
+
+module Docyard
+  module Components
+    class CalloutProcessor < BaseProcessor
+      self.priority = 10
+
+      CALLOUT_TYPES = {
+        "note" => { title: "Note", icon: "info", color: "note" },
+        "tip" => { title: "Tip", icon: "lightbulb", color: "tip" },
+        "important" => { title: "Important", icon: "warning-circle", color: "important" },
+        "warning" => { title: "Warning", icon: "warning", color: "warning" },
+        "danger" => { title: "Danger", icon: "siren", color: "danger" }
+      }.freeze
+
+      GITHUB_ALERT_TYPES = {
+        "NOTE" => "note",
+        "TIP" => "tip",
+        "IMPORTANT" => "important",
+        "WARNING" => "warning",
+        "CAUTION" => "danger"
+      }.freeze
+
+      def preprocess(markdown)
+        process_container_syntax(markdown)
+      end
+
+      def postprocess(html)
+        process_github_alerts(html)
+      end
+
+      private
+
+      def process_container_syntax(markdown)
+        markdown.gsub(/^:::[ \t]*(\w+)(?:[ \t]+([^\n]+?))?[ \t]*\n(.*?)^:::[ \t]*$/m) do
+          process_callout_match(Regexp.last_match(0), Regexp.last_match(1), Regexp.last_match(2), Regexp.last_match(3))
+        end
+      end
+
+      def process_callout_match(original_match, type_raw, custom_title, content_markdown)
+        type = type_raw.downcase
+        return original_match unless CALLOUT_TYPES.key?(type)
+
+        config = CALLOUT_TYPES[type]
+        title = determine_title(custom_title, config[:title])
+        content_html = render_markdown_content(content_markdown.strip)
+
+        wrap_in_nomarkdown(render_callout_html(type, title, content_html, config[:icon]))
+      end
+
+      def determine_title(custom_title, default_title)
+        title = custom_title&.strip
+        title.nil? || title.empty? ? default_title : title
+      end
+
+      def render_markdown_content(content_markdown)
+        return "" if content_markdown.empty?
+
+        Kramdown::Document.new(
+          content_markdown,
+          input: "GFM",
+          hard_wrap: false,
+          syntax_highlighter: "rouge"
+        ).to_html
+      end
+
+      def wrap_in_nomarkdown(html)
+        "{::nomarkdown}\n#{html}\n{:/nomarkdown}"
+      end
+
+      def process_github_alerts(html)
+        github_alert_regex = %r{
+          <blockquote>\s*
+          <p>\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\s*
+          (?:<br\s*/>)?\s*
+          (.*?)</p>
+          (.*?)
+          </blockquote>
+        }mx
+
+        html.gsub(github_alert_regex) do
+          process_github_alert_match(Regexp.last_match(1), Regexp.last_match(2), Regexp.last_match(3))
+        end
+      end
+
+      def process_github_alert_match(alert_type, first_para, rest_content)
+        type = GITHUB_ALERT_TYPES[alert_type]
+        config = CALLOUT_TYPES[type]
+        content_html = combine_alert_content(first_para.strip, rest_content.strip)
+
+        render_callout_html(type, config[:title], content_html, config[:icon])
+      end
+
+      def combine_alert_content(first_para, rest_content)
+        return "<p>#{first_para}</p>" if rest_content.empty?
+
+        "<p>#{first_para}</p>#{rest_content}"
+      end
+
+      def render_callout_html(type, title, content_html, icon_name)
+        icon_svg = Icons.render(icon_name, "duotone") || ""
+        renderer = Renderer.new
+
+        renderer.render_partial(
+          "_callout", {
+            type: type,
+            title: title,
+            content_html: content_html,
+            icon_svg: icon_svg
+          }
+        )
+      end
+    end
+  end
+end

data/lib/docyard/components/code_block_processor.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "../icons"
+require_relative "../renderer"
+require_relative "base_processor"
+
+module Docyard
+  module Components
+    class CodeBlockProcessor < BaseProcessor
+      self.priority = 20
+
+      def postprocess(html)
+        return html unless html.include?('<div class="highlight">')
+
+        html.gsub(%r{<div class="highlight">(.*?)</div>}m) do
+          process_code_block(Regexp.last_match(0), Regexp.last_match(1))
+        end
+      end
+
+      private
+
+      def process_code_block(original_html, inner_html)
+        code_text = extract_code_text(inner_html)
+
+        render_code_block_with_copy(original_html, code_text)
+      end
+
+      def extract_code_text(html)
+        text = html.gsub(/<[^>]+>/, "")
+        text = CGI.unescapeHTML(text)
+        text.strip
+      end
+
+      def render_code_block_with_copy(code_block_html, code_text)
+        copy_icon = Icons.render("copy", "regular") || ""
+        renderer = Renderer.new
+
+        renderer.render_partial(
+          "_code_block", {
+            code_block_html: code_block_html,
+            code_text: escape_html_attribute(code_text),
+            copy_icon: copy_icon
+          }
+        )
+      end
+
+      def escape_html_attribute(text)
+        text.gsub('"', "&quot;")
+          .gsub("'", "&#39;")
+          .gsub("<", "&lt;")
+          .gsub(">", "&gt;")
+      end
+    end
+  end
+end

data/lib/docyard/components/code_detector.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "../language_mapping"
+
+module Docyard
+  module Components
+    class CodeDetector
+      def self.detect(content)
+        new(content).detect
+      end
+
+      def initialize(content)
+        @content = content
+      end
+
+      def detect
+        return nil unless code_only?
+
+        language = extract_language
+        return nil unless language
+
+        icon_for_language(language)
+      end
+
+      private
+
+      attr_reader :content
+
+      def code_only?
+        stripped = content.strip
+        return false unless stripped.start_with?("```") && stripped.end_with?("```")
+
+        parts = stripped.split("```")
+        parts.length == 2 && parts[0].empty?
+      end
+
+      def extract_language
+        parts = content.strip.split("```")
+        return nil unless parts[1]
+
+        lines = parts[1].split("\n", 2)
+        lang_line = lines[0].strip
+        return nil if lang_line.empty? || lang_line.include?(" ")
+
+        lang_line.downcase
+      end
+
+      def icon_for_language(language)
+        if LanguageMapping.terminal_language?(language)
+          { icon: "terminal-window", source: "phosphor" }
+        elsif (extension = LanguageMapping.extension_for(language))
+          { icon: extension, source: "file-extension" }
+        else
+          { icon: "file", source: "phosphor" }
+        end
+      end
+    end
+  end
+end

data/lib/docyard/components/icon_detector.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "code_detector"
+
+module Docyard
+  module Components
+    class IconDetector
+      MANUAL_ICON_PATTERN = /^:([a-z0-9-]+):\s*(.+)$/i
+
+      def self.detect(tab_name, tab_content)
+        new(tab_name, tab_content).detect
+      end
+
+      def initialize(tab_name, tab_content)
+        @tab_name = tab_name
+        @tab_content = tab_content
+      end
+
+      def detect
+        manual_icon || auto_detected_icon || no_icon
+      end
+
+      private
+
+      attr_reader :tab_name, :tab_content
+
+      def manual_icon
+        return nil unless tab_name.match(MANUAL_ICON_PATTERN)
+
+        {
+          name: Regexp.last_match(2).strip,
+          icon: Regexp.last_match(1),
+          icon_source: "phosphor"
+        }
+      end
+
+      def auto_detected_icon
+        detected = CodeDetector.detect(tab_content)
+        return nil unless detected
+
+        {
+          name: tab_name,
+          icon: detected[:icon],
+          icon_source: detected[:source]
+        }
+      end
+
+      def no_icon
+        {
+          name: tab_name,
+          icon: nil,
+          icon_source: nil
+        }
+      end
+    end
+  end
+end

data/lib/docyard/components/icon_processor.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "../icons"
+require_relative "base_processor"
+
+module Docyard
+  module Components
+    class IconProcessor < BaseProcessor
+      self.priority = 20
+
+      ICON_PATTERN = /:([a-z][a-z0-9-]*):(?:([a-z]+):)?/i
+
+      def postprocess(html)
+        segments = split_preserving_code_blocks(html)
+
+        segments.map do |segment|
+          segment[:type] == :code ? segment[:content] : process_segment(segment[:content])
+        end.join
+      end
+
+      private
+
+      def split_preserving_code_blocks(html)
+        segments = []
+        current_pos = 0
+
+        html.scan(%r{<(code|pre)[^>]*>.*?</\1>}m) do
+          match_start = Regexp.last_match.begin(0)
+          match_end = Regexp.last_match.end(0)
+
+          segments << { type: :text, content: html[current_pos...match_start] } if match_start > current_pos
+          segments << { type: :code, content: html[match_start...match_end] }
+
+          current_pos = match_end
+        end
+
+        segments << { type: :text, content: html[current_pos..] } if current_pos < html.length
+
+        segments.empty? ? [{ type: :text, content: html }] : segments
+      end
+
+      def process_segment(content)
+        content.gsub(ICON_PATTERN) do
+          icon_name = Regexp.last_match(1)
+          weight = Regexp.last_match(2) || "regular"
+          Icons.render(icon_name, weight) || Regexp.last_match(0)
+        end
+      end
+    end
+  end
+end

data/lib/docyard/components/registry.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Components
+    class Registry
+      @processors = []
+
+      class << self
+        def register(processor_class)
+          @processors << processor_class
+          @processors.sort_by! { |p| p.priority || 100 }
+        end
+
+        def run_preprocessors(content)
+          @processors.reduce(content) do |processed_content, processor_class|
+            processor_class.new.preprocess(processed_content)
+          end
+        end
+
+        def run_postprocessors(html)
+          @processors.reduce(html) do |processed_html, processor_class|
+            processor_class.new.postprocess(processed_html)
+          end
+        end
+
+        def reset!
+          @processors = []
+        end
+
+        attr_reader :processors
+      end
+    end
+  end
+end

data/lib/docyard/components/tabs_parser.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "icon_detector"
+require "kramdown"
+require "kramdown-parser-gfm"
+
+module Docyard
+  module Components
+    class TabsParser
+      def self.parse(content)
+        new(content).parse
+      end
+
+      def initialize(content)
+        @content = content
+      end
+
+      def parse
+        sections.filter_map { |section| parse_section(section) }
+      end
+
+      private
+
+      attr_reader :content
+
+      def sections
+        content.split(/^==[ \t]+/)
+      end
+
+      def parse_section(section)
+        return nil if section.strip.empty?
+
+        parts = section.split("\n", 2)
+        tab_name = parts[0]&.strip
+        return nil if tab_name.nil? || tab_name.empty?
+
+        tab_content = parts[1]&.strip || ""
+        icon_data = IconDetector.detect(tab_name, tab_content)
+
+        {
+          name: icon_data[:name],
+          content: render_markdown(tab_content),
+          icon: icon_data[:icon],
+          icon_source: icon_data[:icon_source]
+        }
+      end
+
+      def render_markdown(markdown_content)
+        return "" if markdown_content.empty?
+
+        Kramdown::Document.new(
+          markdown_content,
+          input: "GFM",
+          hard_wrap: false,
+          syntax_highlighter: "rouge"
+        ).to_html
+      end
+    end
+  end
+end