docyard 0.8.0 → 0.9.0

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

@@ -0,0 +1,198 @@
+# 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_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
+        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: extract_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 = line_numbers_enabled?(block_data[:option])
+          start = extract_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 ? generate_line_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 line_numbers_enabled?(option)
+          return false if option == ":no-line-numbers"
+          return true if option&.start_with?(":line-numbers")
+
+          false
+        end
+
+        def extract_start_line(option)
+          return 1 unless option&.include?("=")
+
+          option.split("=").last.to_i
+        end
+
+        def generate_line_numbers(code_text, start_line)
+          count = [code_text.lines.count, 1].max
+          (start_line...(start_line + count)).to_a
+        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

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

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

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require_relative "../base_processor"
+require_relative "../support/markdown_code_block_helper"
+require_relative "../../rendering/icons"
+
+module Docyard
+  module Components
+    module Processors
+      class FileTreeProcessor < BaseProcessor
+        include Support::MarkdownCodeBlockHelper
+
+        FILETREE_PATTERN = /```filetree\n(.*?)```/m
+
+        self.priority = 8
+
+        def preprocess(content)
+          @code_block_ranges = find_code_block_ranges(content, exclude_language: "filetree")
+
+          content.gsub(FILETREE_PATTERN) do
+            match = Regexp.last_match
+            next match[0] if inside_code_block?(match.begin(0), @code_block_ranges)
+
+            build_file_tree(match[1])
+          end
+        end
+
+        private
+
+        def build_file_tree(content)
+          lines = content.lines.map(&:chomp).reject(&:empty?)
+
+          items = parse_tree_structure(lines)
+          html = render_tree(items)
+
+          "\n\n<div class=\"docyard-filetree\" markdown=\"0\">\n#{html}</div>\n\n"
+        end
+
+        def parse_tree_structure(lines)
+          root_items = []
+          stack = [{ indent: -1, children: root_items }]
+
+          lines.each { |line| process_line(line, stack) }
+
+          root_items
+        end
+
+        def process_line(line, stack)
+          indent = line[/\A */].length
+          name = line.strip
+          return if name.empty?
+
+          item = build_item(name, indent)
+          unwind_stack(stack, indent)
+          stack.last[:children] << item
+
+          add_folder_to_stack(item, indent, stack) if item[:type] == :folder
+        end
+
+        def build_item(name, indent)
+          item = parse_item(name)
+          item[:indent] = indent
+          item
+        end
+
+        def unwind_stack(stack, indent)
+          stack.pop while stack.length > 1 && stack.last[:indent] >= indent
+        end
+
+        def add_folder_to_stack(item, indent, stack)
+          item[:children] = []
+          stack.push({ indent: indent, children: item[:children] })
+        end
+
+        def parse_item(name)
+          highlighted = name.end_with?(" *")
+          name = name.chomp(" *") if highlighted
+
+          name, comment = extract_comment(name)
+          type = name.end_with?("/") ? :folder : :file
+          name = name.chomp("/") if type == :folder
+
+          { name: name, type: type, highlighted: highlighted, comment: comment }
+        end
+
+        def extract_comment(name)
+          return [name, nil] unless name.include?(" # ")
+
+          name.split(" # ", 2)
+        end
+
+        def render_tree(items, depth = 0)
+          return "" if items.empty?
+
+          html = "<ul class=\"docyard-filetree__list\">\n"
+          items.each { |item| html += render_item(item, depth) }
+          html += "</ul>\n"
+          html
+        end
+
+        def render_item(item, depth)
+          classes = item_classes(item)
+
+          html = "<li class=\"#{classes}\">\n"
+          html += render_entry(item)
+          html += render_tree(item[:children], depth + 1) if render_children?(item)
+          html += "</li>\n"
+          html
+        end
+
+        def item_classes(item)
+          classes = ["docyard-filetree__item", "docyard-filetree__item--#{item[:type]}"]
+          classes << "docyard-filetree__item--highlighted" if item[:highlighted]
+          classes.join(" ")
+        end
+
+        def render_entry(item)
+          html = "<span class=\"docyard-filetree__entry\">"
+          html += icon_for(item[:type])
+          html += "<span class=\"docyard-filetree__name\">#{escape_html(item[:name])}</span>"
+          html += render_comment(item[:comment])
+          html += "</span>"
+          html
+        end
+
+        def render_comment(comment)
+          return "" unless comment
+
+          "<span class=\"docyard-filetree__comment\">#{escape_html(comment)}</span>"
+        end
+
+        def render_children?(item)
+          item[:type] == :folder && item[:children] && !item[:children].empty?
+        end
+
+        def icon_for(type)
+          icon_name = type == :folder ? "folder-open" : "file-text"
+          Icons.render(icon_name)
+        end
+
+        def escape_html(text)
+          text.to_s
+            .gsub("&", "&amp;")
+            .gsub("<", "&lt;")
+            .gsub(">", "&gt;")
+            .gsub('"', "&quot;")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative "../base_processor"
+require_relative "../support/markdown_code_block_helper"
+
+module Docyard
+  module Components
+    module Processors
+      class ImageCaptionProcessor < BaseProcessor
+        include Support::MarkdownCodeBlockHelper
+
+        IMAGE_ATTRS_PATTERN = /!\[([^\]]*)\]\(([^)]+)\)\{([^}]+)\}/
+
+        self.priority = 5
+
+        def preprocess(content)
+          process_outside_code_blocks(content) do |segment|
+            process_images_with_attrs(segment)
+          end
+        end
+
+        private
+
+        def process_images_with_attrs(content)
+          content.gsub(IMAGE_ATTRS_PATTERN) do
+            alt = Regexp.last_match(1)
+            src = Regexp.last_match(2)
+            attrs_string = Regexp.last_match(3)
+
+            attrs = parse_attributes(attrs_string)
+            build_image_html(alt, src, attrs)
+          end
+        end
+
+        def parse_attributes(attrs_string)
+          attrs = {}
+
+          attrs_string.scan(/(\w+)="([^"]*)"/) do |key, value|
+            attrs[key] = value
+          end
+
+          attrs[:nozoom] = true if attrs_string.include?("nozoom")
+
+          attrs
+        end
+
+        def build_image_html(alt, src, attrs)
+          if attrs["caption"]
+            build_figure(alt, src, attrs)
+          else
+            build_img(alt, src, attrs)
+          end
+        end
+
+        def build_figure(alt, src, attrs)
+          "\n\n" \
+            "<figure class=\"docyard-figure\" markdown=\"0\">\n" \
+            "#{build_img_tag(alt, src, attrs)}\n" \
+            "<figcaption>#{escape_html(attrs['caption'])}</figcaption>\n" \
+            "</figure>" \
+            "\n\n"
+        end
+
+        def build_img(alt, src, attrs)
+          "\n\n#{build_img_tag(alt, src, attrs)}\n\n"
+        end
+
+        def build_img_tag(alt, src, attrs)
+          parts = base_img_attrs(alt, src)
+          parts.concat(dimension_attrs(attrs))
+          parts << "data-no-zoom" if attrs[:nozoom]
+          "<img #{parts.join(' ')}>"
+        end
+
+        def base_img_attrs(alt, src)
+          ["src=\"#{escape_html(src)}\"", "alt=\"#{escape_html(alt)}\""]
+        end
+
+        def dimension_attrs(attrs)
+          result = []
+          result << "width=\"#{escape_html(attrs['width'])}\"" if attrs["width"]
+          result << "height=\"#{escape_html(attrs['height'])}\"" if attrs["height"]
+          result
+        end
+
+        def escape_html(text)
+          text.to_s
+            .gsub("&", "&amp;")
+            .gsub("<", "&lt;")
+            .gsub(">", "&gt;")
+            .gsub('"', "&quot;")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "../base_processor"
+require_relative "../support/markdown_code_block_helper"
+
+module Docyard
+  module Components
+    module Processors
+      class IncludeProcessor < BaseProcessor
+        include Support::MarkdownCodeBlockHelper
+
+        INCLUDE_PATTERN = /<!--\s*@include:\s*([^\s]+)\s*-->/
+
+        self.priority = 0
+
+        def preprocess(content)
+          @current_file = context[:current_file]
+          @docs_root = context[:docs_root] || "docs"
+          @included_files = Set.new
+
+          process_outside_code_blocks(content) do |segment|
+            process_includes(segment)
+          end
+        end
+
+        private
+
+        def process_includes(content)
+          content.gsub(INCLUDE_PATTERN) { |_| process_include(Regexp.last_match) }
+        end
+
+        def process_include(match)
+          filepath = match[1]
+          full_path = resolve_path(filepath)
+
+          error = validate_include(filepath, full_path)
+          return error if error
+
+          @included_files.add(full_path)
+          file_content = File.read(full_path)
+
+          process_includes(file_content.strip)
+        end
+
+        def validate_include(filepath, full_path)
+          return include_error(filepath, "File not found") unless full_path && File.exist?(full_path)
+          return include_error(filepath, "Circular include detected") if @included_files.include?(full_path)
+          return include_error(filepath, "Use code snippets for non-markdown files") unless markdown_file?(filepath)
+
+          nil
+        end
+
+        def resolve_path(filepath)
+          if filepath.start_with?("./", "../")
+            resolve_relative_path(filepath)
+          else
+            resolve_docs_path(filepath)
+          end
+        end
+
+        def resolve_relative_path(filepath)
+          return nil unless @current_file
+
+          base_dir = File.dirname(@current_file)
+          full_path = File.expand_path(filepath, base_dir)
+
+          full_path if File.exist?(full_path)
+        end
+
+        def resolve_docs_path(filepath)
+          full_path = File.join(@docs_root, filepath)
+          full_path if File.exist?(full_path)
+        end
+
+        def markdown_file?(filepath)
+          ext = File.extname(filepath).downcase
+          %w[.md .markdown .mdx].include?(ext)
+        end
+
+        def include_error(filepath, message)
+          "> [!WARNING]\n> Include error: #{filepath} - #{message}\n"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+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 StepsProcessor < BaseProcessor
+        include Support::MarkdownCodeBlockHelper
+
+        self.priority = 10
+
+        STEPS_PATTERN = /^:::steps\s*\n(.*?)^:::\s*$/m
+        STEP_HEADING_PATTERN = /^###\s+(.+)$/
+
+        def preprocess(markdown)
+          @code_block_ranges = find_code_block_ranges(markdown)
+
+          markdown.gsub(STEPS_PATTERN) do
+            match = Regexp.last_match
+            next match[0] if inside_code_block?(match.begin(0), @code_block_ranges)
+
+            content = match[1]
+            steps = parse_steps(content)
+
+            wrap_in_nomarkdown(render_steps_html(steps))
+          end
+        end
+
+        private
+
+        def parse_steps(content)
+          steps = []
+          current_step = nil
+
+          content.lines.each do |line|
+            if line.match(STEP_HEADING_PATTERN)
+              steps << current_step if current_step
+              current_step = { title: Regexp.last_match(1).strip, content: "" }
+            elsif current_step
+              current_step[:content] += line
+            end
+          end
+
+          steps << current_step if current_step
+          steps
+        end
+
+        def render_steps_html(steps)
+          renderer = Renderer.new
+
+          steps_html = steps.map.with_index(1) do |step, index|
+            content_html = render_markdown_content(step[:content].strip)
+
+            renderer.render_partial(
+              "_step", {
+                number: index,
+                title: step[:title],
+                content_html: content_html,
+                is_last: index == steps.length
+              }
+            )
+          end.join("\n")
+
+          "<div class=\"docyard-steps\">\n#{steps_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