docyard 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4892fa130361d02f347660d81932135f00c71d339c28b292e7bfecbe46ededa0
-  data.tar.gz: 4697d95492f675b935db0dad134c11eb0d57f7aca611dd25c3e4e22bded9f031
+  metadata.gz: c329f7664eff5bca0fded133cdc29fffa5eea23f81a0183605ea1f038adfa819
+  data.tar.gz: 5f4c135cd6a7dc25140d8111940d6a2fda14c4c9b142adb3d0c8b8a2c91a8f30
 SHA512:
-  metadata.gz: 342e2e7f16c32da9da273b6325532ad8ee842d58304faf309a0e634be5f7c2d3a6a8c5eb0176b09e0b518a67150c25223b5ad3be9c67da90e974e4be9871e28e
-  data.tar.gz: 2f1b65cde20d044348908884fbfd0a185d47d6ef73d9fdd516e5f11792262700550bb70d6ec7523dc910dcaed864d2df51bf6f54480997092c63dfe926b6629d
+  metadata.gz: bb2ccd83fef6197381df0dee879b71005fa6745842c242bd2fe4e2622d172356f0919b165c63791d6999f04f1cf8715f4dc5338d6050203f5133345ad52fcd9a
+  data.tar.gz: 7a6ea46ba7dd06050e4157c018d158c904a9fbb86dcce352446a4b7d8c99199b641cd8094d5a5eb4074e59716df2abd3e30925fc19c8d4232f365a11d20524a5

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-02-22
+
+### Added
+- **Code Annotations** - Clickable inline markers in code blocks with popover explanations using `// (1)` syntax and a matching ordered list (#156)
+- **Variables** - Template variables with `{{ variable }}` syntax, defined in `docyard.yml` under `variables:` (#155)
+
+### Documentation
+- Added Code Annotations section to Code Blocks page
+- Added Variables page with usage examples and configuration reference
+
 ## [1.3.0] - 2026-02-17
 
 ### Added
@@ -275,7 +285,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/v1.3.0...HEAD
+[Unreleased]: https://github.com/sanifhimani/docyard/compare/v1.4.0...HEAD
+[1.4.0]: https://github.com/sanifhimani/docyard/compare/v1.3.0...v1.4.0
 [1.3.0]: https://github.com/sanifhimani/docyard/compare/v1.2.0...v1.3.0
 [1.2.0]: https://github.com/sanifhimani/docyard/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/sanifhimani/docyard/compare/v1.0.2...v1.1.0

data/lib/docyard/components/aliases.rb

@@ -10,6 +10,7 @@ module Docyard
     CalloutProcessor = Processors::CalloutProcessor
     CodeBlockProcessor = Processors::CodeBlockProcessor
     CodeGroupProcessor = Processors::CodeGroupProcessor
+    CodeBlockAnnotationPreprocessor = Processors::CodeBlockAnnotationPreprocessor
     CodeBlockDiffPreprocessor = Processors::CodeBlockDiffPreprocessor
     CodeBlockFocusPreprocessor = Processors::CodeBlockFocusPreprocessor
     CodeBlockOptionsPreprocessor = Processors::CodeBlockOptionsPreprocessor
@@ -25,6 +26,7 @@ module Docyard
     TableWrapperProcessor = Processors::TableWrapperProcessor
     TabsProcessor = Processors::TabsProcessor
     TooltipProcessor = Processors::TooltipProcessor
+    VariablesProcessor = Processors::VariablesProcessor
 
     CodeBlockFeatureExtractor = Support::CodeBlock::FeatureExtractor
     CodeBlockLineWrapper = Support::CodeBlock::LineWrapper

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

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "kramdown"
+require "kramdown-parser-gfm"
+require_relative "../base_processor"
+require_relative "../support/code_block/patterns"
+require_relative "../support/code_block/annotation_list_parser"
+
+module Docyard
+  module Components
+    module Processors
+      class CodeBlockAnnotationPreprocessor < BaseProcessor
+        include Support::CodeBlock::Patterns
+
+        self.priority = 8
+
+        CODE_BLOCK_REGEX = /^```(\w*).*?\n(.*?)^```/m
+        TABS_BLOCK_REGEX = /^:::tabs[ \t]*\n.*?^:::[ \t]*$/m
+        CODE_GROUP_REGEX = /^:::code-group[ \t]*\n.*?^:::[ \t]*$/m
+
+        ListParser = Support::CodeBlock::AnnotationListParser
+
+        def preprocess(content)
+          initialize_state
+          @skip_ranges = find_skip_ranges(content)
+          process_content(content)
+        end
+
+        private
+
+        def initialize_state
+          context[:code_block_annotation_markers] ||= []
+          context[:code_block_annotation_content] ||= []
+          @block_index = 0
+        end
+
+        def process_content(content)
+          result = +""
+          last_end = 0
+
+          content.scan(CODE_BLOCK_REGEX) do
+            match = Regexp.last_match
+            next if match.begin(0) < last_end
+
+            result << content[last_end...match.begin(0)]
+            processed, new_end = process_match(match, content)
+            result << processed
+            last_end = new_end
+          end
+
+          result << content[last_end..]
+        end
+
+        def process_match(match, content)
+          if inside_skip_range?(match.begin(0))
+            [match[0], match.end(0)]
+          else
+            process_annotated_block(match, content)
+          end
+        end
+
+        def process_annotated_block(match, content)
+          markers = extract_annotation_markers(match[2])
+          code_end = match.end(0)
+
+          if markers.any?
+            process_with_list(match, content, markers, code_end)
+          else
+            store_empty_markers
+            @block_index += 1
+            [match[0], code_end]
+          end
+        end
+
+        def process_with_list(match, content, markers, code_end)
+          list_result = ListParser.find_after_code_block(content, code_end)
+
+          if list_result
+            store_markers_and_content(markers, list_result[:items])
+            cleaned_code = strip_annotation_markers(match[2])
+            @block_index += 1
+            ["#{match[0].sub(match[2], cleaned_code)}\n", list_result[:end_position]]
+          else
+            store_empty_markers
+            @block_index += 1
+            [match[0], code_end]
+          end
+        end
+
+        def store_markers_and_content(markers, list_items)
+          context[:code_block_annotation_markers][@block_index] = markers
+          context[:code_block_annotation_content][@block_index] = render_annotation_content(list_items)
+        end
+
+        def store_empty_markers
+          context[:code_block_annotation_markers][@block_index] = {}
+          context[:code_block_annotation_content][@block_index] = {}
+        end
+
+        def extract_annotation_markers(code_content)
+          markers = {}
+          code_content.lines.each_with_index do |line, index|
+            next unless (match = line.match(ANNOTATION_MARKER_PATTERN))
+
+            num = match.captures.compact.first.to_i
+            markers[index + 1] = num
+          end
+          markers
+        end
+
+        def strip_annotation_markers(code_content)
+          code_content.lines.map { |line| strip_single_marker(line) }.join
+        end
+
+        def strip_single_marker(line)
+          return line unless line.match?(ANNOTATION_MARKER_PATTERN)
+
+          stripped = line.sub(ANNOTATION_MARKER_PATTERN, "")
+          stripped.end_with?("\n") ? stripped : "#{stripped}\n"
+        end
+
+        def render_annotation_content(list_items)
+          list_items.transform_values { |markdown_text| render_markdown(markdown_text) }
+        end
+
+        def render_markdown(text)
+          Kramdown::Document.new(text, input: "GFM", hard_wrap: false).to_html.strip
+        end
+
+        def inside_skip_range?(position)
+          @skip_ranges.any? { |range| range.cover?(position) }
+        end
+
+        def find_skip_ranges(content)
+          find_ranges(content, TABS_BLOCK_REGEX) + find_ranges(content, CODE_GROUP_REGEX)
+        end
+
+        def find_ranges(content, pattern)
+          ranges = []
+          content.scan(pattern) do
+            match = Regexp.last_match
+            ranges << (match.begin(0)...match.end(0))
+          end
+          ranges
+        end
+      end
+    end
+  end
+end

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

@@ -33,11 +33,17 @@ module Docyard
         def initialize_postprocess_state(html)
           @block_index = 0
           @options = context[:code_block_options] || []
+          initialize_line_feature_state
+          @tabs_ranges = TabsRangeFinder.find_ranges(html)
+        end
+
+        def initialize_line_feature_state
           @diff_lines = context[:code_block_diff_lines] || []
           @focus_lines = context[:code_block_focus_lines] || []
           @error_lines = context[:code_block_error_lines] || []
           @warning_lines = context[:code_block_warning_lines] || []
-          @tabs_ranges = TabsRangeFinder.find_ranges(html)
+          @annotation_markers = context[:code_block_annotation_markers] || []
+          @annotation_content = context[:code_block_annotation_content] || []
         end
 
         def process_all_highlight_blocks(html)
@@ -99,25 +105,28 @@ module Docyard
 
         def build_block_data(code_text, opts, show_line_numbers, start_line, title_data)
           {
-            text: code_text,
-            highlights: opts[:highlights],
+            text: code_text, highlights: opts[:highlights],
+            show_line_numbers: show_line_numbers, start_line: start_line,
+            line_numbers: show_line_numbers ? LineNumbers.generate_numbers(code_text, start_line) : [],
+            title: title_data[:title], icon: title_data[:icon], icon_source: title_data[:icon_source]
+          }.merge(current_line_features)
+        end
+
+        def current_line_features
+          {
             diff_lines: @diff_lines[@block_index] || {},
             focus_lines: @focus_lines[@block_index] || {},
             error_lines: @error_lines[@block_index] || {},
             warning_lines: @warning_lines[@block_index] || {},
-            show_line_numbers: show_line_numbers,
-            line_numbers: show_line_numbers ? LineNumbers.generate_numbers(code_text, start_line) : [],
-            start_line: start_line,
-            title: title_data[:title],
-            icon: title_data[:icon],
-            icon_source: title_data[:icon_source]
+            annotation_markers: @annotation_markers[@block_index] || {},
+            annotation_content: @annotation_content[@block_index] || {}
           }
         end
 
         def process_html_for_highlighting(original_html, block_data)
           needs_wrapping = block_data[:highlights].any? || block_data[:diff_lines].any? ||
                            block_data[:focus_lines].any? || block_data[:error_lines].any? ||
-                           block_data[:warning_lines].any?
+                           block_data[:warning_lines].any? || block_data[:annotation_markers].any?
           return original_html unless needs_wrapping
 
           wrap_code_block(original_html, block_data)
@@ -150,7 +159,8 @@ module Docyard
         def line_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] }
+            warning_lines: block_data[:warning_lines], annotation_markers: block_data[:annotation_markers],
+            annotation_content: block_data[:annotation_content] }
         end
 
         def title_locals(block_data)

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../base_processor"
+require_relative "../support/markdown_code_block_helper"
+
+module Docyard
+  module Components
+    module Processors
+      class VariablesProcessor < BaseProcessor
+        include Support::MarkdownCodeBlockHelper
+
+        VARIABLE_PATTERN = /\{\{\s*([a-zA-Z0-9_.]+)\s*\}\}/
+        VARS_SUFFIX_PATTERN = /^(`{3,}|~{3,})(\S+)-vars(.*)/
+
+        self.priority = 1
+
+        def preprocess(content)
+          variables = context.dig(:config, "variables") || {}
+          return content if variables.empty?
+
+          segments = split_by_code_blocks(content)
+          segments.map { |segment| process_segment(segment, variables) }.join
+        end
+
+        private
+
+        def process_segment(segment, variables)
+          return substitute_variables(segment[:content], variables) if segment[:type] == :text
+
+          match = segment[:content].match(VARS_SUFFIX_PATTERN)
+          return segment[:content] unless match
+
+          stripped = segment[:content].sub("#{match[2]}-vars", match[2])
+          substitute_variables(stripped, variables)
+        end
+
+        def substitute_variables(content, variables)
+          content.gsub(VARIABLE_PATTERN) do |original|
+            key = Regexp.last_match(1)
+            value = resolve_variable(key, variables)
+            value.nil? ? original : value.to_s
+          end
+        end
+
+        def resolve_variable(key, variables)
+          keys = key.split(".")
+          keys.reduce(variables) do |current, k|
+            return nil unless current.is_a?(Hash)
+
+            current[k]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/docyard/components/support/code_block/annotation_list_parser.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Components
+    module Support
+      module CodeBlock
+        module AnnotationListParser
+          ORDERED_LIST_ITEM = /\A(\d+)\.\s+(.*)/
+          CONTINUATION_LINE = /\A\s{2,}(\S.*)/
+          BLANK_LINE = /\A\s*\z/
+          LIST_START = /\A(\s*\n)*(\d+\.\s+)/m
+
+          module_function
+
+          def parse(text)
+            state = { items: {}, current_num: nil, current_lines: [] }
+            catch(:done) { text.each_line { |line| consume_line(state, line) } }
+            finalize(state)
+            state[:items]
+          end
+
+          def find_after_code_block(content, position)
+            rest = content[position..]
+            return nil unless rest
+
+            preamble = rest.match(LIST_START)
+            return nil unless preamble
+
+            list_start = preamble.begin(2)
+            list_text = rest[list_start..]
+            parsed = parse_with_extent(list_text)
+            return nil if parsed[:items].empty?
+
+            { text: parsed[:consumed], end_position: position + list_start + parsed[:length], items: parsed[:items] }
+          end
+
+          def parse_with_extent(text)
+            state = { items: {}, current_num: nil, current_lines: [] }
+            consumed_length = 0
+
+            catch(:done) do
+              text.each_line do |line|
+                consume_line(state, line)
+                consumed_length += line.length
+              end
+            end
+
+            finalize(state)
+            { items: state[:items], consumed: text[0...consumed_length], length: consumed_length }
+          end
+
+          def consume_line(state, line)
+            if (match = line.match(ORDERED_LIST_ITEM))
+              start_new_item(state, match)
+            elsif state[:current_num] && (cont = line.match(CONTINUATION_LINE))
+              state[:current_lines] << cont[1].rstrip
+            elsif state[:current_num] && line.match?(BLANK_LINE)
+              state[:current_lines] << ""
+            else
+              finalize(state)
+              throw :done
+            end
+          end
+
+          def start_new_item(state, match)
+            finalize(state)
+            state[:current_num] = match[1].to_i
+            state[:current_lines] = [match[2].rstrip]
+          end
+
+          def finalize(state)
+            return unless state[:current_num]
+
+            state[:items][state[:current_num]] = state[:current_lines].join("\n").strip
+            state[:current_num] = nil
+            state[:current_lines] = []
+          end
+
+          private_class_method :consume_line, :start_new_item, :finalize, :parse_with_extent
+        end
+      end
+    end
+  end
+end

data/lib/docyard/components/support/code_block/line_wrapper.rb

@@ -24,10 +24,18 @@ module Docyard
               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>)
+              annotation = annotation_badge(source_line, block_data)
+              line_with_badge = insert_before_newline(line, annotation)
+              %(<span class="#{classes}">#{line_with_badge}</span>)
             end
           end
 
+          def insert_before_newline(line, annotation)
+            return line if annotation.empty?
+
+            line.end_with?("\n") ? "#{line.chomp}#{annotation}\n" : "#{line}#{annotation}"
+          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)
@@ -43,6 +51,22 @@ module Docyard
               ("docyard-code-line--warning" if block_data[:warning_lines][source_line])
             ].compact
           end
+
+          ANNOTATION_ICON = "<i class=\"ph ph-plus-circle\" aria-hidden=\"true\"></i>"
+
+          def annotation_badge(source_line, block_data)
+            markers = block_data[:annotation_markers] || {}
+            num = markers[source_line]
+            return "" unless num
+
+            content = (block_data[:annotation_content] || {})[num]
+            return "" unless content
+
+            escaped = content.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;").gsub('"', "&quot;")
+            %(<button class="docyard-code-annotation" data-annotation-id="#{num}") +
+              %( data-annotation-content="#{escaped}" type="button" aria-label="Annotation #{num}">) +
+              %(#{ANNOTATION_ICON}</button>)
+          end
         end
       end
     end

data/lib/docyard/components/support/code_block/patterns.rb

@@ -48,6 +48,17 @@ module Docyard
               ;\s*\[!code\s+warning\]
             )[^\S\n]*
           }x
+
+          ANNOTATION_MARKER_PATTERN = %r{
+            (?:
+              //\s*\((\d+)\)\s*$              |
+              \#\s*\((\d+)\)\s*$              |
+              /\*\s*\((\d+)\)\s*\*/\s*$       |
+              --\s*\((\d+)\)\s*$              |
+              <!--\s*\((\d+)\)\s*-->\s*$      |
+              ;\s*\((\d+)\)\s*$
+            )
+          }x
         end
       end
     end

data/lib/docyard/config/schema/definition.rb

@@ -23,7 +23,8 @@ module Docyard
         repo: REPO_SCHEMA,
         analytics: ANALYTICS_SCHEMA,
         feedback: FEEDBACK_SCHEMA,
-        social_cards: SOCIAL_CARDS_SCHEMA
+        social_cards: SOCIAL_CARDS_SCHEMA,
+        variables: { type: :hash, allow_extra_keys: true, keys: {} }
       }.freeze
     end
   end

data/lib/docyard/config.rb

@@ -27,7 +27,8 @@ module Docyard
                   "last_updated" => true },
       "analytics" => { "google" => nil, "plausible" => nil, "fathom" => nil, "script" => nil },
       "feedback" => { "enabled" => false, "question" => "Was this page helpful?" },
-      "social_cards" => { "enabled" => false }
+      "social_cards" => { "enabled" => false },
+      "variables" => {}
     }.freeze
 
     attr_reader :data, :file_path
@@ -65,6 +66,7 @@ module Docyard
     def analytics = @analytics ||= Section.new(data["analytics"])
     def feedback = @feedback ||= Section.new(data["feedback"])
     def social_cards = @social_cards ||= Section.new(data["social_cards"])
+    def variables = data["variables"]
 
     def announcement
       @announcement ||= data["announcement"] ? Section.new(data["announcement"]) : nil

data/lib/docyard/rendering/markdown.rb

@@ -19,6 +19,7 @@ require_relative "../components/processors/include_processor"
 require_relative "../components/processors/code_block_options_preprocessor"
 require_relative "../components/processors/code_block_diff_preprocessor"
 require_relative "../components/processors/code_block_focus_preprocessor"
+require_relative "../components/processors/code_block_annotation_preprocessor"
 require_relative "../components/processors/code_block_extended_fence_preprocessor"
 require_relative "../components/processors/code_block_extended_fence_postprocessor"
 require_relative "../components/processors/table_wrapper_processor"
@@ -29,6 +30,7 @@ require_relative "../components/processors/video_embed_processor"
 require_relative "../components/processors/file_tree_processor"
 require_relative "../components/processors/abbreviation_processor"
 require_relative "../components/processors/tooltip_processor"
+require_relative "../components/processors/variables_processor"
 require_relative "../components/processors/table_of_contents_processor"
 require_relative "../components/aliases"
 

data/lib/docyard/templates/assets/css/components/code-annotation.css

@@ -0,0 +1,265 @@
+.docyard-code-annotation {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--code-annotation-size);
+  height: var(--code-annotation-size);
+  margin-left: var(--spacing-1);
+  padding: 0;
+  border: none;
+  border-radius: var(--radius-4xl);
+  background: none;
+  color: var(--primary);
+  cursor: pointer;
+  vertical-align: middle;
+  opacity: 0.7;
+  transition: opacity 150ms ease, transform 150ms ease;
+}
+
+.docyard-code-annotation::before {
+  content: "";
+  position: absolute;
+  inset: -0.375em;
+}
+
+.docyard-code-annotation i[class*="ph-"] {
+  font-size: 1.25em;
+  vertical-align: 0;
+}
+
+@media (hover: hover) {
+  .docyard-code-annotation:hover {
+    opacity: 1;
+  }
+}
+
+.docyard-code-annotation:active {
+  transform: scale(0.92);
+}
+
+.docyard-code-annotation.is-active {
+  opacity: 1;
+}
+
+.docyard-code-annotation:focus-visible {
+  opacity: 1;
+  outline: 1.5px solid var(--primary);
+  outline-offset: 1px;
+  border-radius: 2px;
+}
+
+.docyard-code-block--has-annotations .docyard-code-line {
+  padding-right: calc(var(--code-annotation-size) + var(--spacing-1));
+}
+
+.docyard-code-annotation-popover {
+  position: absolute;
+  z-index: var(--z-tooltip);
+  width: max-content;
+  max-width: 24rem;
+  max-height: 20rem;
+  overflow-y: auto;
+  padding: var(--spacing-3) var(--spacing-4);
+  background: var(--popover);
+  color: oklch(from var(--popover-foreground) l c h / 85%);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-lg);
+  box-shadow:
+    0 1px 2px oklch(from var(--foreground) l c h / 3%),
+    0 4px 12px oklch(from var(--foreground) l c h / 6%),
+    0 16px 32px -8px oklch(from var(--foreground) l c h / 8%);
+  pointer-events: none;
+  opacity: 0;
+  transform: translateY(4px) scale(0.96);
+  transform-origin: var(--arrow-left, 16px) top;
+  transition:
+    opacity 200ms cubic-bezier(0.25, 0.46, 0.45, 0.94),
+    transform 200ms cubic-bezier(0.25, 0.46, 0.45, 0.94);
+}
+
+.docyard-code-annotation-popover.is-visible {
+  opacity: 1;
+  transform: translateY(0) scale(1);
+  pointer-events: auto;
+  transition:
+    opacity 200ms cubic-bezier(0.25, 0.46, 0.45, 0.94),
+    transform 200ms cubic-bezier(0.25, 0.46, 0.45, 0.94);
+}
+
+.docyard-code-annotation-popover.is-above {
+  transform: translateY(-4px) scale(0.96);
+  transform-origin: var(--arrow-left, 16px) bottom;
+}
+
+.docyard-code-annotation-popover.is-above.is-visible {
+  transform: translateY(0) scale(1);
+}
+
+.docyard-code-annotation-popover::after {
+  content: "";
+  position: absolute;
+  top: -5px;
+  left: var(--arrow-left, 16px);
+  width: 9px;
+  height: 9px;
+  background: var(--popover);
+  border-top: 1px solid var(--border);
+  border-left: 1px solid var(--border);
+  border-radius: 1px 0 0 0;
+  transform: rotate(45deg);
+}
+
+.docyard-code-annotation-popover.is-above::after {
+  top: auto;
+  bottom: -5px;
+  border-top: none;
+  border-left: none;
+  border-bottom: 1px solid var(--border);
+  border-right: 1px solid var(--border);
+}
+
+.docyard-code-annotation-popover p {
+  margin: 0;
+  font-size: var(--text-sm);
+  line-height: var(--leading-relaxed);
+}
+
+.docyard-code-annotation-popover * + p,
+.docyard-code-annotation-popover * + ul,
+.docyard-code-annotation-popover * + ol,
+.docyard-code-annotation-popover * + blockquote {
+  margin-top: var(--spacing-2);
+}
+
+.docyard-code-annotation-popover * + .table-wrapper,
+.docyard-code-annotation-popover * + table {
+  margin-top: var(--spacing-2);
+}
+
+.docyard-code-annotation-popover ul,
+.docyard-code-annotation-popover ol {
+  margin: 0;
+  padding-left: var(--spacing-6);
+}
+
+.docyard-code-annotation-popover ul {
+  list-style-type: disc;
+}
+
+.docyard-code-annotation-popover ol {
+  list-style-type: decimal;
+}
+
+.docyard-code-annotation-popover li {
+  margin: var(--spacing-1) 0;
+  padding-left: var(--spacing-1);
+  font-size: var(--text-sm);
+  line-height: var(--leading-relaxed);
+}
+
+.docyard-code-annotation-popover li::marker {
+  color: var(--muted-foreground);
+}
+
+.docyard-code-annotation-popover table {
+  width: 100%;
+  border-spacing: 0;
+  border-collapse: separate;
+  font-size: var(--text-sm);
+  margin: 0;
+  border: 1px solid var(--table-border);
+  border-radius: var(--radius-lg);
+  overflow: hidden;
+}
+
+.docyard-code-annotation-popover thead {
+  background-color: var(--table-header-bg);
+}
+
+.docyard-code-annotation-popover th {
+  padding: var(--spacing-2) var(--spacing-3);
+  text-align: left;
+  font-weight: var(--font-semibold);
+  font-size: var(--text-xs);
+  color: var(--popover-foreground);
+  vertical-align: middle;
+}
+
+.docyard-code-annotation-popover td {
+  padding: var(--spacing-2) var(--spacing-3);
+  font-size: var(--text-xs);
+  vertical-align: middle;
+  border-top: 1px solid var(--table-row-border);
+}
+
+.docyard-code-annotation-popover blockquote {
+  margin: 0;
+  padding-left: var(--spacing-6);
+  border-left: 4px solid var(--border);
+  color: var(--muted-foreground);
+}
+
+.docyard-code-annotation-popover blockquote p {
+  margin: var(--spacing-1) 0;
+}
+
+.docyard-code-annotation-popover code {
+  padding: 0.125rem 0.5rem;
+  background-color: oklch(from var(--muted) l c h / 80%);
+  color: var(--popover-foreground);
+  border-radius: var(--radius-sm);
+  font-size: 0.875em;
+  font-weight: var(--font-medium);
+  font-variant-ligatures: none;
+}
+
+.docyard-code-annotation-popover strong {
+  font-weight: var(--font-semibold);
+  color: var(--popover-foreground);
+}
+
+.docyard-code-annotation-popover a {
+  color: var(--popover-foreground);
+  font-weight: var(--font-semibold);
+  text-decoration: none;
+  border-bottom: 1px solid oklch(from var(--primary) l c h / 40%);
+  transition: border-bottom var(--transition-fast);
+}
+
+.docyard-code-annotation-popover a:hover {
+  border-bottom: 2px solid var(--primary);
+}
+
+@media (max-width: 640px) {
+  .docyard-code-annotation-popover {
+    max-width: 16rem;
+    padding: var(--spacing-2-5) var(--spacing-3);
+  }
+
+  .docyard-code-annotation-popover p,
+  .docyard-code-annotation-popover li {
+    font-size: var(--text-xs);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .docyard-code-annotation,
+  .docyard-code-annotation-popover {
+    transition: none;
+  }
+
+  .docyard-code-annotation:active {
+    transform: none;
+  }
+
+  .docyard-code-annotation-popover,
+  .docyard-code-annotation-popover.is-above {
+    transform: none;
+  }
+
+  .docyard-code-annotation-popover.is-visible,
+  .docyard-code-annotation-popover.is-above.is-visible {
+    transform: none;
+  }
+}

data/lib/docyard/templates/assets/css/variables.css

@@ -84,6 +84,8 @@
   --callout-danger-background: rgba(254, 242, 242, 0.5);
   --callout-danger-border: rgba(239, 68, 68, 0.2);
 
+  --code-annotation-size: 1.25em;
+
   --code-block-bg: oklab(0 0 0 / 0.03);
   --code-block-border: oklab(0 0 0 / 0.06);
   --code-block-header-bg: oklab(0 0 0 / 0.02);

data/lib/docyard/templates/assets/js/components/code-annotation.js

@@ -0,0 +1,136 @@
+var annotationPopover = null;
+var activeAnnotationButton = null;
+
+function initCodeAnnotations(root) {
+  if (typeof root === 'undefined') root = document;
+  var buttons = root.querySelectorAll('.docyard-code-annotation');
+  if (buttons.length === 0) return;
+
+  if (!annotationPopover) {
+    annotationPopover = document.createElement('div');
+    annotationPopover.className = 'docyard-code-annotation-popover';
+    document.body.appendChild(annotationPopover);
+
+    document.addEventListener('click', function(e) {
+      if (activeAnnotationButton &&
+          !annotationPopover.contains(e.target) &&
+          !e.target.closest('.docyard-code-annotation')) {
+        hideAnnotationPopover();
+      }
+    });
+
+    document.addEventListener('keydown', function(e) {
+      if (e.key === 'Escape' && activeAnnotationButton) {
+        hideAnnotationPopover();
+        activeAnnotationButton.focus();
+      }
+    });
+  }
+
+  buttons.forEach(function(button) {
+    if (button.hasAttribute('data-annotation-initialized')) return;
+    button.setAttribute('data-annotation-initialized', 'true');
+
+    button.addEventListener('click', function(e) {
+      e.stopPropagation();
+      if (activeAnnotationButton === button) {
+        hideAnnotationPopover();
+      } else {
+        showAnnotationPopover(button);
+      }
+    });
+  });
+}
+
+function setAnnotationIcon(button, name, animate) {
+  var icon = button.querySelector('i[class*="ph-"]');
+  if (!icon) return;
+  if (!animate) {
+    icon.className = 'ph ph-' + name;
+    return;
+  }
+  icon.style.transition = 'opacity 100ms ease, transform 100ms ease';
+  icon.style.opacity = '0';
+  icon.style.transform = 'scale(0.5)';
+  setTimeout(function() {
+    icon.className = 'ph ph-' + name;
+    icon.style.opacity = '1';
+    icon.style.transform = 'scale(1)';
+  }, 100);
+}
+
+function showAnnotationPopover(button) {
+  if (activeAnnotationButton) {
+    setAnnotationIcon(activeAnnotationButton, 'plus-circle', true);
+    activeAnnotationButton.classList.remove('is-active');
+  }
+
+  activeAnnotationButton = button;
+  button.classList.add('is-active');
+  setAnnotationIcon(button, 'x-circle', true);
+  annotationPopover.innerHTML = button.getAttribute('data-annotation-content');
+
+  annotationPopover.classList.remove('is-above');
+  annotationPopover.style.visibility = 'hidden';
+  annotationPopover.classList.add('is-visible');
+
+  requestAnimationFrame(function() {
+    positionPopover(button);
+  });
+}
+
+function positionPopover(button) {
+  var rect = button.getBoundingClientRect();
+  var scrollX = window.scrollX;
+  var scrollY = window.scrollY;
+  var popoverRect = annotationPopover.getBoundingClientRect();
+  var gap = 6;
+  var padding = 12;
+  var viewportWidth = window.innerWidth;
+  var viewportHeight = window.innerHeight;
+
+  var left = rect.left + scrollX + (rect.width / 2) - (popoverRect.width / 2);
+  var spaceBelow = viewportHeight - rect.bottom;
+  var spaceAbove = rect.top;
+  var openAbove = spaceBelow < popoverRect.height + gap + padding && spaceAbove > spaceBelow;
+
+  var top;
+  if (openAbove) {
+    top = rect.top + scrollY - popoverRect.height - gap;
+    annotationPopover.classList.add('is-above');
+  } else {
+    top = rect.bottom + scrollY + gap;
+    annotationPopover.classList.remove('is-above');
+  }
+
+  if (left < padding) {
+    left = padding;
+  } else if (left + popoverRect.width > viewportWidth - padding) {
+    left = viewportWidth - popoverRect.width - padding;
+  }
+
+  var arrowLeft = rect.left + scrollX + (rect.width / 2) - left;
+  annotationPopover.style.setProperty('--arrow-left', Math.max(12, Math.min(arrowLeft, popoverRect.width - 12)) + 'px');
+  annotationPopover.style.left = left + 'px';
+  annotationPopover.style.top = top + 'px';
+  annotationPopover.style.visibility = 'visible';
+}
+
+function hideAnnotationPopover() {
+  if (!annotationPopover) return;
+  if (activeAnnotationButton) {
+    setAnnotationIcon(activeAnnotationButton, 'plus-circle', true);
+    activeAnnotationButton.classList.remove('is-active');
+  }
+  annotationPopover.classList.remove('is-visible');
+  activeAnnotationButton = null;
+}
+
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', function() { initCodeAnnotations(); });
+} else {
+  initCodeAnnotations();
+}
+
+window.docyard = window.docyard || {};
+window.docyard.initCodeAnnotations = initCodeAnnotations;

data/lib/docyard/templates/assets/js/hot-reload.js

@@ -59,6 +59,7 @@
     if (docyard.initAbbreviations) docyard.initAbbreviations(container);
     if (docyard.initLightbox) docyard.initLightbox(container);
     if (docyard.initTooltips) docyard.initTooltips(container);
+    if (docyard.initCodeAnnotations) docyard.initCodeAnnotations(container);
   }
 
   function reloadContent() {

data/lib/docyard/templates/partials/_code_block.html.erb

@@ -1,4 +1,4 @@
-<% has_diff = @diff_lines&.any? %><% has_focus = @focus_lines&.any? %><% has_error = @error_lines&.any? %><% has_warning = @warning_lines&.any? %><% has_title = !@title.nil? && !@title.empty? %><div class="docyard-code-block<%= ' docyard-code-block--line-numbers' if @show_line_numbers %><%= ' docyard-code-block--highlighted' if @highlights&.any? %><%= ' docyard-code-block--diff' if has_diff %><%= ' docyard-code-block--has-focus' if has_focus %><%= ' docyard-code-block--has-error' if has_error %><%= ' docyard-code-block--has-warning' if has_warning %><%= ' docyard-code-block--titled' if has_title %>" data-pagefind-ignore>
+<% has_diff = @diff_lines&.any? %><% has_focus = @focus_lines&.any? %><% has_error = @error_lines&.any? %><% has_warning = @warning_lines&.any? %><% has_annotations = @annotation_markers&.any? %><% has_title = !@title.nil? && !@title.empty? %><div class="docyard-code-block<%= ' docyard-code-block--line-numbers' if @show_line_numbers %><%= ' docyard-code-block--highlighted' if @highlights&.any? %><%= ' docyard-code-block--diff' if has_diff %><%= ' docyard-code-block--has-focus' if has_focus %><%= ' docyard-code-block--has-error' if has_error %><%= ' docyard-code-block--has-warning' if has_warning %><%= ' docyard-code-block--has-annotations' if has_annotations %><%= ' docyard-code-block--titled' if has_title %>" data-pagefind-ignore>
   <% if has_title %>
   <div class="docyard-code-block__header">
     <% if @icon %>

data/lib/docyard/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Docyard
-  VERSION = "1.3.0"
+  VERSION = "1.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docyard
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Sanif Himani
@@ -199,6 +199,7 @@ files:
 - lib/docyard/components/processors/badge_processor.rb
 - lib/docyard/components/processors/callout_processor.rb
 - lib/docyard/components/processors/cards_processor.rb
+- lib/docyard/components/processors/code_block_annotation_preprocessor.rb
 - lib/docyard/components/processors/code_block_diff_preprocessor.rb
 - lib/docyard/components/processors/code_block_extended_fence_postprocessor.rb
 - lib/docyard/components/processors/code_block_extended_fence_preprocessor.rb
@@ -218,8 +219,10 @@ files:
 - lib/docyard/components/processors/table_wrapper_processor.rb
 - lib/docyard/components/processors/tabs_processor.rb
 - lib/docyard/components/processors/tooltip_processor.rb
+- lib/docyard/components/processors/variables_processor.rb
 - lib/docyard/components/processors/video_embed_processor.rb
 - lib/docyard/components/registry.rb
+- lib/docyard/components/support/code_block/annotation_list_parser.rb
 - lib/docyard/components/support/code_block/feature_extractor.rb
 - lib/docyard/components/support/code_block/icon_detector.rb
 - lib/docyard/components/support/code_block/line_number_resolver.rb
@@ -330,6 +333,7 @@ files:
 - lib/docyard/templates/assets/css/components/breadcrumbs.css
 - lib/docyard/templates/assets/css/components/callout.css
 - lib/docyard/templates/assets/css/components/cards.css
+- lib/docyard/templates/assets/css/components/code-annotation.css
 - lib/docyard/templates/assets/css/components/code-block.css
 - lib/docyard/templates/assets/css/components/code-group.css
 - lib/docyard/templates/assets/css/components/feedback.css
@@ -363,6 +367,7 @@ files:
 - lib/docyard/templates/assets/fonts/Inter-Variable.woff2
 - lib/docyard/templates/assets/js/components/abbreviation.js
 - lib/docyard/templates/assets/js/components/banner.js
+- lib/docyard/templates/assets/js/components/code-annotation.js
 - lib/docyard/templates/assets/js/components/code-block.js
 - lib/docyard/templates/assets/js/components/code-group.js
 - lib/docyard/templates/assets/js/components/copy-page.js