docyard 1.1.0 → 1.3.0

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

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,40 @@ 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"
+    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 +128,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/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

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require "fileutils"
+require_relative "base"
+
+module Docyard
+  module Deploy
+    module Adapters
+      class GithubPages < Base
+        def platform_name
+          "GitHub Pages"
+        end
+
+        private
+
+        def cli_name
+          "gh"
+        end
+
+        def cli_install_hint
+          "https://cli.github.com"
+        end
+
+        def run_deploy
+          remote_url = fetch_remote_url
+          Dir.mktmpdir do |tmp|
+            prepare_deploy_dir(tmp)
+            push_to_gh_pages(tmp, remote_url)
+          end
+          build_pages_url(remote_url)
+        end
+
+        def fetch_remote_url
+          execute_command("git", "remote", "get-url", "origin").strip
+        end
+
+        def prepare_deploy_dir(tmp)
+          FileUtils.cp_r("#{output_dir}/.", tmp)
+          execute_command("git", "-C", tmp, "init", "-b", "gh-pages")
+          execute_command("git", "-C", tmp, "add", ".")
+          execute_command("git", "-C", tmp, "commit", "-m", "Deploy via docyard")
+        end
+
+        def push_to_gh_pages(tmp, remote_url)
+          execute_command("git", "-C", tmp, "remote", "add", "origin", remote_url)
+          execute_command("git", "-C", tmp, "push", "--force", "origin", "gh-pages")
+        end
+
+        def build_pages_url(remote_url)
+          match = remote_url.match(%r{github\.com[:/]([^/]+)/([^/.]+)})
+          return nil unless match
+
+          owner, repo = match.captures
+          "https://#{owner}.github.io/#{repo}/"
+        end
+      end
+    end
+  end
+end