docyard 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77d317cd25d544eef47b5bdcecb0515b8937da93b347d39cac6fd1f87bb43b19
-  data.tar.gz: bf97d9449013ba8bf370682271990f64b2c2092bfdc9bf0deb99cf2b67056cc2
+  metadata.gz: 51b2adfdb7f77c4366592cc3eea5a160fc42f85f17e44593e9bf192c3b470b48
+  data.tar.gz: 439d82b762c7bc6f485ab627365522b7e202833fc841c6b8655fb28e1e9b3e55
 SHA512:
-  metadata.gz: 2e30597716798800240f4436c423284d1972fe5fa0abf1de8007b3279dde0a87ef32210cb830c84769c15db0c82e6c372337ae06baaecdb71fa866342c9697a3
-  data.tar.gz: f0ae1edf5937153c9ed3ccb1cc7c599c7f650e16470ad976ef0918c09bc030502ecf89dad6a8a7c79ee8055530b61a65d556bbfd147e08a86349a2475777ee54
+  metadata.gz: a66355efb4615ae4552aa8656e63078989cdec734f41670dc172936060954a065fefb1a2733e51494747ef0ab9a1dbee399b3c8f37daf2718e92ba03c315df9f
+  data.tar.gz: be3cea82f91b60cc7e7c35be142b6c2ccd9be4323cbf1c5190987b6ba6894d4c8da38f55c141abda43211a5ac2b70d38283e1b340d62071ee5c22c87c9c35a51

data/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-01-15
+
+### Added
+- **Accordions** - Collapsible content sections with `:::details{title="..."}` syntax (#62)
+- **Steps** - Numbered step-by-step instructions with `:::steps` syntax and vertical connector lines (#63)
+- **Cards** - Grid of linked content blocks with `:::cards` and `::card{title="" icon="" href=""}` syntax (#64)
+- **Badges** - Inline status indicators with `:badge[text]{type="success|warning|danger"}` syntax (#65)
+- **Sidebar Badges** - Navigation labels via frontmatter `sidebar.badge` and `sidebar.badge_type` (#66)
+- **Announcement Banner** - Dismissible top banner with optional action button via config (#56)
+- **Markdown Inclusion** - Include content from other files with `<!--@include: ./file.md-->` syntax (#57)
+- **Custom Anchor IDs** - Override auto-generated heading IDs with `## Heading {#custom-id}` syntax (#58)
+- **Image Captions** - Figure elements with captions using `![](image.png){caption="..."}` syntax (#59)
+- **Video Embeds** - YouTube and Vimeo embedding with `::youtube[ID]` and `::vimeo[ID]` syntax (#60)
+- **File Tree** - Display directory structures with icons using `filetree` code blocks (#67)
+- **Tooltips** - Inline hover definitions with `:tooltip[term]{description="..."}` syntax (#68)
+- **Abbreviations** - Auto-expanding terms with `*[TERM]: Definition` syntax (#68)
+- **Code Groups** - Tabbed code blocks with `:::code-group` syntax, syncs selection across page (#70)
+
+### Fixed
+- **Copy Button Overlap** - Repositioned copy button to prevent overlapping code content in non-titled blocks (#71)
+- **Code Fence Protection** - Preprocessors now skip content inside fenced code blocks, allowing documentation to show raw syntax examples (#72)
+
 ## [0.8.0] - 2026-01-13
 
 ### Added
@@ -140,7 +162,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.8.0...HEAD
+[Unreleased]: https://github.com/sanifhimani/docyard/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/sanifhimani/docyard/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/sanifhimani/docyard/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/sanifhimani/docyard/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/sanifhimani/docyard/compare/v0.5.0...v0.6.0

data/lib/docyard/components/aliases.rb

@@ -2,17 +2,29 @@
 
 module Docyard
   module Components
+    AbbreviationProcessor = Processors::AbbreviationProcessor
+    AccordionProcessor = Processors::AccordionProcessor
+    BadgeProcessor = Processors::BadgeProcessor
+    StepsProcessor = Processors::StepsProcessor
+    CardsProcessor = Processors::CardsProcessor
     CalloutProcessor = Processors::CalloutProcessor
     CodeBlockProcessor = Processors::CodeBlockProcessor
+    CodeGroupProcessor = Processors::CodeGroupProcessor
     CodeBlockDiffPreprocessor = Processors::CodeBlockDiffPreprocessor
     CodeBlockFocusPreprocessor = Processors::CodeBlockFocusPreprocessor
     CodeBlockOptionsPreprocessor = Processors::CodeBlockOptionsPreprocessor
     CodeSnippetImportPreprocessor = Processors::CodeSnippetImportPreprocessor
+    CustomAnchorProcessor = Processors::CustomAnchorProcessor
+    ImageCaptionProcessor = Processors::ImageCaptionProcessor
+    IncludeProcessor = Processors::IncludeProcessor
+    VideoEmbedProcessor = Processors::VideoEmbedProcessor
+    FileTreeProcessor = Processors::FileTreeProcessor
     HeadingAnchorProcessor = Processors::HeadingAnchorProcessor
     IconProcessor = Processors::IconProcessor
     TableOfContentsProcessor = Processors::TableOfContentsProcessor
     TableWrapperProcessor = Processors::TableWrapperProcessor
     TabsProcessor = Processors::TabsProcessor
+    TooltipProcessor = Processors::TooltipProcessor
 
     CodeDetector = Support::CodeDetector
     IconDetector = Support::Tabs::IconDetector

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "../base_processor"
+require_relative "../support/markdown_code_block_helper"
+
+module Docyard
+  module Components
+    module Processors
+      class AbbreviationProcessor < BaseProcessor
+        include Support::MarkdownCodeBlockHelper
+
+        DEFINITION_PATTERN = /^\*\[([^\]]+)\]:\s*(.+)$/
+        self.priority = 5
+
+        def preprocess(content)
+          abbreviations = extract_abbreviations_outside_code_blocks(content)
+          return content if abbreviations.empty?
+
+          process_outside_code_blocks(content) do |segment|
+            segment = remove_definitions(segment)
+            apply_abbreviations(segment, abbreviations)
+          end
+        end
+
+        private
+
+        def extract_abbreviations_outside_code_blocks(content)
+          abbreviations = {}
+          process_outside_code_blocks(content) do |segment|
+            segment.scan(DEFINITION_PATTERN) do |term, definition|
+              abbreviations[term] = definition.strip
+            end
+            segment
+          end
+          abbreviations
+        end
+
+        def remove_definitions(content)
+          content.gsub(/^[ \t]*\*\[([^\]]+)\]:\s*.+$\n?/, "")
+        end
+
+        def apply_abbreviations(content, abbreviations)
+          abbreviations.each do |term, definition|
+            pattern = build_term_pattern(term)
+            content = content.gsub(pattern) do |match|
+              build_abbr_tag(match, definition)
+            end
+          end
+          content
+        end
+
+        def build_term_pattern(term)
+          escaped = Regexp.escape(term)
+          /(?<![<\w])#{escaped}(?![>\w])/
+        end
+
+        def build_abbr_tag(term, definition)
+          escaped_definition = escape_html(definition)
+          %(<abbr class="docyard-abbr" data-definition="#{escaped_definition}">#{term}</abbr>)
+        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/accordion_processor.rb

@@ -0,0 +1,81 @@
+# 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 AccordionProcessor < BaseProcessor
+        include Support::MarkdownCodeBlockHelper
+
+        self.priority = 10
+
+        DETAILS_PATTERN = /^:::details(?:\{([^}]*)\})?\s*\n(.*?)^:::\s*$/m
+
+        def preprocess(markdown)
+          @code_block_ranges = find_code_block_ranges(markdown)
+
+          markdown.gsub(DETAILS_PATTERN) do
+            match = Regexp.last_match
+            next match[0] if inside_code_block?(match.begin(0), @code_block_ranges)
+
+            attributes = parse_attributes(match[1])
+            content_markdown = match[2]
+
+            title = attributes["title"] || "Details"
+            open = attributes.key?("open")
+            content_html = render_markdown_content(content_markdown.strip)
+
+            wrap_in_nomarkdown(render_accordion_html(title, content_html, open))
+          end
+        end
+
+        private
+
+        def parse_attributes(attr_string)
+          return {} if attr_string.nil? || attr_string.empty?
+
+          attrs = {}
+          attr_string.scan(/(\w+)(?:="([^"]*)")?/) do |key, value|
+            attrs[key] = value || true
+          end
+          attrs
+        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 render_accordion_html(title, content_html, open)
+          icon_svg = Icons.render("caret-right") || ""
+          renderer = Renderer.new
+
+          renderer.render_partial(
+            "_accordion", {
+              title: title,
+              content_html: content_html,
+              icon_svg: icon_svg,
+              open: open
+            }
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "../base_processor"
+
+module Docyard
+  module Components
+    module Processors
+      class BadgeProcessor < BaseProcessor
+        self.priority = 15
+
+        BADGE_PATTERN = /:badge\[([^\]]*)\](?:\{([^}]*)\})?/
+
+        VALID_TYPES = %w[default success warning danger].freeze
+
+        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(BADGE_PATTERN) do
+            text = Regexp.last_match(1)
+            attrs = Regexp.last_match(2)
+
+            render_badge(text, parse_attributes(attrs))
+          end
+        end
+
+        def parse_attributes(attrs_string)
+          return {} if attrs_string.nil? || attrs_string.empty?
+
+          attrs = {}
+          attrs_string.scan(/(\w+)=["'\u201C\u201D]([^"'\u201C\u201D]*)["'\u201C\u201D]/) do |key, value|
+            attrs[key] = value
+          end
+          attrs
+        end
+
+        def render_badge(text, attrs)
+          type = attrs["type"] || "default"
+          type = "default" unless VALID_TYPES.include?(type)
+
+          %(<span class="docyard-badge docyard-badge--#{type}">#{text}</span>)
+        end
+      end
+    end
+  end
+end

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

@@ -3,6 +3,7 @@
 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"
 
@@ -10,6 +11,8 @@ module Docyard
   module Components
     module Processors
       class CalloutProcessor < BaseProcessor
+        include Support::MarkdownCodeBlockHelper
+
         self.priority = 10
 
         CALLOUT_TYPES = {
@@ -29,6 +32,7 @@ module Docyard
         }.freeze
 
         def preprocess(markdown)
+          @code_block_ranges = find_code_block_ranges(markdown)
           process_container_syntax(markdown)
         end
 
@@ -40,8 +44,10 @@ module Docyard
 
         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))
+            match = Regexp.last_match
+            next match[0] if inside_code_block?(match.begin(0), @code_block_ranges)
+
+            process_callout_match(match[0], match[1], match[2], match[3])
           end
         end
 

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_options_preprocessor.rb

@@ -10,10 +10,12 @@ 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
 
         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,10 +37,21 @@ module Docyard
         end
 
         def process_fence_match(match)
-          store_code_block_options(match) unless inside_tabs?(match.begin(0))
+          position = match.begin(0)
+          return match[0] if inside_special_block?(position)
+
+          store_code_block_options(match)
           "```#{match[1]}"
         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)
           context[:code_block_options] << {
             lang: match[1],
@@ -53,8 +66,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

@@ -67,10 +67,16 @@ 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)