docyard 1.0.2 → 1.2.0

data/lib/docyard/builder.rb

@@ -1,84 +1,143 @@
 # frozen_string_literal: true
 
 require "fileutils"
-require "tty-progressbar"
+require_relative "build/step_runner"
 
 module Docyard
   class Builder
-    attr_reader :config, :clean, :verbose, :start_time
+    attr_reader :config, :clean, :verbose, :strict, :start_time
 
-    def initialize(clean: true, verbose: false)
+    def initialize(clean: true, verbose: false, strict: false)
       @config = Config.new
       @clean = clean
       @verbose = verbose
+      @strict = strict || config.build.strict
       @start_time = Time.now
+      @step_runner = Build::StepRunner.new(verbose: verbose)
     end
 
     def build
-      prepare_output_directory
-      log "Building static site..."
-
-      pages_built = generate_static_pages
-      bundles_created = bundle_assets
-      assets_copied = copy_static_files
-      generate_seo_files
-      pages_indexed = generate_search_index
+      return false unless passes_validation?
 
-      display_summary(pages_built, bundles_created, assets_copied, pages_indexed)
+      print_header
+      prepare_output_directory
+      execute_build_steps
+      print_summary
       true
     rescue StandardError => e
-      error "Build failed: #{e.message}"
-      error e.backtrace.first if verbose
+      print_error(e)
       false
     end
 
     private
 
-    def prepare_output_directory
-      output_dir = config.build.output
+    def print_header
+      puts
+      puts "  #{UI.bold('Docyard')} v#{VERSION}"
+      puts
+      puts "  Building to #{UI.dim("#{config.build.output}/")}..."
+      puts
+    end
+
+    def passes_validation?
+      require_relative "build/validator"
+      validator = Build::Validator.new(config, strict: strict)
+      return true if validator.valid?
+
+      validator.print_errors
+      false
+    end
 
-      if clean && Dir.exist?(output_dir)
-        log "[✓] Cleaning #{output_dir}/ directory"
-        FileUtils.rm_rf(output_dir)
-      end
+    def execute_build_steps
+      @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
+
+    def print_error(error)
+      puts UI.error("failed")
+      puts
+      puts "  #{UI.error('Error:')} #{error.message}"
+      puts "  #{error.backtrace.first}" if verbose
+      puts
+    end
+
+    def print_summary
+      puts
+      puts "  #{UI.success('Build complete')} in #{format('%.2fs', build_duration)}"
+      puts "  #{UI.dim(output_summary)}"
+      puts
+      @step_runner.print_timing_breakdown if verbose
+    end
 
+    def build_duration
+      Time.now - start_time
+    end
+
+    def output_summary
+      "Output: #{config.build.output}/ (#{format_size(calculate_output_size)})"
+    end
+
+    def format_size(bytes)
+      kb = bytes / 1024.0
+      kb >= 1000 ? format("%.1f MB", kb / 1024.0) : format("%.1f KB", kb)
+    end
+
+    def calculate_output_size
+      Dir.glob(File.join(config.build.output, "**", "*"))
+        .select { |f| File.file?(f) }
+        .sum { |f| File.size(f) }
+    end
+
+    def prepare_output_directory
+      output_dir = config.build.output
+      FileUtils.rm_rf(output_dir) if clean && Dir.exist?(output_dir)
       FileUtils.mkdir_p(output_dir)
     end
 
     def generate_static_pages
       require_relative "build/static_generator"
-      generator = Build::StaticGenerator.new(config, verbose: verbose)
-      generator.generate
+      Build::StaticGenerator.new(config, verbose: verbose).generate
     end
 
     def bundle_assets
       require_relative "build/asset_bundler"
-      bundler = Build::AssetBundler.new(config, verbose: verbose)
-      bundler.bundle
+      [Build::AssetBundler.new(config, verbose: verbose).bundle, nil]
     end
 
     def copy_static_files
       require_relative "build/file_copier"
-      copier = Build::FileCopier.new(config, verbose: verbose)
-      copier.copy
+      Build::FileCopier.new(config, verbose: verbose).copy
     end
 
     def generate_seo_files
       require_relative "build/sitemap_generator"
-      sitemap_gen = Build::SitemapGenerator.new(config)
-      sitemap_gen.generate
+      sitemap_result = Build::SitemapGenerator.new(config).generate
 
       require_relative "build/llms_txt_generator"
-      llms_gen = Build::LlmsTxtGenerator.new(config)
-      llms_gen.generate
+      Build::LlmsTxtGenerator.new(config).generate
 
       File.write(File.join(config.build.output, "robots.txt"), robots_txt_content)
-      log "[+] Generated robots.txt"
+
+      result = ["sitemap.xml", "robots.txt", "llms.txt"]
+      details = ["sitemap.xml (#{sitemap_result} URLs)", "robots.txt", "llms.txt", "llms-full.txt"]
+      [result, details]
     end
 
     def generate_search_index
-      indexer = Search::BuildIndexer.new(config, verbose: verbose)
-      indexer.index
+      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
@@ -92,27 +151,5 @@ module Docyard
         Sitemap: #{base}sitemap.xml
       ROBOTS
     end
-
-    def display_summary(pages, bundles, assets, indexed = 0)
-      elapsed = Time.now - start_time
-
-      puts "\n#{'=' * 50}"
-      puts "Build complete in #{format('%.2f', elapsed)}s"
-      puts "Output: #{config.build.output}/"
-
-      summary = "#{pages} pages, #{bundles} bundles, #{assets} static files"
-      summary += ", #{indexed} pages indexed" if indexed.positive?
-      puts summary
-
-      puts "=" * 50
-    end
-
-    def log(message)
-      Docyard.logger.info(message)
-    end
-
-    def error(message)
-      Docyard.logger.error(message)
-    end
   end
 end

data/lib/docyard/cli.rb

@@ -8,6 +8,8 @@ module Docyard
       true
     end
 
+    class_option :no_color, type: :boolean, default: false, desc: "Disable colored output"
+
     desc "version", "Show docyard version"
     def version
       puts "docyard #{Docyard::VERSION}"
@@ -17,6 +19,7 @@ module Docyard
     method_option :force, type: :boolean, default: false, aliases: "-f",
                           desc: "Overwrite existing files"
     def init(project_name = nil)
+      apply_global_options
       initializer = Docyard::Initializer.new(project_name, force: options[:force])
       exit(1) unless initializer.run
     end
@@ -24,23 +27,28 @@ module Docyard
     desc "build", "Build static site for production"
     method_option :clean, type: :boolean, default: true, desc: "Clean output directory before building"
     method_option :verbose, type: :boolean, default: false, aliases: "-v", desc: "Show verbose output"
+    method_option :strict, type: :boolean, default: false, desc: "Fail on any validation errors"
     def build
+      apply_global_options
       require_relative "builder"
       builder = Docyard::Builder.new(
         clean: options[:clean],
-        verbose: options[:verbose]
+        verbose: options[:verbose],
+        strict: options[:strict]
       )
       exit(1) unless builder.build
     rescue ConfigError => e
-      Docyard.logger.error(e.message)
-      exit(1)
+      print_config_error(e)
     end
 
     desc "preview", "Preview the built site locally"
     method_option :port, type: :numeric, default: 4000, aliases: "-p", desc: "Port to run preview server on"
     def preview
+      apply_global_options
       require_relative "server/preview_server"
       Docyard::PreviewServer.new(port: options[:port]).start
+    rescue ConfigError => e
+      print_config_error(e)
     end
 
     desc "serve", "Start the development server"
@@ -49,6 +57,7 @@ module Docyard
     method_option :search, type: :boolean, default: false, aliases: "-s",
                            desc: "Enable search indexing (slower startup)"
     def serve
+      apply_global_options
       require_relative "server/dev_server"
       config = Docyard::Config.load
       server = Docyard::DevServer.new(
@@ -59,7 +68,57 @@ module Docyard
       )
       server.start
     rescue ConfigError => e
-      Docyard.logger.error(e.message)
+      print_config_error(e)
+    end
+
+    desc "doctor", "Check documentation for issues"
+    method_option :fix, type: :boolean, default: false, desc: "Auto-fix fixable issues"
+    def doctor
+      apply_global_options
+      require_relative "doctor"
+      doctor = Docyard::Doctor.new(fix: options[:fix])
+      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
+      UI.enabled = false if options[:no_color]
+    end
+
+    def print_config_error(error)
+      puts
+      puts "  #{UI.bold('Docyard')} v#{VERSION}"
+      puts
+      puts "  #{UI.red(error.message)}"
+      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

data/lib/docyard/components/aliases.rb

@@ -26,11 +26,7 @@ module Docyard
     TabsProcessor = Processors::TabsProcessor
     TooltipProcessor = Processors::TooltipProcessor
 
-    CodeDetector = Support::CodeDetector
-    IconDetector = Support::Tabs::IconDetector
-
     CodeBlockFeatureExtractor = Support::CodeBlock::FeatureExtractor
-    CodeBlockIconDetector = Support::CodeBlock::IconDetector
     CodeBlockLineWrapper = Support::CodeBlock::LineWrapper
     CodeBlockPatterns = Support::CodeBlock::Patterns
     CodeLineParser = Support::CodeBlock::LineParser

data/lib/docyard/components/processors/callout_processor.rb

@@ -43,7 +43,7 @@ module Docyard
         private
 
         def process_container_syntax(markdown)
-          markdown.gsub(/^:::[ \t]*(\w+)(?:[ \t]+([^\n]+?))?[ \t]*\n(.*?)^:::[ \t]*$/m) do
+          markdown.gsub(/^:::(\w+)(?:[ \t]+([^\n]+?))?[ \t]*\n(.*?)^:::[ \t]*$/m) do
             match = Regexp.last_match
             next match[0] if inside_code_block?(match.begin(0), @code_block_ranges)
 

data/lib/docyard/components/processors/code_block_diff_preprocessor.rb

@@ -12,7 +12,7 @@ module Docyard
         self.priority = 6
 
         CODE_BLOCK_REGEX = /^```(\w*).*?\n(.*?)^```/m
-        TABS_BLOCK_REGEX = /^:::[ \t]*tabs[ \t]*\n.*?^:::[ \t]*$/m
+        TABS_BLOCK_REGEX = /^:::tabs[ \t]*\n.*?^:::[ \t]*$/m
 
         def preprocess(content)
           context[:code_block_diff_lines] ||= []

data/lib/docyard/components/processors/code_block_focus_preprocessor.rb

@@ -20,7 +20,7 @@ module Docyard
         }x
 
         CODE_BLOCK_REGEX = /^```(\w*).*?\n(.*?)^```/m
-        TABS_BLOCK_REGEX = /^:::[ \t]*tabs[ \t]*\n.*?^:::[ \t]*$/m
+        TABS_BLOCK_REGEX = /^:::tabs[ \t]*\n.*?^:::[ \t]*$/m
 
         def preprocess(content)
           context[:code_block_focus_lines] ||= []

data/lib/docyard/components/processors/code_block_options_preprocessor.rb

@@ -10,8 +10,8 @@ module Docyard
         self.priority = 5
 
         CODE_FENCE_REGEX = /^```(\w+)(?:\s*\[([^\]]+)\])?(:\S+)?(?:\s*\{([^}\n]+)\})?/
-        TABS_BLOCK_REGEX = /^:::[ \t]*tabs[ \t]*\n.*?^:::[ \t]*$/m
-        CODE_GROUP_BLOCK_REGEX = /^:::[ \t]*code-group[ \t]*\n.*?^:::[ \t]*$/m
+        TABS_BLOCK_REGEX = /^:::tabs[ \t]*\n.*?^:::[ \t]*$/m
+        CODE_GROUP_BLOCK_REGEX = /^:::code-group[ \t]*\n.*?^:::[ \t]*$/m
         EXCLUDED_LANGUAGES = %w[filetree].freeze
 
         def preprocess(content)

data/lib/docyard/components/processors/code_group_processor.rb

@@ -22,7 +22,7 @@ module Docyard
 
         self.priority = 12
 
-        CODE_GROUP_PATTERN = /^:::[ \t]*code-group[ \t]*\n(.*?)^:::[ \t]*$/m
+        CODE_GROUP_PATTERN = /^:::code-group[ \t]*\n(.*?)^:::[ \t]*$/m
         CODE_BLOCK_PATTERN = /```(\w*)\s*\[([^\]]+)\]([^\n]*)\n(.*?)```/m
 
         CodeBlockFeatureExtractor = Support::CodeBlock::FeatureExtractor

data/lib/docyard/components/processors/icon_processor.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../base_processor"
+require_relative "../../rendering/icons"
 
 module Docyard
   module Components
@@ -9,7 +10,6 @@ module Docyard
         self.priority = 20
 
         ICON_PATTERN = /:([a-z][a-z0-9-]*):(?:([a-z]+):)?/i
-        VALID_WEIGHTS = %w[regular bold fill light thin duotone].freeze
 
         def postprocess(html)
           segments = split_preserving_code_blocks(html)
@@ -49,7 +49,7 @@ module Docyard
         end
 
         def render_icon(name, weight)
-          weight = "regular" unless VALID_WEIGHTS.include?(weight)
+          weight = "regular" unless Icons::VALID_WEIGHTS.include?(weight)
           weight_class = weight == "regular" ? "ph" : "ph-#{weight}"
           %(<i class="#{weight_class} ph-#{name}" aria-hidden="true"></i>)
         end

data/lib/docyard/components/processors/tabs_processor.rb

@@ -21,7 +21,7 @@ module Docyard
 
           @code_block_ranges = find_code_block_ranges(content)
 
-          content.gsub(/^:::[ \t]*tabs[ \t]*\n(.*?)^:::[ \t]*$/m) do
+          content.gsub(/^:::tabs[ \t]*\n(.*?)^:::[ \t]*$/m) do
             match = Regexp.last_match
             next match[0] if inside_code_block?(match.begin(0), @code_block_ranges)
 

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "sections"
+
+module Docyard
+  class Config
+    module Schema
+      DEFINITION = {
+        title: { type: :string },
+        description: { type: :string },
+        url: { type: :url },
+        og_image: { type: :string },
+        twitter: { type: :string },
+        source: { type: :string },
+        sidebar: { type: :enum, values: SIDEBAR_MODES },
+        branding: BRANDING_SCHEMA,
+        socials: SOCIALS_SCHEMA,
+        tabs: TABS_SCHEMA,
+        build: BUILD_SCHEMA,
+        search: SEARCH_SCHEMA,
+        navigation: NAVIGATION_SCHEMA,
+        announcement: ANNOUNCEMENT_SCHEMA,
+        repo: REPO_SCHEMA,
+        analytics: ANALYTICS_SCHEMA,
+        feedback: FEEDBACK_SCHEMA,
+        social_cards: SOCIAL_CARDS_SCHEMA
+      }.freeze
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "simple_sections"
+
+module Docyard
+  class Config
+    module Schema
+      SOCIALS_SCHEMA = {
+        type: :hash,
+        allow_extra_keys: true,
+        keys: {
+          github: { type: :url },
+          twitter: { type: :url },
+          discord: { type: :url },
+          slack: { type: :url },
+          linkedin: { type: :url },
+          youtube: { type: :url },
+          custom: {
+            type: :array,
+            items: {
+              type: :hash,
+              keys: { icon: { type: :string }, href: { type: :url } }
+            }
+          }
+        }
+      }.freeze
+
+      TABS_SCHEMA = {
+        type: :array,
+        items: {
+          type: :hash,
+          keys: {
+            text: { type: :string },
+            href: { type: :string },
+            icon: { type: :string },
+            external: { type: :boolean }
+          }
+        }
+      }.freeze
+
+      NAVIGATION_SCHEMA = {
+        type: :hash,
+        keys: {
+          breadcrumbs: { type: :boolean },
+          cta: {
+            type: :array,
+            max_items: 2,
+            items: {
+              type: :hash,
+              keys: {
+                text: { type: :string },
+                href: { type: :string },
+                variant: { type: :enum, values: CTA_VARIANTS },
+                external: { type: :boolean }
+              }
+            }
+          }
+        }
+      }.freeze
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Config
+    module Schema
+      BRANDING_SCHEMA = {
+        type: :hash,
+        keys: {
+          logo: { type: :file_or_url },
+          favicon: { type: :file_or_url },
+          credits: { type: :boolean },
+          copyright: { type: :string },
+          color: { type: :color }
+        }
+      }.freeze
+
+      BUILD_SCHEMA = {
+        type: :hash,
+        keys: {
+          output: { type: :string, format: :no_slashes },
+          base: { type: :string, format: :starts_with_slash },
+          strict: { type: :boolean }
+        }
+      }.freeze
+
+      SEARCH_SCHEMA = {
+        type: :hash,
+        keys: {
+          enabled: { type: :boolean },
+          placeholder: { type: :string },
+          exclude: { type: :array, items: { type: :string } }
+        }
+      }.freeze
+
+      ANNOUNCEMENT_SCHEMA = {
+        type: :hash,
+        keys: {
+          text: { type: :string },
+          link: { type: :string },
+          dismissible: { type: :boolean },
+          button: {
+            type: :hash,
+            keys: { text: { type: :string }, link: { type: :string } }
+          }
+        }
+      }.freeze
+
+      REPO_SCHEMA = {
+        type: :hash,
+        keys: {
+          url: { type: :url },
+          branch: { type: :string },
+          edit_path: { type: :string },
+          edit_link: { type: :boolean },
+          last_updated: { type: :boolean }
+        }
+      }.freeze
+
+      ANALYTICS_SCHEMA = {
+        type: :hash,
+        keys: {
+          google: { type: :string },
+          plausible: { type: :string },
+          fathom: { type: :string },
+          script: { type: :string }
+        }
+      }.freeze
+
+      FEEDBACK_SCHEMA = {
+        type: :hash,
+        keys: {
+          enabled: { type: :boolean },
+          question: { type: :string }
+        }
+      }.freeze
+
+      SOCIAL_CARDS_SCHEMA = {
+        type: :hash,
+        keys: {
+          enabled: { type: :boolean }
+        }
+      }.freeze
+    end
+  end
+end

data/lib/docyard/config/schema.rb

@@ -3,37 +3,34 @@
 module Docyard
   class Config
     module Schema
-      TOP_LEVEL = %w[
-        title description url og_image twitter source
-        branding socials tabs sidebar
-        build search navigation announcement
-        repo analytics feedback
-      ].freeze
-
-      SECTIONS = {
-        "branding" => %w[logo favicon credits copyright color],
-        "build" => %w[output base],
-        "search" => %w[enabled placeholder exclude],
-        "navigation" => %w[cta breadcrumbs],
-        "repo" => %w[url branch edit_path edit_link last_updated],
-        "analytics" => %w[google plausible fathom script],
-        "announcement" => %w[text link button dismissible],
-        "feedback" => %w[enabled question]
-      }.freeze
-
-      TAB = %w[text href icon external].freeze
-
-      CTA = %w[text href variant external].freeze
-
-      ANNOUNCEMENT_BUTTON = %w[text link].freeze
-
-      SIDEBAR_ITEM = %w[text icon badge badge_type items collapsed index group collapsible].freeze
-
-      SIDEBAR_EXTERNAL_LINK = %w[link text icon target].freeze
-
-      SOCIALS_BUILTIN = %w[github twitter discord slack linkedin youtube bluesky custom].freeze
-
-      CUSTOM_SOCIAL = %w[icon href].freeze
+      SIDEBAR_MODES = %w[config auto distributed].freeze
+      CTA_VARIANTS = %w[primary secondary].freeze
+      SIDEBAR_ITEM_KEYS = %w[text icon badge badge_type items collapsed index group collapsible].freeze
+      SIDEBAR_EXTERNAL_LINK_KEYS = %w[link text icon target].freeze
+
+      class << self
+        def validate_keys(hash, valid_keys, context:)
+          return [] unless hash.is_a?(Hash)
+
+          unknown = hash.keys.map(&:to_s) - valid_keys
+          unknown.map { |key| build_key_error(key, valid_keys, context) }
+        end
+
+        def build_key_error(key, valid_keys, context)
+          suggestion = find_key_suggestion(key, valid_keys)
+          msg = "unknown key '#{key}'"
+          msg += ". Did you mean '#{suggestion}'?" if suggestion
+          fix = suggestion ? { type: :rename, from: key, to: suggestion } : nil
+          { context: context, message: msg, key: key, fix: fix }
+        end
+
+        def find_key_suggestion(key, valid_keys)
+          checker = DidYouMean::SpellChecker.new(dictionary: valid_keys)
+          checker.correct(key).first
+        end
+      end
     end
   end
 end
+
+require_relative "schema/definition"