docyard 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe9582d35d963462ff818674735f3b131607368f6adc6fdb70eac6152365efe8
-  data.tar.gz: a8e8b424702b4ca3ff2726a938ea0696f0b15bed3d82f449f803f64923bbbafc
+  metadata.gz: c329f7664eff5bca0fded133cdc29fffa5eea23f81a0183605ea1f038adfa819
+  data.tar.gz: 5f4c135cd6a7dc25140d8111940d6a2fda14c4c9b142adb3d0c8b8a2c91a8f30
 SHA512:
-  metadata.gz: 4c6ae9f9e88f186d43aa13ef62c2c96d3c4ed65e0320558413df73915bd33478b673dae25dc4f3e3fdf6b0fe627ca595a8fc53cded6186ed3afb03ae08ef7f5d
-  data.tar.gz: 17ad431713b55f78b87a67b5de17db1e58c949895a08ff9d31b6f658aa277a8df8cab84f3d3ee178f9c70a9eb30557089fc0b732e2793b6c9b3c8054bf513b1c
+  metadata.gz: bb2ccd83fef6197381df0dee879b71005fa6745842c242bd2fe4e2622d172356f0919b165c63791d6999f04f1cf8715f4dc5338d6050203f5133345ad52fcd9a
+  data.tar.gz: 7a6ea46ba7dd06050e4157c018d158c904a9fbb86dcce352446a4b7d8c99199b641cd8094d5a5eb4074e59716df2abd3e30925fc19c8d4232f365a11d20524a5

data/CHANGELOG.md

@@ -7,6 +7,27 @@ 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
+- **Deploy Command** - One-command deployment with `docyard deploy` supporting Vercel, Netlify, Cloudflare Pages, and GitHub Pages (#153)
+- **Platform Auto-Detection** - Automatically detects deployment platform from project config files (e.g. `vercel.json`, `netlify.toml`)
+
+### Documentation
+- Added Deploy Command page with per-platform setup instructions
+- Updated CLI reference with `docyard deploy` options
+- Cross-linked existing GitHub Pages, Vercel, and Netlify docs to deploy command
+
 ## [1.2.0] - 2026-02-03
 
 ### Added
@@ -264,7 +285,9 @@ 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.2.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
 [1.0.2]: https://github.com/sanifhimani/docyard/compare/v1.0.1...v1.0.2

data/lib/docyard/cli.rb

@@ -80,6 +80,23 @@ module Docyard
       exit(doctor.run)
     end
 
+    desc "deploy", "Deploy the built site to a hosting platform"
+    method_option :to, type: :string, desc: "Target platform (vercel, netlify, cloudflare, github-pages)"
+    method_option :prod, type: :boolean, default: true, desc: "Deploy to production"
+    method_option :skip_build, type: :boolean, default: false, desc: "Skip building before deploy"
+    def deploy
+      apply_global_options
+      require_relative "deploy/deployer"
+      deployer = Deploy::Deployer.new(
+        to: options[:to],
+        production: options[:prod],
+        skip_build: options[:skip_build]
+      )
+      exit(1) unless deployer.deploy
+    rescue ConfigError => e
+      print_config_error(e)
+    end
+
     desc "customize", "Generate theme customization files"
     method_option :minimal, type: :boolean, default: false, aliases: "-m",
                             desc: "Generate minimal files without comments"

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/deploy/adapters/base.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Docyard
+  module Deploy
+    module Adapters
+      class Base
+        attr_reader :output_dir, :production, :config
+
+        def initialize(output_dir:, production:, config:)
+          @output_dir = output_dir
+          @production = production
+          @config = config
+        end
+
+        def deploy
+          check_cli_installed!
+          run_deploy
+        end
+
+        def platform_name
+          raise NotImplementedError
+        end
+
+        private
+
+        def cli_name
+          raise NotImplementedError
+        end
+
+        def cli_install_hint
+          raise NotImplementedError
+        end
+
+        def run_deploy
+          raise NotImplementedError
+        end
+
+        def check_cli_installed!
+          _, _, status = Open3.capture3("which", cli_name)
+          return if status.success?
+
+          raise DeployError, "'#{cli_name}' CLI not found. Install it with: #{cli_install_hint}"
+        end
+
+        def execute_command(*)
+          stdout, stderr, status = Open3.capture3(*)
+          return stdout if status.success?
+
+          raise DeployError, "Deploy command failed: #{stderr.strip.empty? ? stdout.strip : stderr.strip}"
+        end
+      end
+    end
+  end
+end

data/lib/docyard/deploy/adapters/cloudflare.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Docyard
+  module Deploy
+    module Adapters
+      class Cloudflare < Base
+        def platform_name
+          "Cloudflare Pages"
+        end
+
+        private
+
+        def cli_name
+          "wrangler"
+        end
+
+        def cli_install_hint
+          "npm i -g wrangler"
+        end
+
+        def run_deploy
+          output = execute_command("wrangler", "pages", "deploy", output_dir, "--project-name=#{project_name}")
+          extract_url(output)
+        end
+
+        def project_name
+          config.title.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|-\z/, "")
+        end
+
+        def extract_url(output)
+          output.match(%r{https://\S+\.pages\.dev\S*})&.to_s
+        end
+      end
+    end
+  end
+end