docyard 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6ab36d72a5ae740f0ba203c29ab88b2698f0010bbc980ac0ef3a8b7d5f9f579
-  data.tar.gz: f4df0ae89a078729eb319733ac7dab36943fa9e228daaba9fb75e6323a2f6fab
+  metadata.gz: fe9582d35d963462ff818674735f3b131607368f6adc6fdb70eac6152365efe8
+  data.tar.gz: a8e8b424702b4ca3ff2726a938ea0696f0b15bed3d82f449f803f64923bbbafc
 SHA512:
-  metadata.gz: 4c4e05cb41cf1259a74a73c24c45fa265da9fbaf6725905e9893f442e9e1a2dbf1979ba03c5aac030bafd9e2f574fa0fec50f1f11ee5fd583353e3fd7b8329ea
-  data.tar.gz: f53424206fd8224b815232c4c2babca237852829f4f43f8fe537f63136c65e7b25ae75d6276a4b07416b4c24cc8274b822946c6f03a2e6aa2c6f394cc5334327
+  metadata.gz: 4c6ae9f9e88f186d43aa13ef62c2c96d3c4ed65e0320558413df73915bd33478b673dae25dc4f3e3fdf6b0fe627ca595a8fc53cded6186ed3afb03ae08ef7f5d
+  data.tar.gz: 17ad431713b55f78b87a67b5de17db1e58c949895a08ff9d31b6f658aa277a8df8cab84f3d3ee178f9c70a9eb30557089fc0b732e2793b6c9b3c8054bf513b1c

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-02-03
+
+### Added
+- **Social Cards** - Auto-generate Open Graph images for social sharing with `social_cards.enabled: true` config (#146)
+- **Customize Command** - Generate theme customization files with `docyard customize` for custom CSS variables and scripts (#147)
+- **Pagefind Standalone Binary** - Download and cache Pagefind binary in `~/.docyard/bin/` for faster, more reliable search indexing without npx (#148)
+
+### Fixed
+- **Hot Reload JS Reinitialization** - Components now properly reinitialize when content changes during development (#149)
+
+### Documentation
+- Added new pages: Abbreviations component, Docs for AI (llms.txt)
+- Removed Troubleshooting page
+- Removed unsupported bluesky platform (33 platforms now supported)
+
 ## [1.1.0] - 2026-01-30
 
 ### Added
@@ -249,7 +264,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.1.0...HEAD
+[Unreleased]: https://github.com/sanifhimani/docyard/compare/v1.2.0...HEAD
+[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
 [1.0.1]: https://github.com/sanifhimani/docyard/compare/v1.0.0...v1.0.1

data/README.md

@@ -1,28 +1,73 @@
-# Docyard
+<p align="center">
+  <a href="https://docyard.dev">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="docs/public/logo-dark.svg">
+      <img src="docs/public/logo.svg" height="60" alt="Docyard">
+    </picture>
+  </a>
+</p>
 
-[![CI](https://github.com/sanifhimani/docyard/actions/workflows/ci.yml/badge.svg)](https://github.com/sanifhimani/docyard/actions/workflows/ci.yml)
-[![Gem Version](https://badge.fury.io/rb/docyard.svg)](https://badge.fury.io/rb/docyard)
+<p align="center">
+  Markdown to docs in seconds. No Node.js required.
+</p>
 
-Beautiful documentation sites from Markdown. Fast, simple, no configuration required.
+<p align="center">
+  <a href="https://github.com/sanifhimani/docyard/actions/workflows/ci.yml"><img src="https://github.com/sanifhimani/docyard/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://badge.fury.io/rb/docyard"><img src="https://badge.fury.io/rb/docyard.svg" alt="Gem Version"></a>
+  <a href="https://github.com/sanifhimani/docyard/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
+</p>
 
-## Quick Start
+<p align="center">
+  <a href="https://docyard.dev">Docs</a> ·
+  <a href="https://docyard.dev/getting-started/quickstart">Quickstart</a> ·
+  <a href="https://github.com/sanifhimani/docyard/blob/main/CHANGELOG.md">Changelog</a>
+</p>
+
+---
+
+## Install
 
 ```bash
 gem install docyard
-docyard init my-docs
-cd my-docs
+docyard init
 docyard serve
 ```
 
-Open http://localhost:4200 and start writing.
+Open `localhost:4200`. Edits reload instantly.
+
+## Example
+
+```markdown
+:::note
+Requires Ruby 3.2 or higher.
+:::
+
+:::tabs
+== macOS
+brew install ruby
+
+== Linux
+sudo apt install ruby-full
+:::
+```
+
+Callouts, tabs, steps, cards, code groups, accordions, and more. [See all components](https://docyard.dev/write-content/components)
+
+## Build
+
+```bash
+docyard build
+```
+
+Static HTML, search index, sitemap, and social cards in `dist/`. Deploy anywhere.
 
-## Documentation
+## Docs
 
-Visit [docyard.dev](https://docyard.dev) for the full documentation.
+[docyard.dev](https://docyard.dev) is built with Docyard.
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 

data/lib/docyard/build/asset_bundler.rb

@@ -32,6 +32,7 @@ module Docyard
       def bundle_css
         main_css = File.read(File.join(ASSETS_PATH, "css", "main.css"))
         css_content = resolve_css_imports(main_css)
+        css_content = append_custom_css(css_content)
         minified = CSSminify.compress(css_content)
         minified = fix_calc_whitespace(minified)
         minified = fix_css_math_functions(minified)
@@ -85,7 +86,8 @@ module Docyard
       def bundle_js
         theme_js = File.read(File.join(ASSETS_PATH, "js", "theme.js"))
         components_js = concatenate_component_js
-        js_content = [theme_js, components_js].join("\n")
+        custom_js = load_custom_js
+        js_content = [theme_js, components_js, custom_js].compact.join("\n")
         minified = Terser.compile(js_content)
         minified = replace_js_asset_urls(minified)
         hash = generate_hash(minified)
@@ -146,6 +148,20 @@ module Docyard
         FileUtils.mkdir_p(File.dirname(output_path))
         File.write(output_path, content)
       end
+
+      def append_custom_css(css_content)
+        custom_path = File.join(config.source, "_custom", "styles.css")
+        return css_content unless File.exist?(custom_path)
+
+        "#{css_content}\n#{File.read(custom_path)}"
+      end
+
+      def load_custom_js
+        custom_path = File.join(config.source, "_custom", "scripts.js")
+        return nil unless File.exist?(custom_path)
+
+        File.read(custom_path)
+      end
     end
   end
 end

data/lib/docyard/build/social_cards/card_renderer.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Build
+    module SocialCards
+      class CardRenderer
+        VIPS_INSTALL_INSTRUCTIONS = <<~MSG.strip
+          Social cards require libvips to be installed.
+
+          Install libvips:
+            macOS:  brew install vips
+            Ubuntu: sudo apt install libvips-dev
+            Fedora: sudo dnf install vips-devel
+
+          Then run: bundle install
+
+          Or disable social cards in docyard.yml:
+            social_cards:
+              enabled: false
+        MSG
+        WIDTH = 1200
+        HEIGHT = 630
+        BACKGROUND_COLOR = "#121212"
+        DEFAULT_BRAND_COLOR = "#22D3EE"
+        WHITE = "#FFFFFF"
+        GRAY = "#71717A"
+
+        PADDING = 88
+        LOGO_BOTTOM_OFFSET = 88
+
+        LOGO_ICON_WIDTH = 40
+        LOGO_ICON_HEIGHT = 58
+        LOGO_TEXT_SIZE = 28
+        LOGO_GAP = 16
+
+        attr_reader :config
+
+        def initialize(config)
+          @config = config
+        end
+
+        def render(output_path)
+          svg_content = build_svg
+          save_as_png(svg_content, output_path)
+        end
+
+        protected
+
+        def build_svg
+          <<~SVG
+            <svg xmlns="http://www.w3.org/2000/svg" width="#{WIDTH}" height="#{HEIGHT}" viewBox="0 0 #{WIDTH} #{HEIGHT}">
+              <defs>
+                <style>
+                  @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700;800&amp;display=swap');
+                  .inter { font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; }
+                </style>
+              </defs>
+              <rect width="#{WIDTH}" height="#{HEIGHT}" fill="#{BACKGROUND_COLOR}"/>
+              #{content_svg}
+              #{logo_svg}
+            </svg>
+          SVG
+        end
+
+        def content_svg
+          raise NotImplementedError, "Subclasses must implement content_svg"
+        end
+
+        def logo_svg
+          site_title = escape_xml(config.title || "Docyard")
+          logo_y = HEIGHT - LOGO_BOTTOM_OFFSET
+          logo_x, text_anchor = logo_position_and_anchor
+
+          <<~SVG
+            <g transform="translate(#{logo_x}, #{logo_y})">
+              #{logo_icon_svg(0, -LOGO_ICON_HEIGHT)}
+              <text x="#{LOGO_ICON_WIDTH + LOGO_GAP}" y="-#{(LOGO_ICON_HEIGHT / 2) - 10}" class="inter" font-size="#{LOGO_TEXT_SIZE}" font-weight="700" fill="#{WHITE}" text-anchor="#{text_anchor}">#{site_title}</text>
+            </g>
+          SVG
+        end
+
+        def logo_position_and_anchor
+          [PADDING, "start"]
+        end
+
+        def logo_icon_svg(x_offset, y_offset)
+          color = brand_color
+          scale = LOGO_ICON_WIDTH.to_f / 531
+          <<~SVG
+            <g transform="translate(#{x_offset}, #{y_offset}) scale(#{scale})">
+              <path fill="#{color}" d="M359.643 59.1798C402.213 89.4398 449.713 123.6 502.063 160.99C510.793 167.23 515.873 170.31 519.293 178.05C523.253 187.02 521.733 198.11 515.883 205.77C513.77 208.536 510.93 211.2 507.363 213.76C379.643 305.353 309.413 355.73 296.673 364.89C287.987 371.136 282.07 374.8 278.923 375.88C269.703 379.026 260.263 378.636 250.603 374.71C248.243 373.75 244.497 371.416 239.363 367.71C199.963 339.29 177.32 322.99 171.433 318.81C128.863 288.54 81.3733 254.39 29.0233 216.99C20.2833 210.75 15.2033 207.67 11.7833 199.93C7.82332 190.96 9.34332 179.87 15.1933 172.21C17.3067 169.443 20.1467 166.78 23.7133 164.22C151.433 72.6264 221.663 22.2498 234.403 13.0898C243.09 6.84309 249.007 3.17976 252.153 2.09976C261.373 -1.04691 270.813 -0.656912 280.473 3.26976C282.833 4.22976 286.58 6.56309 291.713 10.2698C331.113 38.6898 353.757 54.9931 359.643 59.1798Z"/>
+              <path fill="#{WHITE}" d="M467.383 298.01C483.943 286.23 505.033 289.93 519.063 303.51C524.457 308.723 528.033 314.713 529.793 321.48C530.433 323.92 530.733 330.946 530.693 342.56C530.647 356.206 530.657 427.233 530.723 555.64C530.723 566.633 530.513 573 530.093 574.74C527.033 587.29 518.333 592.61 506.693 601.06C504.313 602.786 430.877 656.346 286.383 761.74C275.623 769.59 261.793 770.79 250.113 764.36C249.18 763.846 245.86 761.513 240.153 757.36C150.56 692.066 74.8667 637.046 13.0733 592.3C6.70001 587.68 2.65667 581.73 0.943337 574.45C0.316671 571.783 0.00333476 564.803 0.00333476 553.51C-0.00333191 421.323 -4.06895e-06 348.98 0.0133293 336.48C0.0133293 332.84 -0.0766665 327.18 0.783334 323.18C4.59333 305.51 20.1033 293.29 37.4533 291.15C42.9467 290.476 48.8667 291.276 55.2133 293.55C58.28 294.643 63.3533 297.8 70.4333 303.02C75.98 307.113 82.4433 311.78 89.8233 317.02C128.563 344.526 178.703 380.303 240.243 424.35C242.73 426.13 245.853 428.246 249.613 430.7C257.443 435.8 268.453 436.24 277.213 433.14C279.8 432.22 284.54 429.283 291.433 424.33C394.46 350.276 453.11 308.17 467.383 298.01Z"/>
+            </g>
+          SVG
+        end
+
+        def brand_color
+          color = config.branding.color
+          if color.is_a?(Hash)
+            color["dark"] || color["light"] || DEFAULT_BRAND_COLOR
+          elsif color.is_a?(String) && !color.strip.empty?
+            color.strip
+          else
+            DEFAULT_BRAND_COLOR
+          end
+        end
+
+        def escape_xml(text)
+          text.to_s
+            .gsub("&", "&amp;")
+            .gsub("<", "&lt;")
+            .gsub(">", "&gt;")
+            .gsub('"', "&quot;")
+            .gsub("'", "&apos;")
+        end
+
+        def save_as_png(svg_content, output_path)
+          require_vips!
+          FileUtils.mkdir_p(File.dirname(output_path))
+          image = Vips::Image.svgload_buffer(svg_content, dpi: 96)
+          image.write_to_file(output_path, compression: 9, palette: true)
+        end
+
+        def require_vips!
+          require "vips"
+        rescue LoadError
+          raise Docyard::Error, VIPS_INSTALL_INSTRUCTIONS
+        end
+      end
+    end
+  end
+end

data/lib/docyard/build/social_cards/doc_card.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative "card_renderer"
+
+module Docyard
+  module Build
+    module SocialCards
+      class DocCard < CardRenderer
+        SECTION_LABEL_SIZE = 26
+        TITLE_SIZE = 92
+        DESCRIPTION_SIZE = 30
+
+        SECTION_TO_TITLE_GAP = 16
+        TITLE_TO_DESC_GAP = 24
+
+        LOGO_AREA_HEIGHT = 160
+
+        TITLE_MAX_CHARS = 22
+        DESCRIPTION_MAX_CHARS = 70
+
+        def initialize(config, title:, section: nil, description: nil)
+          super(config)
+          @title = truncate_text(title, TITLE_MAX_CHARS)
+          @section = section
+          @description = truncate_text(description, DESCRIPTION_MAX_CHARS)
+        end
+
+        protected
+
+        def content_svg
+          start_y = calculate_start_y
+          elements = []
+          y_pos = start_y
+
+          if @section && !@section.empty?
+            elements << section_svg(y_pos)
+            y_pos += SECTION_TO_TITLE_GAP + TITLE_SIZE
+          else
+            y_pos += TITLE_SIZE
+          end
+
+          elements << title_svg(y_pos)
+
+          if @description && !@description.empty?
+            y_pos += TITLE_TO_DESC_GAP + DESCRIPTION_SIZE
+            elements << description_svg(y_pos)
+          end
+
+          elements.join("\n")
+        end
+
+        private
+
+        def calculate_start_y
+          total_height = calculate_content_height
+          available_height = HEIGHT - LOGO_AREA_HEIGHT
+          (available_height - total_height) / 2
+        end
+
+        def calculate_content_height
+          height = TITLE_SIZE
+          height += SECTION_LABEL_SIZE + SECTION_TO_TITLE_GAP if @section && !@section.empty?
+          height += TITLE_TO_DESC_GAP + DESCRIPTION_SIZE if @description && !@description.empty?
+          height
+        end
+
+        def section_svg(y_pos)
+          section_text = escape_xml(@section.upcase)
+          <<~SVG
+            <text x="#{PADDING}" y="#{y_pos}" class="inter" font-size="#{SECTION_LABEL_SIZE}" font-weight="600" fill="#{brand_color}" letter-spacing="0.5">#{section_text}</text>
+          SVG
+        end
+
+        def title_svg(y_pos)
+          title_text = escape_xml(@title)
+          <<~SVG
+            <text x="#{PADDING}" y="#{y_pos}" class="inter" font-size="#{TITLE_SIZE}" font-weight="800" fill="#{WHITE}" letter-spacing="-0.02em">#{title_text}</text>
+          SVG
+        end
+
+        def description_svg(y_pos)
+          desc_text = escape_xml(@description)
+          <<~SVG
+            <text x="#{PADDING}" y="#{y_pos}" class="inter" font-size="#{DESCRIPTION_SIZE}" font-weight="400" fill="#{GRAY}">#{desc_text}</text>
+          SVG
+        end
+
+        def truncate_text(text, max_chars)
+          return nil if text.nil?
+          return text if text.length <= max_chars
+
+          "#{text[0, max_chars - 3].strip}..."
+        end
+      end
+    end
+  end
+end

data/lib/docyard/build/social_cards/homepage_card.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative "card_renderer"
+
+module Docyard
+  module Build
+    module SocialCards
+      class HomepageCard < CardRenderer
+        TITLE_SIZE = 84
+        TITLE_MAX_WIDTH = 1024
+
+        def initialize(config, title:)
+          super(config)
+          @title = title
+        end
+
+        protected
+
+        def content_svg
+          title_text = escape_xml(@title)
+          logo_area = LOGO_ICON_HEIGHT + LOGO_BOTTOM_OFFSET + 40
+          title_y = (HEIGHT - logo_area) / 2
+
+          <<~SVG
+            #{background_curves}
+            <text x="#{WIDTH / 2}" y="#{title_y}" class="inter" font-size="#{TITLE_SIZE}" font-weight="700" fill="#{brand_color}" text-anchor="middle" dominant-baseline="middle">
+              #{wrap_text(title_text, TITLE_SIZE, TITLE_MAX_WIDTH)}
+            </text>
+          SVG
+        end
+
+        def background_curves
+          <<~SVG
+            <g fill="none" stroke="#1f1f1f" stroke-width="4">
+              <!-- Top left flowing down -->
+              <ellipse cx="-200" cy="-100" rx="500" ry="400"/>
+              <ellipse cx="-300" cy="200" rx="600" ry="500"/>
+              <!-- Top right diagonal -->
+              <ellipse cx="1400" cy="-200" rx="550" ry="450"/>
+              <ellipse cx="1100" cy="-300" rx="700" ry="600"/>
+              <!-- Bottom crossing -->
+              <ellipse cx="200" cy="800" rx="500" ry="400"/>
+              <ellipse cx="1000" cy="900" rx="600" ry="450"/>
+              <!-- Mid crossing -->
+              <ellipse cx="1500" cy="400" rx="450" ry="550"/>
+            </g>
+          SVG
+        end
+
+        def logo_position_and_anchor
+          [
+            (WIDTH / 2) - ((LOGO_ICON_WIDTH + LOGO_GAP + estimate_text_width(config.title || "Docyard",
+                                                                             LOGO_TEXT_SIZE)) / 2), "start"
+          ]
+        end
+
+        private
+
+        def wrap_text(text, font_size, max_width)
+          lines = split_into_lines(text, max_width, font_size)
+          lines_to_tspans(lines, font_size)
+        end
+
+        def split_into_lines(text, max_width, font_size)
+          chars_per_line = (max_width / (font_size * 0.5)).to_i
+          words = text.split
+          lines = []
+          current_line = []
+
+          words.each { |word| current_line, lines = process_word(word, current_line, lines, chars_per_line) }
+          lines << current_line.join(" ") if current_line.any?
+          lines
+        end
+
+        def process_word(word, current_line, lines, chars_per_line)
+          test_line = (current_line + [word]).join(" ")
+          if test_line.length > chars_per_line && current_line.any?
+            lines << current_line.join(" ")
+            [[word], lines]
+          else
+            [current_line + [word], lines]
+          end
+        end
+
+        def lines_to_tspans(lines, font_size)
+          lines.map.with_index do |line, i|
+            dy = i.zero? ? 0 : font_size * 1.15
+            %(<tspan x="#{WIDTH / 2}" dy="#{dy}">#{line}</tspan>)
+          end.join
+        end
+
+        def estimate_text_width(text, font_size)
+          text.length * font_size * 0.55
+        end
+      end
+    end
+  end
+end

data/lib/docyard/build/social_cards_generator.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "yaml"
+require "parallel"
+require_relative "social_cards/card_renderer"
+require_relative "social_cards/homepage_card"
+require_relative "social_cards/doc_card"
+
+module Docyard
+  module Build
+    class SocialCardsGenerator
+      OUTPUT_DIR = "_docyard/og"
+      FRONTMATTER_REGEX = /\A---\s*\n(.*?\n)---\s*\n/m
+      HOMEPAGE_PATHS = ["/", "/index"].freeze
+      PARALLEL_THRESHOLD = 5
+
+      attr_reader :config, :verbose
+
+      def initialize(config, verbose: false)
+        @config = config
+        @verbose = verbose
+        @generated_cards = []
+        @failed_cards = []
+      end
+
+      def generate
+        ensure_vips_available!
+        pages = collect_pages
+        generate_cards_for(pages)
+        [successful_count, build_verbose_details]
+      end
+
+      def successful_count
+        @generated_cards.compact.size
+      end
+
+      def card_path_for(url_path)
+        File.join("/", OUTPUT_DIR, url_to_filename(url_path))
+      end
+
+      private
+
+      def generate_cards_for(pages)
+        if pages.size >= PARALLEL_THRESHOLD
+          results = Parallel.map(pages, in_threads: Parallel.processor_count) do |page|
+            generate_card(page)
+          end
+          @generated_cards = results.compact
+        else
+          pages.each { |page| @generated_cards << generate_card(page) }
+        end
+      end
+
+      def collect_pages
+        pages = []
+
+        Dir.glob(File.join(docs_path, "**", "*.md")).each do |file_path|
+          frontmatter = extract_frontmatter(file_path)
+          relative_path = file_path.delete_prefix("#{docs_path}/")
+          url_path = markdown_to_url(relative_path)
+
+          pages << build_page_data(file_path, url_path, frontmatter)
+        end
+
+        pages
+      end
+
+      def build_page_data(file_path, url_path, frontmatter)
+        social_cards_config = frontmatter["social_cards"] || {}
+        section = derive_section(url_path)
+
+        {
+          file_path: file_path,
+          url_path: url_path,
+          title: resolve_title(social_cards_config, frontmatter, url_path),
+          description: social_cards_config["description"] || frontmatter["description"],
+          section: section,
+          is_homepage: homepage?(url_path)
+        }
+      end
+
+      def resolve_title(social_cards_config, frontmatter, url_path)
+        title = social_cards_config["title"]
+        return title if title && !title.strip.empty?
+
+        title = frontmatter["title"]
+        return title if title && !title.strip.empty?
+
+        derive_title_from_path(url_path)
+      end
+
+      def ensure_vips_available!
+        require "vips"
+      rescue LoadError
+        raise Docyard::Error, SocialCards::CardRenderer::VIPS_INSTALL_INSTRUCTIONS
+      end
+
+      def generate_card(page)
+        output_path = File.join(config.build.output, OUTPUT_DIR, url_to_filename(page[:url_path]))
+        card = build_card_for(page)
+        card.render(output_path)
+        output_path
+      rescue StandardError => e
+        log_card_error(page, e.message)
+        nil
+      end
+
+      def log_card_error(page, message)
+        @failed_cards << page[:url_path]
+        Docyard.logger.warn("Social card generation failed for #{page[:url_path]}: #{message}")
+      end
+
+      def build_card_for(page)
+        if page[:is_homepage]
+          SocialCards::HomepageCard.new(config, title: page[:title])
+        else
+          SocialCards::DocCard.new(
+            config,
+            title: page[:title],
+            section: page[:section],
+            description: page[:description]
+          )
+        end
+      end
+
+      def extract_frontmatter(file_path)
+        content = File.read(file_path)
+        match = content.match(FRONTMATTER_REGEX)
+        return {} unless match
+
+        YAML.safe_load(match[1]) || {}
+      rescue Psych::SyntaxError
+        {}
+      end
+
+      def markdown_to_url(relative_path)
+        path = relative_path
+          .delete_suffix(".md")
+          .delete_suffix("/index")
+
+        path = "index" if path == "index" || path.empty?
+        "/#{path}"
+      end
+
+      def url_to_filename(url_path)
+        path = url_path.delete_prefix("/")
+        path = "index" if path.empty?
+        "#{path}.png"
+      end
+
+      def homepage?(url_path)
+        HOMEPAGE_PATHS.include?(url_path)
+      end
+
+      def derive_section(url_path)
+        parts = url_path.delete_prefix("/").split("/")
+        return nil if parts.size <= 1
+
+        parts.first.tr("-", " ").split.map(&:capitalize).join(" ")
+      end
+
+      def derive_title_from_path(url_path)
+        filename = File.basename(url_path)
+        filename = "Home" if filename == "index" || filename.empty?
+        filename.tr("-", " ").split.map(&:capitalize).join(" ")
+      end
+
+      def docs_path
+        config.source
+      end
+
+      def build_verbose_details
+        return nil unless verbose
+
+        details = @generated_cards.compact.map do |path|
+          path.delete_prefix("#{config.build.output}/")
+        end
+
+        @failed_cards.each do |url_path|
+          details << "FAILED: #{url_path}"
+        end
+
+        details
+      end
+    end
+  end
+end