docyard 1.1.0 → 1.2.0

data/lib/docyard/build/step_runner.rb

@@ -5,6 +5,7 @@ module Docyard
     class StepRunner
       STEP_SHORT_LABELS = {
         "Generating pages" => "Pages",
+        "Social cards" => "Cards",
         "Bundling assets" => "Assets",
         "Copying files" => "Files",
         "Generating SEO" => "SEO",
@@ -59,6 +60,7 @@ module Docyard
       def format_result(label, result)
         case label
         when "Generating pages" then "done (#{result} pages)"
+        when "Social cards" then "done (#{result} cards)"
         when "Bundling assets" then format_assets_result(result)
         when "Copying files" then "done (#{result} files)"
         when "Generating SEO" then "done (#{result.join(', ')})"

data/lib/docyard/builder.rb

@@ -52,6 +52,7 @@ module Docyard
       @step_runner.run("Generating pages") { generate_static_pages }
       @step_runner.run("Bundling assets") { bundle_assets }
       @step_runner.run("Copying files") { copy_static_files }
+      @step_runner.run("Social cards") { generate_social_cards } if social_cards_enabled?
       @step_runner.run("Generating SEO") { generate_seo_files }
       @step_runner.run("Indexing search") { generate_search_index }
     end
@@ -130,6 +131,15 @@ module Docyard
       Search::BuildIndexer.new(config, verbose: verbose).index
     end
 
+    def generate_social_cards
+      require_relative "build/social_cards_generator"
+      Build::SocialCardsGenerator.new(config, verbose: verbose).generate
+    end
+
+    def social_cards_enabled?
+      config.social_cards&.enabled == true
+    end
+
     def robots_txt_content
       base = config.build.base
       base = "#{base}/" unless base.end_with?("/")

data/lib/docyard/cli.rb

@@ -80,6 +80,23 @@ module Docyard
       exit(doctor.run)
     end
 
+    desc "customize", "Generate theme customization files"
+    method_option :minimal, type: :boolean, default: false, aliases: "-m",
+                            desc: "Generate minimal files without comments"
+    def customize
+      apply_global_options
+      require_relative "customizer"
+      Docyard::Customizer.new(minimal: options[:minimal]).generate
+    rescue ConfigError => e
+      print_config_error(e)
+    rescue Errno::EACCES => e
+      print_file_error("Permission denied", e.message)
+    rescue Errno::ENOSPC
+      print_file_error("Disk full", "No space left on device")
+    rescue SystemCallError => e
+      print_file_error("File operation failed", e.message)
+    end
+
     private
 
     def apply_global_options
@@ -94,5 +111,15 @@ module Docyard
       puts
       exit(1)
     end
+
+    def print_file_error(title, message)
+      puts
+      puts "  #{UI.bold('Docyard')} v#{VERSION}"
+      puts
+      puts "  #{UI.red("#{title}:")}"
+      puts "    #{message}"
+      puts
+      exit(1)
+    end
   end
 end

data/lib/docyard/config/branding_resolver.rb

@@ -38,7 +38,7 @@ module Docyard
         site_options, logo_options, search_options, credits_options, social_options,
         navigation_options, tabs_options, announcement_options, repo_options, analytics_options,
         color_options
-      ].reduce({}, :merge)
+      ].reduce({}, :merge).merge(social_cards_enabled: config.social_cards&.enabled == true)
     end
 
     def site_options

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

@@ -22,7 +22,8 @@ module Docyard
         announcement: ANNOUNCEMENT_SCHEMA,
         repo: REPO_SCHEMA,
         analytics: ANALYTICS_SCHEMA,
-        feedback: FEEDBACK_SCHEMA
+        feedback: FEEDBACK_SCHEMA,
+        social_cards: SOCIAL_CARDS_SCHEMA
       }.freeze
     end
   end

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

@@ -15,7 +15,6 @@ module Docyard
           slack: { type: :url },
           linkedin: { type: :url },
           youtube: { type: :url },
-          bluesky: { type: :url },
           custom: {
             type: :array,
             items: {

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

@@ -73,6 +73,13 @@ module Docyard
           question: { type: :string }
         }
       }.freeze
+
+      SOCIAL_CARDS_SCHEMA = {
+        type: :hash,
+        keys: {
+          enabled: { type: :boolean }
+        }
+      }.freeze
     end
   end
 end

data/lib/docyard/config.rb

@@ -26,7 +26,8 @@ module Docyard
       "repo" => { "url" => nil, "branch" => "main", "edit_path" => nil, "edit_link" => true,
                   "last_updated" => true },
       "analytics" => { "google" => nil, "plausible" => nil, "fathom" => nil, "script" => nil },
-      "feedback" => { "enabled" => false, "question" => "Was this page helpful?" }
+      "feedback" => { "enabled" => false, "question" => "Was this page helpful?" },
+      "social_cards" => { "enabled" => false }
     }.freeze
 
     attr_reader :data, :file_path
@@ -63,6 +64,7 @@ module Docyard
     def repo = @repo ||= Section.new(data["repo"])
     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 announcement
       @announcement ||= data["announcement"] ? Section.new(data["announcement"]) : nil

data/lib/docyard/customizer.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Customizer
+    CUSTOM_DIR = "_custom"
+    STYLES_FILE = "styles.css"
+    SCRIPTS_FILE = "scripts.js"
+    VARIABLES_PATH = File.join(__dir__, "templates", "assets", "css", "variables.css")
+
+    CATEGORY_PATTERNS = {
+      /^--sidebar-width/ => "Layout",
+      /^--sidebar/ => "Sidebar",
+      /^--code|^--diff/ => "Code",
+      /^--callout/ => "Callouts",
+      /^--table|^--hr/ => "Tables",
+      /^--search|^--overlay/ => "Search",
+      /^--font|^--text|^--leading/ => "Typography",
+      /^--spacing/ => "Spacing",
+      /^--toc|^--header|^--content|^--layout|^--tab-bar|^--secondary-header/ => "Layout",
+      /^--radius/ => "Radius",
+      /^--shadow/ => "Shadows",
+      /^--transition/ => "Transitions",
+      /^--z-/ => "Z-Index",
+      /^--ring/ => "Other"
+    }.freeze
+
+    CATEGORIES = %w[
+      Colors Sidebar Code Callouts Tables Search
+      Typography Spacing Layout Radius Shadows Transitions Z-Index Other
+    ].freeze
+
+    attr_reader :config, :minimal
+
+    def initialize(minimal: false)
+      @config = Config.load
+      @minimal = minimal
+    end
+
+    def generate
+      validate_source_directory
+      create_custom_directory
+      write_styles_file
+      write_scripts_file
+      print_success
+    end
+
+    private
+
+    def validate_source_directory
+      return if File.directory?(config.source)
+
+      raise ConfigError, "Source directory '#{config.source}' does not exist"
+    end
+
+    def custom_dir_path
+      @custom_dir_path ||= File.join(config.source, CUSTOM_DIR)
+    end
+
+    def styles_path
+      @styles_path ||= File.join(custom_dir_path, STYLES_FILE)
+    end
+
+    def scripts_path
+      @scripts_path ||= File.join(custom_dir_path, SCRIPTS_FILE)
+    end
+
+    def create_custom_directory
+      FileUtils.mkdir_p(custom_dir_path)
+    end
+
+    def write_styles_file
+      File.write(styles_path, minimal ? minimal_styles : annotated_styles)
+    end
+
+    def write_scripts_file
+      File.write(scripts_path, minimal ? minimal_scripts : annotated_scripts)
+    end
+
+    def annotated_styles
+      build_annotated_css(parse_variables)
+    end
+
+    def minimal_styles
+      build_minimal_css(parse_variables)
+    end
+
+    def parse_variables
+      content = File.read(VARIABLES_PATH)
+      { light: extract_variables(content, ":root"), dark: extract_variables(content, ".dark") }
+    end
+
+    def extract_variables(content, selector)
+      match = content.match(/#{Regexp.escape(selector)}\s*\{([^}]+)\}/m)
+      return [] unless match
+
+      match[1].scan(/(--[\w-]+):\s*([^;]+);/).map { |name, value| { name: name, value: value.strip } }
+    end
+
+    def build_annotated_css(variables)
+      light = format_annotated(variables[:light])
+      dark = format_annotated(variables[:dark])
+      "#{css_header}:root {\n#{light}\n}\n\n.dark {\n#{dark}\n}\n"
+    end
+
+    def build_minimal_css(variables)
+      ":root {\n#{format_minimal(variables[:light])}\n}\n\n.dark {\n#{format_minimal(variables[:dark])}\n}\n"
+    end
+
+    def css_header
+      <<~HEADER
+        /* =============================================================================
+           DOCYARD THEME CUSTOMIZATION
+
+           Uncomment and modify variables to customize your site.
+           Delete any variables you don't need to change.
+
+           Generated with: docyard customize
+           ============================================================================= */
+
+      HEADER
+    end
+
+    def format_annotated(vars)
+      group_variables(vars).flat_map do |category, category_vars|
+        ["  /* #{category} */"] + category_vars.map { |v| "  /* #{v[:name]}: #{v[:value]}; */" } + [""]
+      end.join("\n").rstrip
+    end
+
+    def format_minimal(vars)
+      vars.map { |var| "  /* #{var[:name]}: #{var[:value]}; */" }.join("\n")
+    end
+
+    def group_variables(vars)
+      groups = CATEGORIES.to_h { |cat| [cat, []] }
+      vars.each { |var| groups[categorize_variable(var[:name])] << var }
+      groups.reject { |_, v| v.empty? }
+    end
+
+    def categorize_variable(name)
+      CATEGORY_PATTERNS.each { |pattern, category| return category if name.match?(pattern) }
+      "Colors"
+    end
+
+    def annotated_scripts
+      "#{js_header}document.addEventListener('DOMContentLoaded', function() {\n  // Your custom JavaScript here\n});\n"
+    end
+
+    def js_header
+      <<~HEADER
+        /* =============================================================================
+           DOCYARD CUSTOM SCRIPTS
+
+           This file is loaded on every page after the default scripts.
+
+           Generated with: docyard customize
+           ============================================================================= */
+
+      HEADER
+    end
+
+    def minimal_scripts
+      "document.addEventListener('DOMContentLoaded', function() {\n  // Your custom JavaScript here\n});\n"
+    end
+
+    def print_success
+      puts
+      print_header
+      print_created_files
+      print_next_steps
+    end
+
+    def print_header
+      puts "  #{UI.bold('Docyard')} v#{VERSION}"
+      puts
+    end
+
+    def print_created_files
+      puts "  #{UI.success('Created:')}"
+      puts UI.dim("    #{relative_path(custom_dir_path)}/")
+      puts UI.dim("        #{STYLES_FILE}")
+      puts UI.dim("        #{SCRIPTS_FILE}")
+      puts
+    end
+
+    def print_next_steps
+      puts "  #{UI.bold('Next steps:')}"
+      puts "    Edit #{UI.cyan(relative_path(styles_path))} to customize theme"
+      puts "    Changes apply on next serve or build"
+      puts
+    end
+
+    def relative_path(path)
+      path.sub("#{Dir.pwd}/", "")
+    end
+  end
+end

data/lib/docyard/rendering/markdown.rb

@@ -69,6 +69,10 @@ module Docyard
       frontmatter["og_image"]
     end
 
+    def social_cards
+      frontmatter["social_cards"]
+    end
+
     def toc
       @context[:toc] || []
     end

data/lib/docyard/rendering/og_helpers.rb

@@ -2,6 +2,8 @@
 
 module Docyard
   module OgHelpers
+    SOCIAL_CARDS_OUTPUT_DIR = "_docyard/og"
+
     def assign_og_variables(branding, page_description, page_og_image, current_path)
       site_url = branding[:site_url]
       @og_enabled = !site_url.nil? && !site_url.empty?
@@ -9,12 +11,28 @@ module Docyard
 
       @og_url = build_canonical_url(site_url, current_path)
       @og_description = page_description || @site_description
-      @og_image = build_og_image_url(site_url, page_og_image || branding[:og_image])
+      @og_image = resolve_og_image(site_url, page_og_image, branding, current_path)
       @og_twitter = branding[:twitter]
     end
 
     private
 
+    def resolve_og_image(site_url, page_og_image, branding, current_path)
+      explicit_image = page_og_image || branding[:og_image]
+      return build_og_image_url(site_url, explicit_image) if explicit_image
+
+      return nil unless branding[:social_cards_enabled]
+
+      generated_card_path = social_card_path_for(current_path)
+      build_og_image_url(site_url, generated_card_path)
+    end
+
+    def social_card_path_for(current_path)
+      path = current_path.delete_prefix("/")
+      path = "index" if path.empty?
+      "/#{SOCIAL_CARDS_OUTPUT_DIR}/#{path}.png"
+    end
+
     def build_canonical_url(site_url, current_path)
       base = site_url.chomp("/")
       path = current_path.start_with?("/") ? current_path : "/#{current_path}"

data/lib/docyard/rendering/renderer.rb

@@ -8,7 +8,7 @@ require_relative "og_helpers"
 require_relative "branding_variables"
 
 module Docyard
-  class Renderer
+  class Renderer # rubocop:disable Metrics/ClassLength
     include Utils::UrlHelpers
     include Utils::HtmlHelpers
     include IconHelpers
@@ -153,6 +153,15 @@ module Docyard
       @toc = navigation[:toc] || []
       @breadcrumbs = navigation[:breadcrumbs]
       @raw_markdown = raw_markdown
+      assign_custom_file_variables
+    end
+
+    def assign_custom_file_variables
+      source_dir = config&.source || "docs"
+      custom_css_path = File.join(source_dir, "_custom", "styles.css")
+      custom_js_path = File.join(source_dir, "_custom", "scripts.js")
+      @custom_css_exists = File.exist?(custom_css_path)
+      @custom_js_exists = File.exist?(custom_js_path)
     end
 
     def assign_template_variables(template_options)

data/lib/docyard/search/build_indexer.rb

@@ -7,8 +7,6 @@ module Docyard
     class BuildIndexer
       include PagefindSupport
 
-      PAGEFIND_COMMAND = "npx"
-
       attr_reader :config, :output_dir, :verbose
 
       def initialize(config, verbose: false)
@@ -26,10 +24,17 @@ module Docyard
 
       private
 
+      def pagefind_available?
+        result = super
+        Docyard.logger.warn("Search disabled: Pagefind binary not available") unless result
+        result
+      end
+
       def run_pagefind
+        command = pagefind_command
         args = build_pagefind_args(output_dir)
 
-        stdout, stderr, status = Open3.capture3(PAGEFIND_COMMAND, *args)
+        stdout, stderr, status = Open3.capture3(*command, *args)
 
         if status.success?
           count = extract_page_count(stdout)

data/lib/docyard/search/dev_indexer.rb

@@ -50,7 +50,7 @@ module Docyard
 
       def pagefind_available?
         result = super
-        Docyard.logger.warn("Search disabled: Pagefind not found (npm install -g pagefind)") unless result
+        Docyard.logger.warn("Search disabled: Pagefind binary not available") unless result
         result
       end
 
@@ -132,8 +132,9 @@ module Docyard
       end
 
       def run_pagefind
+        command = pagefind_command
         args = build_pagefind_args(temp_dir)
-        stdout, stderr, status = Open3.capture3("npx", *args)
+        stdout, stderr, status = Open3.capture3(*command, *args)
 
         raise "Pagefind failed: #{stderr}" unless status.success?
 

data/lib/docyard/search/pagefind_binary.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "net/http"
+require "open3"
+require "rubygems/package"
+require "zlib"
+
+module Docyard
+  module Search
+    class PagefindBinary
+      VERSION = "1.3.0"
+      CACHE_DIR = File.join(Dir.home, ".docyard", "bin")
+      DOWNLOAD_BASE = "https://github.com/CloudCannon/pagefind/releases/download"
+
+      DOWNLOAD_TIMEOUT = 30
+      MAX_REDIRECTS = 5
+
+      PLATFORMS = {
+        %w[darwin arm64] => "aarch64-apple-darwin",
+        %w[darwin x86_64] => "x86_64-apple-darwin",
+        %w[linux x86_64] => "x86_64-unknown-linux-musl",
+        %w[linux aarch64] => "aarch64-unknown-linux-musl",
+        %w[mingw x64] => "x86_64-pc-windows-msvc"
+      }.freeze
+
+      class << self
+        def executable
+          @executable ||= resolve_executable
+        end
+
+        def reset!
+          @executable = nil
+        end
+
+        private
+
+        def resolve_executable
+          cached_path || download_binary || npx_fallback
+        end
+
+        def cached_path
+          path = binary_path
+          return path if path && File.executable?(path)
+
+          nil
+        end
+
+        def binary_path
+          platform = detect_platform
+          return nil unless platform
+
+          dir = File.join(CACHE_DIR, "pagefind-#{VERSION}-#{platform}")
+          ext = platform.include?("windows") ? ".exe" : ""
+          File.join(dir, "pagefind#{ext}")
+        end
+
+        def detect_platform
+          os = normalize_os(RbConfig::CONFIG["host_os"])
+          cpu = normalize_cpu(RbConfig::CONFIG["host_cpu"])
+          PLATFORMS[[os, cpu]]
+        end
+
+        def normalize_os(host_os)
+          case host_os
+          when /darwin/i then "darwin"
+          when /linux/i then "linux"
+          when /mingw|mswin|cygwin/i then "mingw"
+          end
+        end
+
+        def normalize_cpu(host_cpu)
+          case host_cpu
+          when /\Aarm64\z/i then "arm64"
+          when /\Aaarch64\z/i then "aarch64"
+          when /\Ax86_64\z/i, /\Aamd64\z/i then "x86_64"
+          when /\Ax64\z/i then "x64"
+          end
+        end
+
+        def download_binary
+          platform = detect_platform
+          return nil unless platform
+
+          perform_download(platform)
+        rescue StandardError => e
+          Docyard.logger.debug("Failed to download Pagefind: #{e.message}")
+          nil
+        end
+
+        def perform_download(platform)
+          tar_url = build_tar_url(platform)
+          sha_url = "#{tar_url}.sha256"
+
+          expected_checksum = fetch_checksum(sha_url)
+          return nil unless expected_checksum
+
+          tar_data = download_file(tar_url)
+          return nil unless tar_data
+
+          return nil unless checksum_valid?(tar_data, expected_checksum)
+
+          extract_binary(tar_data, platform)
+        end
+
+        def build_tar_url(platform)
+          tar_filename = "pagefind-v#{VERSION}-#{platform}.tar.gz"
+          "#{DOWNLOAD_BASE}/v#{VERSION}/#{tar_filename}"
+        end
+
+        def checksum_valid?(tar_data, expected_checksum)
+          actual_checksum = Digest::SHA256.hexdigest(tar_data)
+          return true if actual_checksum == expected_checksum
+
+          Docyard.logger.warn("Pagefind checksum mismatch: expected #{expected_checksum}, got #{actual_checksum}")
+          false
+        end
+
+        def fetch_checksum(url)
+          response = download_file(url)
+          return nil unless response
+
+          response.split.first
+        end
+
+        def download_file(url, redirect_count = 0)
+          return nil if redirect_count >= MAX_REDIRECTS
+
+          uri = URI(url)
+          response = http_get(uri)
+
+          case response
+          when Net::HTTPSuccess then response.body
+          when Net::HTTPRedirection then download_file(response["location"], redirect_count + 1)
+          end
+        end
+
+        def http_get(uri)
+          Net::HTTP.start(
+            uri.host, uri.port,
+            use_ssl: uri.scheme == "https",
+            open_timeout: DOWNLOAD_TIMEOUT,
+            read_timeout: DOWNLOAD_TIMEOUT
+          ) { |http| http.request(Net::HTTP::Get.new(uri)) }
+        end
+
+        def extract_binary(tar_data, platform)
+          target_dir = File.join(CACHE_DIR, "pagefind-#{VERSION}-#{platform}")
+          FileUtils.mkdir_p(target_dir)
+
+          binary_name = platform.include?("windows") ? "pagefind.exe" : "pagefind"
+          target_path = File.join(target_dir, binary_name)
+
+          extract_from_tar(tar_data, binary_name, target_path)
+        end
+
+        def extract_from_tar(tar_data, binary_name, target_path)
+          io = StringIO.new(tar_data)
+          Zlib::GzipReader.wrap(io) do |gz|
+            Gem::Package::TarReader.new(gz) do |tar|
+              tar.each do |entry|
+                next unless entry.file? && File.basename(entry.full_name) == binary_name
+
+                File.binwrite(target_path, entry.read)
+                File.chmod(0o755, target_path)
+                return target_path
+              end
+            end
+          end
+          nil
+        end
+
+        def npx_fallback
+          _, _, status = Open3.capture3("npx", "pagefind", "--version")
+          return "npx" if status.success?
+
+          nil
+        rescue Errno::ENOENT
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/docyard/search/pagefind_support.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "open3"
-
 module Docyard
   module Search
     module PagefindSupport
@@ -10,14 +8,18 @@ module Docyard
       end
 
       def pagefind_available?
-        _stdout, _stderr, status = Open3.capture3("npx", "pagefind", "--version")
-        status.success?
-      rescue Errno::ENOENT
-        false
+        !PagefindBinary.executable.nil?
+      end
+
+      def pagefind_command
+        executable = PagefindBinary.executable
+        return nil unless executable
+
+        executable == "npx" ? %w[npx pagefind] : [executable]
       end
 
       def build_pagefind_args(site_dir)
-        args = ["pagefind", "--site", site_dir, "--output-subdir", "_docyard/pagefind"]
+        args = ["--site", site_dir, "--output-subdir", "_docyard/pagefind"]
 
         exclusions = config.search.exclude || []
         exclusions.each do |pattern|