docyard 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e127990af44c6db555b00cfd2c7a89be408e6e4bfddf2bed9a753387f708ee87
-  data.tar.gz: ed54f92691fe29fc8dd83b8b797504162283bba12840c49c120a4341ac22a66c
+  metadata.gz: 51b2adfdb7f77c4366592cc3eea5a160fc42f85f17e44593e9bf192c3b470b48
+  data.tar.gz: 439d82b762c7bc6f485ab627365522b7e202833fc841c6b8655fb28e1e9b3e55
 SHA512:
-  metadata.gz: 7ae09bfea3ce92e5b5b8cee3e7317d6d57b253e17314adcfbf9f468cc0635a54d3cbd55a90f28807514875359e4d93b4e1c68fee99b7ec65a9ab12d34a21c6c2
-  data.tar.gz: 3c2148376ab27c804a148666795420afe24fe23cb890fa76fa2602af5434d9e60d589fcbb460454210d2dfe1cc38f1f8584db41b1209db14b8b21ec3d7abeb68
+  metadata.gz: a66355efb4615ae4552aa8656e63078989cdec734f41670dc172936060954a065fefb1a2733e51494747ef0ab9a1dbee399b3c8f37daf2718e92ba03c315df9f
+  data.tar.gz: be3cea82f91b60cc7e7c35be142b6c2ccd9be4323cbf1c5190987b6ba6894d4c8da38f55c141abda43211a5ac2b70d38283e1b340d62071ee5c22c87c9c35a51

data/.rubocop.yml

@@ -22,7 +22,11 @@ Metrics/ClassLength:
   Max: 150
 
 Metrics/MethodLength:
-  Max: 15
+  Max: 16
+
+Metrics/ParameterLists:
+  MaxOptionalParameters: 6
+  CountKeywordArgs: false
 
 Style/Documentation:
   Enabled: false

data/CHANGELOG.md

@@ -7,6 +7,46 @@ 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
+- **Landing Pages** - Hero sections, feature grids, and custom footer layouts for documentation homepages (#45)
+- **Tab Navigation** - Top-level navigation tabs for organizing documentation into sections like Guide, API, Components (#52)
+- **Header CTAs** - Configurable call-to-action buttons in the header with primary/secondary variants (#51)
+- **Breadcrumbs** - Path navigation with auto-truncation for deep nesting and configurable via `navigation.breadcrumbs` (#54)
+- **Doc Page Footer** - Social icons, "Built with Docyard" attribution, and copyright text in TOC column (#55)
+- **Auto-detect Branding** - Automatic logo and favicon detection from `docs/public/` directory (#49)
+- **Social Icon Mapping** - 16 social platform icons with automatic platform-to-icon mapping (#55)
+
+### Changed
+- **Sidebar Overhaul** - Per-section `_sidebar.yml` files, improved collapsible behavior, and better active state handling (#50, #53)
+- **Config Schema** - Reorganized configuration with `branding`, `navigation`, and `socials` sections (#48)
+- **Sidebar Convention** - Section-based sidebar configuration in `docs/<section>/_sidebar.yml` (#47)
+- **UI Refresh** - Updated typography, spacing, and visual consistency across components (#44)
+- **Logo Update** - New logo with cyan accent and dark mode support (#46)
+
 ## [0.7.0] - 2026-01-01
 
 ### Added
@@ -122,7 +162,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/v0.7.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
 [0.5.0]: https://github.com/sanifhimani/docyard/compare/v0.4.0...v0.5.0

data/lib/docyard/build/asset_bundler.rb

@@ -35,6 +35,8 @@ module Docyard
         main_css = File.read(File.join(ASSETS_PATH, "css", "main.css"))
         css_content = resolve_css_imports(main_css)
         minified = CSSminify.compress(css_content)
+        minified = fix_calc_whitespace(minified)
+        minified = fix_css_math_functions(minified)
         hash = generate_hash(minified)
 
         write_bundled_asset(minified, hash, "css")
@@ -43,6 +45,19 @@ module Docyard
         hash
       end
 
+      def fix_calc_whitespace(css)
+        css
+          .gsub(/\)\+(?!\s)/, ") + ")
+          .gsub(/\)-(?![-\s])/, ") - ")
+          .gsub(/(\d[a-z]*)\+(?=[\w(])/, '\1 + ')
+          .gsub(/([lch])\+(?=[\d.])/, '\1 + ')
+          .gsub(/([lch])-(?=[\d.])/, '\1 - ')
+      end
+
+      def fix_css_math_functions(css)
+        css.gsub(/\bmax\(0,/, "max(0px,").gsub(/\bmin\(0,/, "min(0px,)")
+      end
+
       def resolve_css_imports(css_content)
         css_content.gsub(/@import url\('([^']+)'\);/) do |match|
           import_file = Regexp.last_match(1)
@@ -92,8 +107,8 @@ module Docyard
       end
 
       def update_html_references(css_hash, js_hash)
-        html_files = Dir.glob(File.join(config.build.output_dir, "**", "*.html"))
-        base_url = normalize_base_url(config.build.base_url)
+        html_files = Dir.glob(File.join(config.build.output, "**", "*.html"))
+        base_url = normalize_base_url(config.build.base)
 
         html_files.each do |file|
           content = replace_asset_references(File.read(file), css_hash, js_hash, base_url)
@@ -104,15 +119,15 @@ module Docyard
       end
 
       def replace_asset_references(content, css_hash, js_hash, base_url)
-        content.gsub(%r{/assets/css/main\.css}, "#{base_url}assets/bundle.#{css_hash}.css")
-          .gsub(%r{/assets/js/theme\.js}, "#{base_url}assets/bundle.#{js_hash}.js")
-          .gsub(%r{/assets/js/components\.js}, "")
-          .gsub(%r{<script src="/assets/js/reload\.js"></script>}, "")
+        content.gsub(%r{/_docyard/css/main\.css}, "#{base_url}_docyard/bundle.#{css_hash}.css")
+          .gsub(%r{/_docyard/js/theme\.js}, "#{base_url}_docyard/bundle.#{js_hash}.js")
+          .gsub(%r{/_docyard/js/components\.js}, "")
+          .gsub(%r{<script src="/_docyard/js/reload\.js"></script>}, "")
       end
 
       def write_bundled_asset(content, hash, extension)
         filename = "bundle.#{hash}.#{extension}"
-        output_path = File.join(config.build.output_dir, "assets", filename)
+        output_path = File.join(config.build.output, "_docyard", filename)
         FileUtils.mkdir_p(File.dirname(output_path))
         File.write(output_path, content)
       end

data/lib/docyard/build/file_copier.rb

@@ -3,6 +3,8 @@
 module Docyard
   module Build
     class FileCopier
+      DOCYARD_OUTPUT_DIR = "_docyard"
+
       attr_reader :config, :verbose
 
       def initialize(config, verbose: false)
@@ -14,7 +16,7 @@ module Docyard
         puts "\nCopying static assets..."
 
         count = 0
-        count += copy_user_assets
+        count += copy_public_files
         count += copy_branding_assets
 
         log "[✓] Copied #{count} static files"
@@ -23,25 +25,22 @@ module Docyard
 
       private
 
-      def copy_user_assets
-        user_assets_dir = "docs/assets"
-        return 0 unless Dir.exist?(user_assets_dir)
-
-        output_assets_dir = File.join(config.build.output_dir, "assets")
-        FileUtils.mkdir_p(output_assets_dir)
+      def copy_public_files
+        public_dir = Constants::PUBLIC_DIR
+        return 0 unless Dir.exist?(public_dir)
 
-        files = find_user_asset_files(user_assets_dir)
-        files.each { |file| copy_single_asset(file, "docs/assets/", output_assets_dir) }
+        files = find_files_in_dir(public_dir)
+        files.each { |file| copy_single_file(file, "#{public_dir}/", config.build.output) }
 
-        log "[✓] Copied #{files.size} user assets from docs/assets/" if files.any?
+        log "[✓] Copied #{files.size} public files from #{public_dir}/" if files.any?
         files.size
       end
 
-      def find_user_asset_files(assets_dir)
-        Dir.glob(File.join(assets_dir, "**", "*")).select { |f| File.file?(f) }
+      def find_files_in_dir(dir)
+        Dir.glob(File.join(dir, "**", "*")).select { |f| File.file?(f) }
       end
 
-      def copy_single_asset(file, prefix, output_dir)
+      def copy_single_file(file, prefix, output_dir)
         relative_path = file.delete_prefix(prefix)
         dest_path = File.join(output_dir, relative_path)
 
@@ -60,26 +59,49 @@ module Docyard
       end
 
       def copy_default_branding_assets
-        templates_assets = File.join(__dir__, "..", "templates", "assets")
-        count = 0
+        templates_assets = templates_assets_path
+        count = copy_branding_files(templates_assets)
+        count + copy_fonts(templates_assets)
+      end
 
-        ["logo.svg", "logo-dark.svg", "favicon.svg"].each do |asset_file|
-          source_path = File.join(templates_assets, asset_file)
-          next unless File.exist?(source_path)
+      def templates_assets_path
+        File.join(__dir__, "..", "templates", "assets")
+      end
 
-          dest_path = File.join(config.build.output_dir, "assets", asset_file)
-          FileUtils.mkdir_p(File.dirname(dest_path))
-          FileUtils.cp(source_path, dest_path)
+      def copy_branding_files(templates_assets)
+        branding_files = %w[logo.svg logo-dark.svg favicon.svg]
+        branding_files.sum { |asset_file| copy_asset_to_docyard(templates_assets, asset_file, "default branding") }
+      end
 
-          log "  Copied default branding: #{asset_file}" if verbose
-          count += 1
-        end
+      def copy_asset_to_docyard(source_dir, filename, label)
+        source_path = File.join(source_dir, filename)
+        return 0 unless File.exist?(source_path)
 
-        count
+        dest_path = File.join(config.build.output, DOCYARD_OUTPUT_DIR, filename)
+        FileUtils.mkdir_p(File.dirname(dest_path))
+        FileUtils.cp(source_path, dest_path)
+        log "  Copied #{label}: #{filename}" if verbose
+        1
+      end
+
+      def copy_fonts(templates_assets)
+        fonts_dir = File.join(templates_assets, "fonts")
+        return 0 unless Dir.exist?(fonts_dir)
+
+        font_files = Dir.glob(File.join(fonts_dir, "*")).select { |f| File.file?(f) }
+        font_files.sum { |font_file| copy_single_font(font_file) }
+      end
+
+      def copy_single_font(font_file)
+        dest_path = File.join(config.build.output, DOCYARD_OUTPUT_DIR, "fonts", File.basename(font_file))
+        FileUtils.mkdir_p(File.dirname(dest_path))
+        FileUtils.cp(font_file, dest_path)
+        log "  Copied font: #{File.basename(font_file)}" if verbose
+        1
       end
 
       def copy_user_branding_assets
-        %w[logo logo_dark favicon].sum { |asset_key| copy_single_branding_asset(asset_key) }
+        %w[logo favicon].sum { |asset_key| copy_single_branding_asset(asset_key) }
       end
 
       def copy_single_branding_asset(asset_key)
@@ -89,7 +111,7 @@ module Docyard
         full_path = File.join("docs", asset_path)
         return 0 unless File.exist?(full_path)
 
-        dest_path = File.join(config.build.output_dir, "assets", asset_path)
+        dest_path = File.join(config.build.output, asset_path)
         FileUtils.mkdir_p(File.dirname(dest_path))
         FileUtils.cp(full_path, dest_path)
 

data/lib/docyard/build/sitemap_generator.rb

@@ -15,7 +15,7 @@ module Docyard
         urls = collect_urls
         sitemap_content = build_sitemap(urls)
 
-        output_path = File.join(config.build.output_dir, "sitemap.xml")
+        output_path = File.join(config.build.output, "sitemap.xml")
         File.write(output_path, sitemap_content)
 
         puts "[✓] Generated sitemap.xml (#{urls.size} URLs)"
@@ -24,10 +24,10 @@ module Docyard
       private
 
       def collect_urls
-        html_files = Dir.glob(File.join(config.build.output_dir, "**", "index.html"))
+        html_files = Dir.glob(File.join(config.build.output, "**", "index.html"))
 
         html_files.map do |file|
-          relative_path = file.delete_prefix(config.build.output_dir).delete_suffix("/index.html")
+          relative_path = file.delete_prefix(config.build.output).delete_suffix("/index.html")
           url_path = relative_path.empty? ? "/" : relative_path
           lastmod = File.mtime(file).utc.iso8601
 
@@ -36,15 +36,15 @@ module Docyard
       end
 
       def build_sitemap(urls)
-        base_url = config.build.base_url
-        base_url = base_url.chop if base_url.end_with?("/")
+        base = config.build.base
+        base = base.chop if base.end_with?("/")
 
         xml = ['<?xml version="1.0" encoding="UTF-8"?>']
         xml << '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">'
 
         urls.each do |url|
           xml << "  <url>"
-          xml << "    <loc>#{base_url}#{url[:loc]}</loc>"
+          xml << "    <loc>#{base}#{url[:loc]}</loc>"
           xml << "    <lastmod>#{url[:lastmod]}</lastmod>"
           xml << "  </url>"
         end

data/lib/docyard/build/static_generator.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 require "tty-progressbar"
+require_relative "../rendering/template_resolver"
+require_relative "../navigation/prev_next_builder"
+require_relative "../navigation/breadcrumb_builder"
 
 module Docyard
   module Build
@@ -10,10 +13,12 @@ module Docyard
       def initialize(config, verbose: false)
         @config = config
         @verbose = verbose
-        @renderer = Renderer.new(base_url: config.build.base_url, config: config)
+        @renderer = Renderer.new(base_url: config.build.base, config: config)
       end
 
       def generate
+        copy_custom_landing_page if custom_landing_page?
+
         markdown_files = collect_markdown_files
         puts "\n[✓] Found #{markdown_files.size} markdown files"
 
@@ -33,24 +38,72 @@ module Docyard
 
       private
 
+      def custom_landing_page?
+        File.file?("docs/index.html")
+      end
+
+      def copy_custom_landing_page
+        output_path = File.join(config.build.output, "index.html")
+        FileUtils.mkdir_p(File.dirname(output_path))
+        FileUtils.cp("docs/index.html", output_path)
+        log "[✓] Copied custom landing page (index.html)"
+      end
+
       def collect_markdown_files
-        Dir.glob(File.join("docs", "**", "*.md"))
+        files = Dir.glob(File.join("docs", "**", "*.md"))
+        files.reject! { |f| f == "docs/index.md" } if custom_landing_page?
+        files
       end
 
       def generate_page(markdown_file_path)
         output_path = determine_output_path(markdown_file_path)
         current_path = determine_current_path(markdown_file_path)
 
-        sidebar_html = build_sidebar(current_path)
-        html_content = renderer.render_file(
-          markdown_file_path,
-          sidebar_html: sidebar_html,
-          branding: branding_options
-        )
+        html_content = render_markdown_file(markdown_file_path, current_path)
+        html_content = apply_search_exclusion(html_content, current_path)
+        write_output(output_path, html_content)
+      end
+
+      def apply_search_exclusion(html_content, current_path)
+        return html_content unless excluded_from_search?(current_path)
+
+        html_content.gsub("data-pagefind-body", "data-pagefind-ignore")
+      end
+
+      def excluded_from_search?(path)
+        exclude_patterns = config.search.exclude || []
+        exclude_patterns.any? do |pattern|
+          next false unless pattern.start_with?("/")
+
+          File.fnmatch(pattern, path, File::FNM_PATHNAME)
+        end
+      end
+
+      def render_markdown_file(markdown_file_path, current_path)
+        markdown = Markdown.new(File.read(markdown_file_path))
+        template_resolver = TemplateResolver.new(markdown.frontmatter, config.data)
+        branding = branding_options
 
+        navigation = build_navigation_html(template_resolver, current_path, markdown, branding[:header_ctas])
+        renderer.render_file(markdown_file_path, **navigation, branding: branding,
+                                                               template_options: template_resolver.to_options,
+                                                               current_path: current_path)
+      end
+
+      def build_navigation_html(template_resolver, current_path, markdown, header_ctas)
+        return { sidebar_html: "", prev_next_html: "", breadcrumbs: nil } unless template_resolver.show_sidebar?
+
+        sidebar_builder = build_sidebar_instance(current_path, header_ctas)
+        {
+          sidebar_html: sidebar_builder.to_html,
+          prev_next_html: build_prev_next(sidebar_builder, current_path, markdown),
+          breadcrumbs: build_breadcrumbs(sidebar_builder.tree, current_path)
+        }
+      end
+
+      def write_output(output_path, html_content)
         FileUtils.mkdir_p(File.dirname(output_path))
         File.write(output_path, html_content)
-
         log "Generated: #{output_path}" if verbose
       end
 
@@ -59,7 +112,7 @@ module Docyard
         base_name = File.basename(relative_path, ".md")
         dir_name = File.dirname(relative_path)
 
-        output_dir = config.build.output_dir
+        output_dir = config.build.output
 
         if base_name == "index"
           File.join(output_dir, dir_name, "index.html")
@@ -80,14 +133,34 @@ module Docyard
         end
       end
 
-      def build_sidebar(current_path)
+      def build_sidebar_instance(current_path, header_ctas = [])
         SidebarBuilder.new(
           docs_path: "docs",
           current_path: current_path,
-          config: config
+          config: config,
+          header_ctas: header_ctas
+        )
+      end
+
+      def build_prev_next(sidebar_builder, current_path, markdown)
+        PrevNextBuilder.new(
+          sidebar_tree: sidebar_builder.tree,
+          current_path: current_path,
+          frontmatter: markdown.frontmatter,
+          config: {}
         ).to_html
       end
 
+      def build_breadcrumbs(sidebar_tree, current_path)
+        return nil unless breadcrumbs_enabled?
+
+        BreadcrumbBuilder.new(sidebar_tree: sidebar_tree, current_path: current_path)
+      end
+
+      def breadcrumbs_enabled?
+        config.navigation.breadcrumbs != false
+      end
+
       def branding_options
         BrandingResolver.new(config).resolve
       end

data/lib/docyard/builder.rb

@@ -35,7 +35,7 @@ module Docyard
     private
 
     def prepare_output_directory
-      output_dir = config.build.output_dir
+      output_dir = config.build.output
 
       if clean && Dir.exist?(output_dir)
         log "[✓] Cleaning #{output_dir}/ directory"
@@ -68,7 +68,7 @@ module Docyard
       sitemap_gen = Build::SitemapGenerator.new(config)
       sitemap_gen.generate
 
-      File.write(File.join(config.build.output_dir, "robots.txt"), robots_txt_content)
+      File.write(File.join(config.build.output, "robots.txt"), robots_txt_content)
       log "[+] Generated robots.txt"
     end
 
@@ -78,14 +78,14 @@ module Docyard
     end
 
     def robots_txt_content
-      base_url = config.build.base_url
-      base_url = "#{base_url}/" unless base_url.end_with?("/")
+      base = config.build.base
+      base = "#{base}/" unless base.end_with?("/")
 
       <<~ROBOTS
         User-agent: *
         Allow: /
 
-        Sitemap: #{base_url}sitemap.xml
+        Sitemap: #{base}sitemap.xml
       ROBOTS
     end
 
@@ -94,7 +94,7 @@ module Docyard
 
       puts "\n#{'=' * 50}"
       puts "Build complete in #{format('%.2f', elapsed)}s"
-      puts "Output: #{config.build.output_dir}/"
+      puts "Output: #{config.build.output}/"
 
       summary = "#{pages} pages, #{bundles} bundles, #{assets} static files"
       summary += ", #{indexed} pages indexed" if indexed.positive?

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