docyard 0.8.0 → 1.0.0

data/lib/docyard/components/processors/cards_processor.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative "../../rendering/icons"
+require_relative "../../rendering/renderer"
+require_relative "../base_processor"
+require_relative "../support/markdown_code_block_helper"
+require "kramdown"
+require "kramdown-parser-gfm"
+
+module Docyard
+  module Components
+    module Processors
+      class CardsProcessor < BaseProcessor
+        include Support::MarkdownCodeBlockHelper
+
+        self.priority = 10
+
+        CARDS_PATTERN = /^:::cards\s*\n(.*?)^:::\s*$/m
+        CARD_PATTERN = /^::card\{([^}]*)\}\s*\n(.*?)^::\s*$/m
+
+        def preprocess(markdown)
+          @code_block_ranges = find_code_block_ranges(markdown)
+
+          markdown.gsub(CARDS_PATTERN) do
+            match = Regexp.last_match
+            next match[0] if inside_code_block?(match.begin(0), @code_block_ranges)
+
+            content = match[1]
+            cards = parse_cards(content)
+
+            wrap_in_nomarkdown(render_cards_html(cards))
+          end
+        end
+
+        private
+
+        def parse_cards(content)
+          cards = []
+
+          content.scan(CARD_PATTERN) do |attrs_string, card_content|
+            attrs = parse_attributes(attrs_string)
+            cards << {
+              title: attrs["title"] || "Card",
+              icon: attrs["icon"],
+              href: attrs["href"],
+              content: card_content.strip
+            }
+          end
+
+          cards
+        end
+
+        def parse_attributes(attr_string)
+          return {} if attr_string.nil? || attr_string.empty?
+
+          attrs = {}
+          attr_string.scan(/(\w+)="([^"]*)"/) do |key, value|
+            attrs[key] = value
+          end
+          attrs
+        end
+
+        def render_cards_html(cards)
+          renderer = Renderer.new
+
+          cards_html = cards.map do |card|
+            icon_svg = card[:icon] ? Icons.render(card[:icon]) : nil
+            content_html = render_markdown_content(card[:content])
+
+            renderer.render_partial(
+              "_card", {
+                title: card[:title],
+                icon_svg: icon_svg,
+                href: card[:href],
+                content_html: content_html
+              }
+            )
+          end.join("\n")
+
+          "<div class=\"docyard-cards\">\n#{cards_html}\n</div>"
+        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
+      end
+    end
+  end
+end

data/lib/docyard/components/processors/code_block_extended_fence_postprocessor.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "../base_processor"
+
+module Docyard
+  module Components
+    module Processors
+      # Restores placeholders after all code block processing.
+      # Runs after CodeBlockProcessor to ensure the HTML is fully rendered.
+      class CodeBlockExtendedFencePostprocessor < BaseProcessor
+        self.priority = 25
+
+        BACKTICK_PLACEHOLDER = "\u200B\u200B\u200B"
+        CODE_MARKER_PLACEHOLDER = "\u200B!\u200Bcode"
+
+        def postprocess(html)
+          html
+            .gsub(BACKTICK_PLACEHOLDER, "`")
+            .gsub(CODE_MARKER_PLACEHOLDER, "[!code")
+        end
+      end
+    end
+  end
+end

data/lib/docyard/components/processors/code_block_extended_fence_preprocessor.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "../base_processor"
+
+module Docyard
+  module Components
+    module Processors
+      # Handles 4+ backtick code fences (extended fences) for showing raw syntax.
+      # Escapes special markers so they display as raw text instead of being processed.
+      # Example: ```` (4 backticks) wrapping ```js shows the raw markdown syntax.
+      class CodeBlockExtendedFencePreprocessor < BaseProcessor
+        self.priority = 1
+
+        # Match 4+ backticks, capture language, content, and closing backticks
+        EXTENDED_FENCE_REGEX = /^(`{4,})(\w*)[^\n]*\n(.*?)^\1/m
+
+        # Placeholders using zero-width spaces
+        BACKTICK_PLACEHOLDER = "\u200B\u200B\u200B"
+        CODE_MARKER_PLACEHOLDER = "\u200B!\u200Bcode"
+
+        def preprocess(content)
+          content.gsub(EXTENDED_FENCE_REGEX) { |_| process_extended_fence(Regexp.last_match) }
+        end
+
+        private
+
+        def process_extended_fence(match)
+          lang = match[2]
+          code = match[3].chomp
+
+          # Replace backticks and code markers with placeholders
+          # This prevents other preprocessors from matching/processing them
+          escaped_code = code
+            .gsub("`", BACKTICK_PLACEHOLDER)
+            .gsub("[!code", CODE_MARKER_PLACEHOLDER)
+
+          # Output as regular 3-backtick fence so it goes through normal processing
+          lang_spec = lang.empty? ? "text" : lang
+          "```#{lang_spec}\n#{escaped_code}\n```"
+        end
+      end
+    end
+  end
+end

data/lib/docyard/components/processors/code_block_options_preprocessor.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../base_processor"
+require_relative "../../rendering/icons"
 
 module Docyard
   module Components
@@ -10,10 +11,13 @@ module Docyard
 
         CODE_FENCE_REGEX = /^```(\w+)(?:\s*\[([^\]]+)\])?(:\S+)?(?:\s*\{([^}\n]+)\})?/
         TABS_BLOCK_REGEX = /^:::[ \t]*tabs[ \t]*\n.*?^:::[ \t]*$/m
+        CODE_GROUP_BLOCK_REGEX = /^:::[ \t]*code-group[ \t]*\n.*?^:::[ \t]*$/m
+        EXCLUDED_LANGUAGES = %w[filetree].freeze
 
         def preprocess(content)
           context[:code_block_options] ||= []
           @tabs_ranges = find_tabs_ranges(content)
+          @code_group_ranges = find_code_group_ranges(content)
 
           process_code_fences(content)
         end
@@ -35,8 +39,27 @@ module Docyard
         end
 
         def process_fence_match(match)
-          store_code_block_options(match) unless inside_tabs?(match.begin(0))
-          "```#{match[1]}"
+          position = match.begin(0)
+          return match[0] if inside_special_block?(position)
+
+          original_lang = match[1]
+          return match[0] if excluded_language?(original_lang)
+
+          store_code_block_options(match)
+          highlight_lang = Icons.highlight_language(original_lang)
+          "```#{highlight_lang}"
+        end
+
+        def excluded_language?(lang)
+          EXCLUDED_LANGUAGES.include?(lang&.downcase)
+        end
+
+        def inside_special_block?(position)
+          inside_tabs?(position) || inside_code_group?(position)
+        end
+
+        def inside_code_group?(position)
+          @code_group_ranges.any? { |range| range.cover?(position) }
         end
 
         def store_code_block_options(match)
@@ -53,8 +76,16 @@ module Docyard
         end
 
         def find_tabs_ranges(content)
+          find_block_ranges(content, TABS_BLOCK_REGEX)
+        end
+
+        def find_code_group_ranges(content)
+          find_block_ranges(content, CODE_GROUP_BLOCK_REGEX)
+        end
+
+        def find_block_ranges(content, regex)
           ranges = []
-          content.scan(TABS_BLOCK_REGEX) do
+          content.scan(regex) do
             match = Regexp.last_match
             ranges << (match.begin(0)...match.end(0))
           end

data/lib/docyard/components/processors/code_block_processor.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
 require_relative "../../rendering/icons"
-require_relative "../../rendering/language_mapping"
 require_relative "../../rendering/renderer"
 require_relative "../base_processor"
 require_relative "../support/code_block/icon_detector"
 require_relative "../support/code_block/line_wrapper"
+require_relative "../support/code_block/line_number_resolver"
 require_relative "../support/tabs/range_finder"
 
 module Docyard
@@ -18,6 +18,7 @@ module Docyard
         self.priority = 20
 
         CodeBlockIconDetector = Support::CodeBlock::IconDetector
+        LineNumbers = Support::CodeBlock::LineNumberResolver
         TabsRangeFinder = Support::Tabs::RangeFinder
 
         def postprocess(html)
@@ -36,7 +37,6 @@ module Docyard
           @focus_lines = context[:code_block_focus_lines] || []
           @error_lines = context[:code_block_error_lines] || []
           @warning_lines = context[:code_block_warning_lines] || []
-          @global_line_numbers = context.dig(:config, "markdown", "lineNumbers") || false
           @tabs_ranges = TabsRangeFinder.find_ranges(html)
         end
 
@@ -67,15 +67,21 @@ module Docyard
         def process_code_block(original_html, inner_html)
           block_data = extract_block_data(inner_html)
           processed_html = process_html_for_highlighting(original_html, block_data)
+          processed_html = inject_scroll_spacer(processed_html) unless block_data[:title]
 
           render_code_block_with_copy(block_data.merge(html: processed_html))
         end
 
+        def inject_scroll_spacer(html)
+          spacer = '<span class="docyard-code-block__scroll-spacer" aria-hidden="true"></span>'
+          html.sub("\n", "#{spacer}\n")
+        end
+
         def extract_block_data(inner_html)
           opts = current_block_options
           code_text = extract_code_text(inner_html)
-          start_line = extract_start_line(opts[:option])
-          show_line_numbers = determine_line_numbers(opts[:option])
+          start_line = LineNumbers.start_line(opts[:option])
+          show_line_numbers = LineNumbers.enabled?(opts[:option])
           title_data = CodeBlockIconDetector.detect(opts[:title], opts[:lang])
 
           build_block_data(code_text, opts, show_line_numbers, start_line, title_data)
@@ -100,7 +106,7 @@ module Docyard
             error_lines: @error_lines[@block_index] || {},
             warning_lines: @warning_lines[@block_index] || {},
             show_line_numbers: show_line_numbers,
-            line_numbers: show_line_numbers ? generate_line_numbers(code_text, start_line) : [],
+            line_numbers: show_line_numbers ? LineNumbers.generate_numbers(code_text, start_line) : [],
             start_line: start_line,
             title: title_data[:title],
             icon: title_data[:icon],
@@ -117,25 +123,6 @@ module Docyard
           wrap_code_block(original_html, block_data)
         end
 
-        def determine_line_numbers(block_option)
-          return false if block_option == ":no-line-numbers"
-          return true if block_option&.start_with?(":line-numbers")
-
-          @global_line_numbers
-        end
-
-        def extract_start_line(block_option)
-          return 1 unless block_option&.include?("=")
-
-          block_option.split("=").last.to_i
-        end
-
-        def generate_line_numbers(code_text, start_line)
-          line_count = code_text.lines.count
-          line_count = 1 if line_count.zero?
-          (start_line...(start_line + line_count)).to_a
-        end
-
         def inside_tabs?(position)
           @tabs_ranges.any? { |range| range.cover?(position) }
         end

data/lib/docyard/components/processors/code_group_processor.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require_relative "../base_processor"
+require_relative "../support/code_block/feature_extractor"
+require_relative "../support/code_block/line_wrapper"
+require_relative "../support/code_block/line_number_resolver"
+require_relative "../support/code_group/html_builder"
+require_relative "../support/markdown_code_block_helper"
+require_relative "../../rendering/icons"
+require_relative "../../rendering/renderer"
+require "securerandom"
+require "kramdown"
+require "kramdown-parser-gfm"
+require "cgi"
+
+module Docyard
+  module Components
+    module Processors
+      class CodeGroupProcessor < BaseProcessor
+        include Utils::HtmlHelpers
+        include Support::MarkdownCodeBlockHelper
+
+        self.priority = 12
+
+        CODE_GROUP_PATTERN = /^:::[ \t]*code-group[ \t]*\n(.*?)^:::[ \t]*$/m
+        CODE_BLOCK_PATTERN = /```(\w*)\s*\[([^\]]+)\]([^\n]*)\n(.*?)```/m
+
+        CodeBlockFeatureExtractor = Support::CodeBlock::FeatureExtractor
+        CodeBlockLineWrapper = Support::CodeBlock::LineWrapper
+        LineNumbers = Support::CodeBlock::LineNumberResolver
+        CodeGroupHtmlBuilder = Support::CodeGroup::HtmlBuilder
+
+        def preprocess(content)
+          return content unless content.include?(":::code-group")
+
+          @code_block_ranges = find_code_block_ranges(content)
+
+          content.gsub(CODE_GROUP_PATTERN) do
+            match = ::Regexp.last_match
+            next match[0] if inside_code_block?(match.begin(0), @code_block_ranges)
+
+            process_code_group(match[1])
+          end
+        end
+
+        private
+
+        def process_code_group(inner_content)
+          blocks = extract_code_blocks(inner_content)
+          return "" if blocks.empty?
+
+          group_id = SecureRandom.hex(4)
+          html = CodeGroupHtmlBuilder.new(blocks, group_id).build
+          wrap_in_nomarkdown(html)
+        end
+
+        def extract_code_blocks(content)
+          blocks = []
+          content.scan(CODE_BLOCK_PATTERN) do
+            blocks << build_block_data(::Regexp.last_match)
+          end
+          blocks
+        end
+
+        def build_block_data(match)
+          lang = match[1] || ""
+          label = match[2]
+          options = match[3].strip
+          code = match[4]
+
+          code_with_newline = code.end_with?("\n") ? code : "#{code}\n"
+          markdown = "```#{lang}#{format_options(options)}\n#{code_with_newline}```"
+          extracted = CodeBlockFeatureExtractor.process_markdown(markdown)
+          rendered = render_and_enhance(extracted)
+
+          { label: label, lang: lang, content: rendered, code_text: code.strip }
+        end
+
+        def format_options(options)
+          return "" if options.empty?
+          return options if options.start_with?(":")
+
+          " #{options}"
+        end
+
+        def render_and_enhance(extracted)
+          html = render_markdown(extracted[:cleaned_markdown])
+          enhance_code_blocks(html, extracted[:blocks])
+        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
+
+        def enhance_code_blocks(html, blocks)
+          return html unless html.include?('<div class="highlight">')
+
+          block_index = 0
+          html.gsub(%r{<div class="highlight">(.*?)</div>}m) do
+            block_data = blocks[block_index] || {}
+            block_index += 1
+            render_enhanced_code_block(Regexp.last_match, block_data)
+          end
+        end
+
+        def render_enhanced_code_block(match, block_data)
+          original_html = match[0]
+          inner_html = match[1]
+          code_text = extract_code_text(inner_html)
+
+          processed_html = process_html_if_needed(original_html, block_data)
+          Renderer.new.render_partial("_code_block", build_locals(processed_html, code_text, block_data))
+        end
+
+        def process_html_if_needed(original_html, block_data)
+          return original_html unless needs_line_wrapping?(block_data)
+
+          CodeBlockLineWrapper.wrap_code_block(original_html, wrapper_data(block_data))
+        end
+
+        def needs_line_wrapping?(block_data)
+          %i[highlights diff_lines focus_lines error_lines warning_lines].any? do |key|
+            block_data[key]&.any?
+          end
+        end
+
+        def wrapper_data(block_data)
+          {
+            highlights: block_data[:highlights] || [],
+            diff_lines: block_data[:diff_lines] || {},
+            focus_lines: block_data[:focus_lines] || {},
+            error_lines: block_data[:error_lines] || {},
+            warning_lines: block_data[:warning_lines] || {},
+            start_line: LineNumbers.start_line(block_data[:option])
+          }
+        end
+
+        def build_locals(processed_html, code_text, block_data)
+          base_locals(processed_html, code_text, block_data).merge(feature_locals(block_data)).merge(title_locals)
+        end
+
+        def base_locals(processed_html, code_text, block_data)
+          show_ln = LineNumbers.enabled?(block_data[:option])
+          start = LineNumbers.start_line(block_data[:option])
+
+          {
+            code_block_html: processed_html, code_text: escape_html_attribute(code_text),
+            copy_icon: Icons.render("copy", "regular") || "", show_line_numbers: show_ln,
+            line_numbers: show_ln ? LineNumbers.generate_numbers(code_text, start) : [], start_line: start
+          }
+        end
+
+        def feature_locals(block_data)
+          {
+            highlights: block_data[:highlights] || [], diff_lines: block_data[:diff_lines] || {},
+            focus_lines: block_data[:focus_lines] || {}, error_lines: block_data[:error_lines] || {},
+            warning_lines: block_data[:warning_lines] || {}
+          }
+        end
+
+        def title_locals
+          { title: nil, icon: nil, icon_source: nil }
+        end
+
+        def extract_code_text(html)
+          CGI.unescapeHTML(html.gsub(/<[^>]+>/, "")).strip
+        end
+
+        def wrap_in_nomarkdown(html)
+          "{::nomarkdown}\n#{html}\n{:/nomarkdown}"
+        end
+      end
+    end
+  end
+end

data/lib/docyard/components/processors/code_snippet_import_preprocessor.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 require_relative "../base_processor"
+require_relative "../support/markdown_code_block_helper"
 
 module Docyard
   module Components
     module Processors
       class CodeSnippetImportPreprocessor < BaseProcessor
+        include Support::MarkdownCodeBlockHelper
+
         EXTENSION_MAP = {
           "rb" => "ruby",
           "js" => "javascript",
@@ -25,7 +28,9 @@ module Docyard
 
         def preprocess(content)
           @docs_root = context[:docs_root] || "docs"
-          content.gsub(IMPORT_PATTERN) { |_| process_import(Regexp.last_match) }
+          process_outside_code_blocks(content) do |segment|
+            segment.gsub(IMPORT_PATTERN) { |_| process_import(Regexp.last_match) }
+          end
         end
 
         private
@@ -119,6 +124,7 @@ module Docyard
         end
 
         def import_error(filepath, message)
+          Docyard.logger.warn("Code snippet import failed: #{filepath} - #{message}")
           "```\nError importing #{filepath}: #{message}\n```"
         end
       end

data/lib/docyard/components/processors/custom_anchor_processor.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "../base_processor"
+
+module Docyard
+  module Components
+    module Processors
+      class CustomAnchorProcessor < BaseProcessor
+        CUSTOM_ID_PATTERN = /\s*\{#([\w-]+)\}\s*$/
+
+        self.priority = 25
+
+        def postprocess(html)
+          process_custom_anchors(html)
+        end
+
+        private
+
+        def process_custom_anchors(html)
+          html.gsub(%r{<(h[1-6])(\s+id="[^"]*")?>(.+?)</\1>}m) do
+            tag = Regexp.last_match(1)
+            existing_attr = Regexp.last_match(2) || ""
+            content = Regexp.last_match(3)
+
+            if content.match?(CUSTOM_ID_PATTERN)
+              process_heading_with_custom_id(tag, content)
+            else
+              "<#{tag}#{existing_attr}>#{content}</#{tag}>"
+            end
+          end
+        end
+
+        def process_heading_with_custom_id(tag, content)
+          custom_id = content.match(CUSTOM_ID_PATTERN)[1]
+          clean_content = content.sub(CUSTOM_ID_PATTERN, "")
+
+          "<#{tag} id=\"#{custom_id}\">#{clean_content}</#{tag}>"
+        end
+      end
+    end
+  end
+end