docyard 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db5ddabfe4a3b7bf25c24876b915188bd4768ca543772ad0a8cfc971ee791fee
-  data.tar.gz: d906b1c2ab33102c9ade6e2cb23f6d067fdbf240d6a4a8e2aa27a52a9ba62b42
+  metadata.gz: 34bf24256bf638697dbc86f9d146667a4f17594c365070313eb19e74f8ab5134
+  data.tar.gz: 357ea04d8822f47c98e2aee4e09ca9e8cc69b7e4d11cbdce1491874aaa459b5c
 SHA512:
-  metadata.gz: 2abc1d991cade7059cfaa0b54c2b6f88b33625937e8073cee9d8f61948149567a209a378efd225e9fe85b45b7579ef4e1d81599be5a8cbee970e9cb6e5218a3c
-  data.tar.gz: dcd2baa65fcdd4c00825c6f895c035ffd53603ec22503233b600925084b6512b651c9a009687682f1f5cab3a0c8d8e3d0a5c7586634d6da174e4e4c5a95f9a53
+  metadata.gz: bc5c55d5ad69b73ef286eec3b4e202c7312b3dfd7d67b79d491612357e1c4e6e03d255a78af97706bdd5fe19353b7dd96f2da046a4c17f2e363342fc265b5628
+  data.tar.gz: 855fdcdcf312f3778fd204ca1fd36825c183b1abf0a5c938edff599693930d519668b8fdb0770f65ae00f9db43d1b794e31ca922b29dbde73143caf6abd2f64c

data/.rubocop.yml

@@ -16,7 +16,7 @@ Metrics/BlockLength:
     - '*.gemspec'
 
 RSpec/ExampleLength:
-  Max: 10
+  Max: 15
 
 Metrics/ClassLength:
   Max: 150

data/CHANGELOG.md

@@ -7,7 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.4.0] - 2025-01-16
+## [0.6.0] - 2025-12-25
+
+### Added
+- **Line Numbers** - Display line numbers on code blocks with `:line-numbers` or `:line-numbers=N` syntax, plus global config option (#33)
+- **Line Highlighting** - Highlight specific lines in code blocks with `{1,3,5-7}` syntax (#34)
+- **Diff Markers** - Show additions/deletions with `// [!code ++]` and `// [!code --]` comments, supports all major comment styles (#35)
+- **Code Block Titles** - Add filename titles to code blocks with `[filename.js]` syntax, auto-detects file icons (#36)
+- **Focus Mode** - Dim surrounding code with `// [!code focus]` to highlight important lines (#37)
+- **Error/Warning Markers** - Highlight problematic lines with `// [!code error]` and `// [!code warning]` (#38)
+- **Code Snippet Imports** - Import code from external files with `<<< @/filepath` syntax (#39)
+- **VS Code Regions** - Import specific code sections with `<<< @/filepath#region-name` (#39)
+- **Line Range Extraction** - Extract specific lines from imports with `<<< @/filepath{2-10}` (#39)
+- **Language Override** - Override auto-detected language in imports with `<<< @/filepath{js}` (#39)
+
+### Changed
+- Code block processor refactored for better maintainability with shared patterns module
+- Improved code block CSS with support for all new marker types
+
+## [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)
@@ -29,7 +53,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Component CSS accessibility and performance improvements (#24)
 - Table responsive styling with proper wrapper element (#23)
 
-## [0.3.0] - 2025-01-09
+## [0.3.0] - 2025-11-09
 
 ### Added
 - Configuration system with optional `docyard.yml` file (#20)
@@ -85,7 +109,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.4.0...HEAD
+[Unreleased]: https://github.com/sanifhimani/docyard/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/sanifhimani/docyard/compare/v0.5.0...v0.6.0
+[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

data/README.md

@@ -20,6 +20,8 @@ Build beautiful documentation sites with hot reload, dark mode, and powerful mar
 ### 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
@@ -139,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
 
@@ -227,18 +255,15 @@ 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:**
-- Search functionality
-- Table of contents
-- More markdown components
+**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/static_generator.rb

@@ -10,7 +10,7 @@ module Docyard
       def initialize(config, verbose: false)
         @config = config
         @verbose = verbose
-        @renderer = Renderer.new(base_url: config.build.base_url)
+        @renderer = Renderer.new(base_url: config.build.base_url, config: config)
       end
 
       def generate

data/lib/docyard/components/base_processor.rb

@@ -12,6 +12,12 @@ module Docyard
         end
       end
 
+      attr_reader :context
+
+      def initialize(context = {})
+        @context = context
+      end
+
       def preprocess(content)
         content
       end

data/lib/docyard/components/code_block_diff_preprocessor.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "base_processor"
+require_relative "code_block_patterns"
+
+module Docyard
+  module Components
+    class CodeBlockDiffPreprocessor < BaseProcessor
+      include CodeBlockPatterns
+
+      self.priority = 6
+
+      CODE_BLOCK_REGEX = /^```(\w*).*?\n(.*?)^```/m
+      TABS_BLOCK_REGEX = /^:::[ \t]*tabs[ \t]*\n.*?^:::[ \t]*$/m
+
+      def preprocess(content)
+        context[:code_block_diff_lines] ||= []
+        context[:code_block_error_lines] ||= []
+        context[:code_block_warning_lines] ||= []
+        @block_index = 0
+        @tabs_ranges = find_tabs_ranges(content)
+
+        content.gsub(CODE_BLOCK_REGEX) { |_| process_code_block(Regexp.last_match) }
+      end
+
+      private
+
+      def process_code_block(match)
+        return match[0] if inside_tabs?(match.begin(0))
+
+        result = extract_all_markers(match[2])
+        store_extracted_markers(result)
+        @block_index += 1
+        match[0].sub(match[2], result[:cleaned_content])
+      end
+
+      def store_extracted_markers(result)
+        context[:code_block_diff_lines][@block_index] = result[:diff_lines]
+        context[:code_block_error_lines][@block_index] = result[:error_lines]
+        context[:code_block_warning_lines][@block_index] = result[:warning_lines]
+      end
+
+      def extract_all_markers(code_content)
+        diff_info = extract_diff_lines(code_content)
+        error_info = extract_error_lines(diff_info[:cleaned_content])
+        warning_info = extract_warning_lines(error_info[:cleaned_content])
+
+        {
+          diff_lines: diff_info[:lines],
+          error_lines: error_info[:lines],
+          warning_lines: warning_info[:lines],
+          cleaned_content: warning_info[:cleaned_content]
+        }
+      end
+
+      def extract_diff_lines(code_content)
+        extract_marker_lines(code_content, DIFF_MARKER_PATTERN) do |match|
+          diff_type = match.captures.compact.first
+          diff_type == "++" ? :addition : :deletion
+        end
+      end
+
+      def extract_error_lines(code_content)
+        extract_marker_lines(code_content, ERROR_MARKER_PATTERN) { true }
+      end
+
+      def extract_warning_lines(code_content)
+        extract_marker_lines(code_content, WARNING_MARKER_PATTERN) { true }
+      end
+
+      def extract_marker_lines(code_content, pattern)
+        lines = code_content.lines
+        marker_lines = {}
+        cleaned_lines = []
+
+        lines.each_with_index do |line, index|
+          line_num = index + 1
+
+          if (match = line.match(pattern))
+            marker_lines[line_num] = yield(match)
+            cleaned_lines << line.gsub(pattern, "")
+          else
+            cleaned_lines << line
+          end
+        end
+
+        { lines: marker_lines, cleaned_content: cleaned_lines.join }
+      end
+
+      def inside_tabs?(position)
+        @tabs_ranges.any? { |range| range.cover?(position) }
+      end
+
+      def find_tabs_ranges(content)
+        ranges = []
+        content.scan(TABS_BLOCK_REGEX) do
+          match = Regexp.last_match
+          ranges << (match.begin(0)...match.end(0))
+        end
+        ranges
+      end
+    end
+  end
+end

data/lib/docyard/components/code_block_feature_extractor.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative "code_block_patterns"
+
+module Docyard
+  module Components
+    module CodeBlockFeatureExtractor
+      include CodeBlockPatterns
+
+      CODE_FENCE_REGEX = /^```(\w+)(?:\s*\[([^\]]+)\])?(:\S+)?(?:\s*\{([^}\n]+)\})?[ \t]*\n(.*?)^```/m
+
+      module_function
+
+      def process_markdown(markdown)
+        blocks = []
+        cleaned = markdown.gsub(CODE_FENCE_REGEX) do
+          block_data = extract_block_data(Regexp.last_match)
+          blocks << block_data
+          "```#{block_data[:lang]}\n#{block_data[:cleaned_content]}```"
+        end
+        { cleaned_markdown: cleaned, blocks: blocks }
+      end
+
+      def extract_block_data(match)
+        code_content = match[5]
+        diff_info = extract_diff_lines(code_content)
+        focus_info = extract_focus_lines(diff_info[:cleaned_content])
+        error_info = extract_error_lines(focus_info[:cleaned_content])
+        warning_info = extract_warning_lines(error_info[:cleaned_content])
+
+        build_block_result(match, diff_info, focus_info, error_info, warning_info)
+      end
+
+      def build_block_result(match, diff_info, focus_info, error_info, warning_info)
+        {
+          lang: match[1],
+          title: match[2],
+          option: match[3],
+          highlights: parse_highlights(match[4]),
+          diff_lines: diff_info[:lines],
+          focus_lines: focus_info[:lines],
+          error_lines: error_info[:lines],
+          warning_lines: warning_info[:lines],
+          cleaned_content: warning_info[:cleaned_content]
+        }
+      end
+
+      def parse_highlights(highlights_str)
+        return [] if highlights_str.nil? || highlights_str.strip.empty?
+
+        highlights_str.split(",").flat_map { |part| parse_highlight_part(part.strip) }.uniq.sort
+      end
+
+      def parse_highlight_part(part)
+        return (part.split("-")[0].to_i..part.split("-")[1].to_i).to_a if part.include?("-")
+
+        [part.to_i]
+      end
+
+      def extract_diff_lines(code_content)
+        lines = code_content.lines
+        diff_lines = {}
+        cleaned_lines = []
+
+        lines.each_with_index do |line, index|
+          line_num = index + 1
+
+          if (match = line.match(DIFF_MARKER_PATTERN))
+            diff_type = match.captures.compact.first
+            diff_lines[line_num] = diff_type == "++" ? :addition : :deletion
+            cleaned_line = line.gsub(DIFF_MARKER_PATTERN, "")
+            cleaned_lines << cleaned_line
+          else
+            cleaned_lines << line
+          end
+        end
+
+        { lines: diff_lines, cleaned_content: cleaned_lines.join }
+      end
+
+      def extract_focus_lines(code_content)
+        extract_marker_lines(code_content, FOCUS_MARKER_PATTERN)
+      end
+
+      def extract_error_lines(code_content)
+        extract_marker_lines(code_content, ERROR_MARKER_PATTERN)
+      end
+
+      def extract_warning_lines(code_content)
+        extract_marker_lines(code_content, WARNING_MARKER_PATTERN)
+      end
+
+      def extract_marker_lines(code_content, pattern)
+        lines = code_content.lines
+        marker_lines = {}
+        cleaned_lines = []
+
+        lines.each_with_index do |line, index|
+          line_num = index + 1
+
+          if line.match?(pattern)
+            marker_lines[line_num] = true
+            cleaned_lines << line.gsub(pattern, "")
+          else
+            cleaned_lines << line
+          end
+        end
+
+        { lines: marker_lines, cleaned_content: cleaned_lines.join }
+      end
+    end
+  end
+end

data/lib/docyard/components/code_block_focus_preprocessor.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "base_processor"
+
+module Docyard
+  module Components
+    class CodeBlockFocusPreprocessor < BaseProcessor
+      self.priority = 7
+
+      FOCUS_MARKER_PATTERN = %r{
+        (?:
+          //\s*\[!code\s+focus\]              |
+          \#\s*\[!code\s+focus\]              |
+          /\*\s*\[!code\s+focus\]\s*\*/       |
+          --\s*\[!code\s+focus\]              |
+          <!--\s*\[!code\s+focus\]\s*-->      |
+          ;\s*\[!code\s+focus\]
+        )[^\S\n]*
+      }x
+
+      CODE_BLOCK_REGEX = /^```(\w*).*?\n(.*?)^```/m
+      TABS_BLOCK_REGEX = /^:::[ \t]*tabs[ \t]*\n.*?^:::[ \t]*$/m
+
+      def preprocess(content)
+        context[:code_block_focus_lines] ||= []
+        @block_index = 0
+        @tabs_ranges = find_tabs_ranges(content)
+
+        content.gsub(CODE_BLOCK_REGEX) { |_| process_code_block(Regexp.last_match) }
+      end
+
+      private
+
+      def process_code_block(match)
+        return match[0] if inside_tabs?(match.begin(0))
+
+        focus_info = extract_focus_lines(match[2])
+        context[:code_block_focus_lines][@block_index] = focus_info[:lines]
+        @block_index += 1
+        match[0].sub(match[2], focus_info[:cleaned_content])
+      end
+
+      def extract_focus_lines(code_content)
+        lines = code_content.lines
+        focus_lines = {}
+        cleaned_lines = []
+
+        lines.each_with_index do |line, index|
+          line_num = index + 1
+
+          if line.match?(FOCUS_MARKER_PATTERN)
+            focus_lines[line_num] = true
+            cleaned_line = line.gsub(FOCUS_MARKER_PATTERN, "")
+            cleaned_lines << cleaned_line
+          else
+            cleaned_lines << line
+          end
+        end
+
+        { lines: focus_lines, cleaned_content: cleaned_lines.join }
+      end
+
+      def inside_tabs?(position)
+        @tabs_ranges.any? { |range| range.cover?(position) }
+      end
+
+      def find_tabs_ranges(content)
+        ranges = []
+        content.scan(TABS_BLOCK_REGEX) do
+          match = Regexp.last_match
+          ranges << (match.begin(0)...match.end(0))
+        end
+        ranges
+      end
+    end
+  end
+end

data/lib/docyard/components/code_block_icon_detector.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "../language_mapping"
+
+module Docyard
+  module Components
+    module CodeBlockIconDetector
+      MANUAL_ICON_PATTERN = /^:([a-z0-9-]+):\s*(.+)$/i
+
+      module_function
+
+      def detect(title, language)
+        return { title: nil, icon: nil, icon_source: nil } if title.nil?
+
+        if (match = title.match(MANUAL_ICON_PATTERN))
+          return {
+            title: match[2].strip,
+            icon: match[1],
+            icon_source: "phosphor"
+          }
+        end
+
+        icon, icon_source = auto_detect_icon(language)
+        { title: title, icon: icon, icon_source: icon_source }
+      end
+
+      def auto_detect_icon(language)
+        return [nil, nil] if language.nil?
+
+        if LanguageMapping.terminal_language?(language)
+          %w[terminal-window phosphor]
+        elsif (ext = LanguageMapping.extension_for(language))
+          [ext, "file-extension"]
+        else
+          %w[file phosphor]
+        end
+      end
+    end
+  end
+end

data/lib/docyard/components/code_block_line_wrapper.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "code_line_parser"
+
+module Docyard
+  module Components
+    module CodeBlockLineWrapper
+      module_function
+
+      def wrap_code_block(html, block_data)
+        html.gsub(%r{<pre[^>]*><code[^>]*>(.*?)</code></pre>}m) do
+          pre_match = Regexp.last_match(0)
+          code_content = Regexp.last_match(1)
+          lines = CodeLineParser.new(code_content).parse
+          wrapped_lines = wrap_lines_with_classes(lines, block_data)
+          pre_match.sub(code_content, wrapped_lines.join)
+        end
+      end
+
+      def wrap_lines_with_classes(lines, block_data)
+        lines.each_with_index.map do |line, index|
+          source_line = index + 1
+          display_line = block_data[:start_line] + index
+          classes = build_line_classes(source_line, display_line, block_data)
+          %(<span class="#{classes}">#{line}</span>)
+        end
+      end
+
+      DIFF_CLASSES = { addition: "docyard-code-line--diff-add", deletion: "docyard-code-line--diff-remove" }.freeze
+
+      def build_line_classes(source_line, display_line, block_data)
+        (["docyard-code-line"] + feature_classes(source_line, display_line, block_data)).join(" ")
+      end
+
+      def feature_classes(source_line, display_line, block_data)
+        [
+          ("docyard-code-line--highlighted" if block_data[:highlights].include?(display_line)),
+          DIFF_CLASSES[block_data[:diff_lines][source_line]],
+          ("docyard-code-line--focus" if block_data[:focus_lines][source_line]),
+          ("docyard-code-line--error" if block_data[:error_lines][source_line]),
+          ("docyard-code-line--warning" if block_data[:warning_lines][source_line])
+        ].compact
+      end
+    end
+  end
+end

data/lib/docyard/components/code_block_options_preprocessor.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "base_processor"
+
+module Docyard
+  module Components
+    class CodeBlockOptionsPreprocessor < BaseProcessor
+      self.priority = 5
+
+      CODE_FENCE_REGEX = /^```(\w+)(?:\s*\[([^\]]+)\])?(:\S+)?(?:\s*\{([^}\n]+)\})?/
+      TABS_BLOCK_REGEX = /^:::[ \t]*tabs[ \t]*\n.*?^:::[ \t]*$/m
+
+      def preprocess(content)
+        context[:code_block_options] ||= []
+        @tabs_ranges = find_tabs_ranges(content)
+
+        process_code_fences(content)
+      end
+
+      private
+
+      def process_code_fences(content)
+        result = +""
+        last_end = 0
+
+        content.scan(CODE_FENCE_REGEX) do
+          match = Regexp.last_match
+          result << content[last_end...match.begin(0)]
+          result << process_fence_match(match)
+          last_end = match.end(0)
+        end
+
+        result << content[last_end..]
+      end
+
+      def process_fence_match(match)
+        store_code_block_options(match) unless inside_tabs?(match.begin(0))
+        "```#{match[1]}"
+      end
+
+      def store_code_block_options(match)
+        context[:code_block_options] << {
+          lang: match[1],
+          title: match[2],
+          option: match[3],
+          highlights: parse_highlights(match[4])
+        }
+      end
+
+      def inside_tabs?(position)
+        @tabs_ranges.any? { |range| range.cover?(position) }
+      end
+
+      def find_tabs_ranges(content)
+        ranges = []
+        content.scan(TABS_BLOCK_REGEX) do
+          match = Regexp.last_match
+          ranges << (match.begin(0)...match.end(0))
+        end
+        ranges
+      end
+
+      def parse_highlights(highlights_str)
+        return [] if highlights_str.nil? || highlights_str.strip.empty?
+
+        highlights_str.split(",").flat_map { |part| parse_highlight_part(part.strip) }.uniq.sort
+      end
+
+      def parse_highlight_part(part)
+        return (part.split("-")[0].to_i..part.split("-")[1].to_i).to_a if part.include?("-")
+
+        [part.to_i]
+      end
+    end
+  end
+end

data/lib/docyard/components/code_block_patterns.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Components
+    module CodeBlockPatterns
+      DIFF_MARKER_PATTERN = %r{
+        (?:
+          //\s*\[!code\s*([+-]{2})\]              |
+          \#\s*\[!code\s*([+-]{2})\]              |
+          /\*\s*\[!code\s*([+-]{2})\]\s*\*/       |
+          --\s*\[!code\s*([+-]{2})\]              |
+          <!--\s*\[!code\s*([+-]{2})\]\s*-->      |
+          ;\s*\[!code\s*([+-]{2})\]
+        )[^\S\n]*
+      }x
+
+      FOCUS_MARKER_PATTERN = %r{
+        (?:
+          //\s*\[!code\s+focus\]              |
+          \#\s*\[!code\s+focus\]              |
+          /\*\s*\[!code\s+focus\]\s*\*/       |
+          --\s*\[!code\s+focus\]              |
+          <!--\s*\[!code\s+focus\]\s*-->      |
+          ;\s*\[!code\s+focus\]
+        )[^\S\n]*
+      }x
+
+      ERROR_MARKER_PATTERN = %r{
+        (?:
+          //\s*\[!code\s+error\]              |
+          \#\s*\[!code\s+error\]              |
+          /\*\s*\[!code\s+error\]\s*\*/       |
+          --\s*\[!code\s+error\]              |
+          <!--\s*\[!code\s+error\]\s*-->      |
+          ;\s*\[!code\s+error\]
+        )[^\S\n]*
+      }x
+
+      WARNING_MARKER_PATTERN = %r{
+        (?:
+          //\s*\[!code\s+warning\]              |
+          \#\s*\[!code\s+warning\]              |
+          /\*\s*\[!code\s+warning\]\s*\*/       |
+          --\s*\[!code\s+warning\]              |
+          <!--\s*\[!code\s+warning\]\s*-->      |
+          ;\s*\[!code\s+warning\]
+        )[^\S\n]*
+      }x
+    end
+  end
+end