docyard 0.8.0 → 1.0.0

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

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require_relative "../base_processor"
+require_relative "../support/markdown_code_block_helper"
+
+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"
+          %(<i class="ph ph-#{icon_name}" aria-hidden="true"></i>)
+        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/icon_processor.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "../../rendering/icons"
 require_relative "../base_processor"
 
 module Docyard
@@ -10,6 +9,7 @@ module Docyard
         self.priority = 20
 
         ICON_PATTERN = /:([a-z][a-z0-9-]*):(?:([a-z]+):)?/i
+        VALID_WEIGHTS = %w[regular bold fill light thin duotone].freeze
 
         def postprocess(html)
           segments = split_preserving_code_blocks(html)
@@ -44,9 +44,15 @@ module Docyard
           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)
+            render_icon(icon_name, weight)
           end
         end
+
+        def render_icon(name, weight)
+          weight = "regular" unless VALID_WEIGHTS.include?(weight)
+          weight_class = weight == "regular" ? "ph" : "ph-#{weight}"
+          %(<i class="#{weight_class} ph-#{name}" aria-hidden="true"></i>)
+        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"
+
+          process_outside_code_blocks(content) do |segment|
+            process_includes(segment, Set.new)
+          end
+        end
+
+        private
+
+        def process_includes(content, included_files)
+          content.gsub(INCLUDE_PATTERN) { |_| process_include(Regexp.last_match, included_files) }
+        end
+
+        def process_include(match, included_files)
+          filepath = match[1]
+          full_path = resolve_path(filepath)
+
+          error = validate_include(filepath, full_path, included_files)
+          return error if error
+
+          updated_included_files = included_files.dup.add(full_path)
+          file_content = File.read(full_path)
+
+          process_includes(file_content.strip, updated_included_files)
+        end
+
+        def validate_include(filepath, full_path, included_files)
+          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)
+          Docyard.logger.warn("Include failed: #{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

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

@@ -2,6 +2,7 @@
 
 require_relative "../../rendering/renderer"
 require_relative "../base_processor"
+require_relative "../support/markdown_code_block_helper"
 require_relative "../support/tabs/parser"
 require "securerandom"
 
@@ -9,6 +10,8 @@ module Docyard
   module Components
     module Processors
       class TabsProcessor < BaseProcessor
+        include Support::MarkdownCodeBlockHelper
+
         self.priority = 15
 
         TabsParser = Support::Tabs::Parser
@@ -16,8 +19,13 @@ module Docyard
         def preprocess(content)
           return content unless content.include?(":::tabs")
 
+          @code_block_ranges = find_code_block_ranges(content)
+
           content.gsub(/^:::[ \t]*tabs[ \t]*\n(.*?)^:::[ \t]*$/m) do
-            process_tabs_block(Regexp.last_match(1))
+            match = Regexp.last_match
+            next match[0] if inside_code_block?(match.begin(0), @code_block_ranges)
+
+            process_tabs_block(match[1])
           end
         end
 

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "../base_processor"
+require_relative "../support/markdown_code_block_helper"
+
+module Docyard
+  module Components
+    module Processors
+      class TooltipProcessor < BaseProcessor
+        include Support::MarkdownCodeBlockHelper
+
+        TOOLTIP_PATTERN = /:tooltip\[([^\]]+)\]\{([^}]+)\}/
+        self.priority = 6
+
+        def preprocess(content)
+          process_outside_code_blocks(content) do |segment|
+            segment.gsub(TOOLTIP_PATTERN) do |_match|
+              term = ::Regexp.last_match(1)
+              attributes = parse_attributes(::Regexp.last_match(2))
+              build_tooltip_tag(term, attributes)
+            end
+          end
+        end
+
+        private
+
+        def parse_attributes(attr_string)
+          attributes = {}
+          attr_string.scan(/(\w+)="([^"]*)"/) do |key, value|
+            attributes[key.to_sym] = value
+          end
+          attributes
+        end
+
+        def build_tooltip_tag(term, attributes)
+          description = escape_html(attributes[:description] || "")
+          link = attributes[:link]
+          link_text = attributes[:link_text] || "Learn more"
+
+          data_attrs = %(data-description="#{description}")
+          data_attrs += %( data-link="#{escape_html(link)}") if link
+          data_attrs += %( data-link-text="#{escape_html(link_text)}") if link
+
+          %(<span class="docyard-tooltip" #{data_attrs}>#{term}</span>)
+        end
+
+        def escape_html(text)
+          text.to_s
+            .gsub("&", "&amp;")
+            .gsub("<", "&lt;")
+            .gsub(">", "&gt;")
+            .gsub('"', "&quot;")
+        end
+      end
+    end
+  end
+end