docyard 0.8.0 → 1.0.0

data/lib/docyard/config/branding_resolver.rb

@@ -1,20 +1,16 @@
 # frozen_string_literal: true
 
+require_relative "logo_detector"
+require_relative "analytics_resolver"
+
 module Docyard
   class BrandingResolver
+    include AnalyticsResolver
+
     def initialize(config)
       @config = config
     end
 
-    SOCIAL_ICON_MAP = {
-      "x" => "x-logo", "twitter" => "x-logo", "discord" => "discord-logo",
-      "linkedin" => "linkedin-logo", "youtube" => "youtube-logo", "instagram" => "instagram-logo",
-      "facebook" => "facebook-logo", "tiktok" => "tiktok-logo", "twitch" => "twitch-logo",
-      "reddit" => "reddit-logo", "mastodon" => "mastodon-logo", "threads" => "threads-logo",
-      "pinterest" => "pinterest-logo", "medium" => "medium-logo", "slack" => "slack-logo",
-      "gitlab" => "gitlab-logo"
-    }.freeze
-
     def resolve
       return default_branding unless config
 
@@ -38,66 +34,35 @@ module Docyard
     end
 
     def config_branding_options
-      site_options
-        .merge(logo_options)
-        .merge(search_options)
-        .merge(credits_options)
-        .merge(social_options)
-        .merge(navigation_options)
-        .merge(tabs_options)
+      [
+        site_options, logo_options, search_options, credits_options, social_options,
+        navigation_options, tabs_options, announcement_options, repo_options, analytics_options,
+        color_options
+      ].reduce({}, :merge)
     end
 
     def site_options
       {
         site_title: config.title || Constants::DEFAULT_SITE_TITLE,
         site_description: config.description || "",
-        favicon: config.branding.favicon || auto_detect_favicon
+        site_url: config.url,
+        og_image: config.og_image,
+        twitter: config.twitter,
+        favicon: config.branding.favicon || LogoDetector.auto_detect_favicon(public_dir: config.public_dir)
       }
     end
 
     def logo_options
       branding = config.branding
-      logo = branding.logo || auto_detect_logo
+      logo = branding.logo || LogoDetector.auto_detect_logo(public_dir: config.public_dir)
       has_custom_logo = !logo.nil?
       {
         logo: logo || Constants::DEFAULT_LOGO_PATH,
-        logo_dark: detect_dark_logo(logo) || Constants::DEFAULT_LOGO_DARK_PATH,
+        logo_dark: LogoDetector.detect_dark_logo(logo, public_dir: config.public_dir) || Constants::DEFAULT_LOGO_DARK_PATH,
         has_custom_logo: has_custom_logo
       }
     end
 
-    def auto_detect_logo
-      detect_public_file("logo", %w[svg png])
-    end
-
-    def auto_detect_favicon
-      detect_public_file("favicon", %w[ico svg png])
-    end
-
-    def detect_public_file(name, extensions)
-      extensions.each do |ext|
-        path = File.join(Constants::PUBLIC_DIR, "#{name}.#{ext}")
-        return "#{name}.#{ext}" if File.exist?(path)
-      end
-      nil
-    end
-
-    def detect_dark_logo(logo)
-      return nil unless logo
-
-      ext = File.extname(logo)
-      base = File.basename(logo, ext)
-      dark_filename = "#{base}-dark#{ext}"
-
-      if File.absolute_path?(logo)
-        dark_path = File.join(File.dirname(logo), dark_filename)
-        File.exist?(dark_path) ? dark_path : logo
-      else
-        dark_path = File.join("docs/public", dark_filename)
-        File.exist?(dark_path) ? dark_filename : logo
-      end
-    end
-
     def search_options
       {
         search_enabled: config.search.enabled != false,
@@ -113,22 +78,28 @@ module Docyard
     end
 
     def social_options
-      socials = config.socials || {}
-      {
-        social: normalize_social_links(socials)
-      }
+      { social: normalize_social_links(config.socials || {}) }
     end
 
     def normalize_social_links(socials)
       return [] unless socials.is_a?(Hash) && socials.any?
 
-      socials.filter_map { |platform, url| build_social_link(platform.to_s, url) }
+      socials.except("custom").filter_map { |platform, url| build_social_link(platform.to_s, url) } +
+        build_custom_social_links(socials["custom"])
     end
 
     def build_social_link(platform, url)
-      return if platform == "custom" || !valid_url?(url)
+      { platform: platform, url: url, icon: Constants::SOCIAL_ICON_MAP[platform] || platform } if valid_url?(url)
+    end
+
+    def build_custom_social_links(custom)
+      return [] unless custom.is_a?(Array)
+
+      custom.filter_map do |item|
+        next unless item.is_a?(Hash) && item["icon"] && valid_url?(item["href"])
 
-      { platform: platform, url: url, icon: SOCIAL_ICON_MAP[platform] || platform }
+        { platform: "custom", url: item["href"], icon: item["icon"] }
+      end
     end
 
     def valid_url?(url)
@@ -179,5 +150,60 @@ module Docyard
         }
       end
     end
+
+    def announcement_options
+      announcement = config.announcement
+      return { announcement: nil } unless announcement
+
+      {
+        announcement: {
+          text: announcement.text,
+          link: announcement.link,
+          button: build_announcement_button(announcement),
+          dismissible: announcement.dismissible != false
+        }
+      }
+    end
+
+    def build_announcement_button(announcement)
+      button = announcement.button
+      return nil unless button.is_a?(Hash) && button["text"]
+
+      {
+        text: button["text"],
+        link: button["link"] || announcement.link
+      }
+    end
+
+    def repo_options
+      repo = config.repo
+      has_repo_url = !repo.url.nil? && !repo.url.empty?
+      {
+        repo_url: repo.url,
+        repo_branch: repo.branch || "main",
+        repo_edit_path: repo.edit_path || config.source,
+        show_edit_link: has_repo_url && repo.edit_link != false,
+        show_last_updated: has_repo_url && repo.last_updated != false
+      }
+    end
+
+    def color_options
+      color = config.branding.color
+      { primary_color: normalize_color(color) }
+    end
+
+    def normalize_color(color)
+      return nil if color.nil?
+
+      if color.is_a?(Hash)
+        light = color["light"]
+        dark = color["dark"]
+        return nil if light.nil? && dark.nil?
+
+        { light: light, dark: dark }.compact
+      elsif color.is_a?(String) && !color.strip.empty?
+        { light: color.strip }
+      end
+    end
   end
 end

data/lib/docyard/config/key_validator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Config
+    module KeyValidator
+      class << self
+        def validate(hash, valid_keys, context:)
+          return [] unless hash.is_a?(Hash)
+
+          unknown = hash.keys.map(&:to_s) - valid_keys
+          unknown.map { |key| build_error(key, valid_keys, context) }
+        end
+
+        private
+
+        def build_error(key, valid_keys, context)
+          suggestion = find_suggestion(key, valid_keys)
+          msg = "unknown key '#{key}'"
+          msg += ". Did you mean '#{suggestion}'?" if suggestion
+          { context: context, message: msg }
+        end
+
+        def find_suggestion(key, valid_keys)
+          checker = DidYouMean::SpellChecker.new(dictionary: valid_keys)
+          checker.correct(key).first
+        end
+      end
+    end
+  end
+end

data/lib/docyard/config/logo_detector.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Docyard
+  module LogoDetector
+    module_function
+
+    def auto_detect_logo(public_dir: "docs/public")
+      detect_public_file("logo", %w[svg png], public_dir: public_dir)
+    end
+
+    def auto_detect_favicon(public_dir: "docs/public")
+      detect_public_file("favicon", %w[ico svg png], public_dir: public_dir)
+    end
+
+    def detect_public_file(name, extensions, public_dir: "docs/public")
+      extensions.each do |ext|
+        path = File.join(public_dir, "#{name}.#{ext}")
+        return "#{name}.#{ext}" if File.exist?(path)
+      end
+      nil
+    end
+
+    def detect_dark_logo(logo, public_dir: "docs/public")
+      return nil unless logo
+
+      ext = File.extname(logo)
+      base = File.basename(logo, ext)
+      dark_filename = "#{base}-dark#{ext}"
+
+      if File.absolute_path?(logo)
+        dark_path = File.join(File.dirname(logo), dark_filename)
+        File.exist?(dark_path) ? dark_path : logo
+      else
+        dark_path = File.join(public_dir, dark_filename)
+        File.exist?(dark_path) ? dark_filename : logo
+      end
+    end
+  end
+end

data/lib/docyard/config/schema.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+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
+    end
+  end
+end

data/lib/docyard/config/section.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Config
+    class Section
+      def initialize(data)
+        @data = data || {}
+      end
+
+      def method_missing(method, *args)
+        return super unless args.empty?
+
+        @data[method.to_s]
+      end
+
+      def respond_to_missing?(method, include_private = false)
+        @data.key?(method.to_s) || super
+      end
+    end
+  end
+end

data/lib/docyard/config/validation_helpers.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Config
+    module ValidationHelpers
+      private
+
+      def validate_string(value, field_name)
+        return if value.nil? || value.is_a?(String)
+
+        add_error(field: field_name, error: "must be a string", got: value.class.name, fix: "Change to a string value")
+      end
+
+      def validate_boolean(value, field_name)
+        return if [true, false].include?(value)
+
+        add_error(field: field_name, error: "must be true or false", got: value.inspect, fix: "Change to true or false")
+      end
+
+      def validate_url(value, field_name)
+        return if value.nil? || value.is_a?(String)
+
+        add_error(field: field_name, error: "must be a URL string", got: value.class.name,
+                  fix: "Change to a URL string")
+      end
+
+      def validate_array(value, field_name)
+        return if value.nil? || value.is_a?(Array)
+
+        add_array_error(field_name)
+      end
+
+      def validate_file_path_or_url(value, field_name)
+        return if value.nil?
+        return add_type_error(field_name, "file path or URL (string)", value.class.name) unless value.is_a?(String)
+        return if url?(value)
+
+        public_dir = File.join(@config["source"] || "docs", "public")
+        file_path = File.absolute_path?(value) ? value : File.join(public_dir, value)
+        return if File.exist?(file_path)
+
+        add_error(field: field_name, error: "file not found", got: value,
+                  fix: "Place the file in #{public_dir}/ directory (e.g., 'logo.svg' for #{public_dir}/logo.svg)")
+      end
+
+      def validate_no_slashes(value, field_name)
+        return if value.nil? || !value.is_a?(String)
+        return unless value.include?("/") || value.include?("\\")
+
+        add_error(field: field_name, error: "cannot contain slashes", got: value,
+                  fix: "Use a simple directory name like 'dist' or '_site'")
+      end
+
+      def validate_starts_with_slash(value, field_name)
+        return if value.nil? || value.start_with?("/")
+
+        add_error(field: field_name, error: "must start with /", got: value, fix: "Change to '/#{value}'")
+      end
+
+      def url?(value)
+        value.match?(%r{\Ahttps?://})
+      end
+
+      def add_error(error_data)
+        @errors << error_data
+      end
+
+      def add_type_error(field, expected, got)
+        add_error(field: field, error: "must be a #{expected}", got: got, fix: "Change to a #{expected}")
+      end
+
+      def add_hash_error(field)
+        add_error(field: field, error: "must be a hash", got: @config[field].class.name,
+                  fix: "Change to a hash with platform names as keys and URLs as values")
+      end
+
+      def add_array_error(field)
+        value = field.split(".").reduce(@config) { |h, k| h&.[](k) }
+        add_error(field: field, error: "must be an array", got: value.class.name, fix: "Change to an array")
+      end
+    end
+  end
+end

data/lib/docyard/config/validator.rb

@@ -1,194 +1,95 @@
 # frozen_string_literal: true
 
+require_relative "validation_helpers"
+require_relative "schema"
+require_relative "key_validator"
+require_relative "validators/section"
+require_relative "validators/navigation"
+
 module Docyard
   class Config
     class Validator
+      include ValidationHelpers
+      include Validators::Section
+      include Validators::Navigation
+
       def initialize(config_data)
         @config = config_data
         @errors = []
+        @key_errors = []
       end
 
       def validate!
+        validate_unknown_keys
         validate_top_level
         validate_branding_section
         validate_socials_section
         validate_tabs_section
+        validate_sidebar_setting
         validate_build_section
         validate_search_section
         validate_navigation_section
+        validate_announcement_section
+        validate_feedback_section
 
+        raise_key_errors if @key_errors.any?
         raise ConfigError, format_errors if @errors.any?
       end
 
       private
 
-      def validate_top_level
-        validate_string(@config["title"], "title")
-        validate_string(@config["description"], "description")
+      def validate_unknown_keys
+        validate_top_level_keys
+        validate_section_keys
+        validate_array_item_keys
       end
 
-      def validate_branding_section
-        branding = @config["branding"]
-        return unless branding
-
-        validate_file_path_or_url(branding["logo"], "branding.logo")
-        validate_file_path_or_url(branding["favicon"], "branding.favicon")
-        validate_boolean(branding["credits"], "branding.credits") if branding.key?("credits")
+      def validate_top_level_keys
+        @key_errors.concat(KeyValidator.validate(@config, Schema::TOP_LEVEL, context: "docyard.yml"))
       end
 
-      def validate_socials_section
-        socials = @config["socials"]
-        return unless socials
-        return add_hash_error("socials") unless socials.is_a?(Hash)
+      def validate_section_keys
+        Schema::SECTIONS.each do |section, valid_keys|
+          next unless @config[section].is_a?(Hash)
 
-        socials.each { |platform, url| validate_url(url, "socials.#{platform}") unless platform == "custom" }
-        validate_custom_socials(socials["custom"]) if socials.key?("custom")
+          @key_errors.concat(KeyValidator.validate(@config[section], valid_keys, context: section))
+        end
       end
 
-      def validate_custom_socials(custom)
-        return if custom.nil?
-        return add_array_error("socials.custom") unless custom.is_a?(Array)
-
-        custom.each_with_index do |item, index|
-          validate_string(item["icon"], "socials.custom[#{index}].icon")
-          validate_url(item["href"], "socials.custom[#{index}].href")
-        end
+      def validate_array_item_keys
+        validate_tabs_keys
+        validate_cta_keys
+        validate_announcement_button_keys
       end
 
-      def validate_tabs_section
+      def validate_tabs_keys
         tabs = @config["tabs"]
-        return unless tabs
-        return add_array_error("tabs") unless tabs.is_a?(Array)
+        return unless tabs.is_a?(Array)
 
-        tabs.each_with_index do |tab, index|
-          validate_string(tab["text"], "tabs[#{index}].text")
-          validate_string(tab["href"], "tabs[#{index}].href")
-          validate_boolean(tab["external"], "tabs[#{index}].external") if tab.key?("external")
+        tabs.each_with_index do |tab, idx|
+          @key_errors.concat(KeyValidator.validate(tab, Schema::TAB, context: "tabs[#{idx}]"))
         end
       end
 
-      def validate_build_section
-        build = @config["build"]
-        return unless build
-
-        validate_string(build["output"], "build.output")
-        validate_no_slashes(build["output"], "build.output")
-        validate_string(build["base"], "build.base")
-        validate_starts_with_slash(build["base"], "build.base")
-      end
-
-      def validate_search_section
-        search = @config["search"]
-        return unless search
-
-        validate_boolean(search["enabled"], "search.enabled") if search.key?("enabled")
-        validate_string(search["placeholder"], "search.placeholder") if search.key?("placeholder")
-        validate_array(search["exclude"], "search.exclude") if search.key?("exclude")
-      end
-
-      def validate_navigation_section
+      def validate_cta_keys
         cta = @config.dig("navigation", "cta")
-        return if cta.nil?
-        return add_array_error("navigation.cta") unless cta.is_a?(Array)
+        return unless cta.is_a?(Array)
 
-        validate_cta_max_count(cta)
-        validate_cta_items(cta)
-      end
-
-      def validate_cta_items(cta)
         cta.each_with_index do |item, idx|
-          validate_string(item["text"], "navigation.cta[#{idx}].text")
-          validate_string(item["href"], "navigation.cta[#{idx}].href")
-          validate_cta_variant(item["variant"], idx) if item.key?("variant")
-          validate_boolean(item["external"], "navigation.cta[#{idx}].external") if item.key?("external")
+          @key_errors.concat(KeyValidator.validate(item, Schema::CTA, context: "navigation.cta[#{idx}]"))
         end
       end
 
-      def validate_cta_max_count(cta)
-        return if cta.length <= 2
-
-        add_error(field: "navigation.cta", error: "maximum 2 CTAs allowed",
-                  got: "#{cta.length} items", fix: "Remove extra CTA items to have at most 2")
-      end
-
-      def validate_cta_variant(variant, idx)
-        return if variant.nil? || %w[primary secondary].include?(variant)
-
-        add_error(field: "navigation.cta[#{idx}].variant", error: "must be 'primary' or 'secondary'",
-                  got: variant, fix: "Change to 'primary' or 'secondary'")
-      end
-
-      def validate_string(value, field_name)
-        return if value.nil? || value.is_a?(String)
-
-        add_error(field: field_name, error: "must be a string", got: value.class.name, fix: "Change to a string value")
-      end
-
-      def validate_boolean(value, field_name)
-        return if [true, false].include?(value)
-
-        add_error(field: field_name, error: "must be true or false", got: value.inspect, fix: "Change to true or false")
-      end
-
-      def validate_url(value, field_name)
-        return if value.nil? || value.is_a?(String)
-
-        add_error(field: field_name, error: "must be a URL string",
-                  got: value.class.name, fix: "Change to a URL string")
-      end
-
-      def validate_array(value, field_name)
-        return if value.nil? || value.is_a?(Array)
-
-        add_array_error(field_name)
-      end
-
-      def validate_file_path_or_url(value, field_name)
-        return if value.nil?
-        return add_type_error(field_name, "file path or URL (string)", value.class.name) unless value.is_a?(String)
-        return if url?(value)
-
-        file_path = File.absolute_path?(value) ? value : File.join("docs/public", value)
-        return if File.exist?(file_path)
-
-        add_error(field: field_name, error: "file not found", got: value,
-                  fix: "Place the file in docs/public/ directory (e.g., 'logo.svg' for docs/public/logo.svg)")
-      end
-
-      def validate_no_slashes(value, field_name)
-        return if value.nil? || !value.is_a?(String)
-        return unless value.include?("/") || value.include?("\\")
-
-        add_error(field: field_name, error: "cannot contain slashes", got: value,
-                  fix: "Use a simple directory name like 'dist' or '_site'")
-      end
-
-      def validate_starts_with_slash(value, field_name)
-        return if value.nil? || value.start_with?("/")
-
-        add_error(field: field_name, error: "must start with /", got: value, fix: "Change to '/#{value}'")
-      end
-
-      def url?(value)
-        value.match?(%r{\Ahttps?://})
-      end
-
-      def add_error(error_data)
-        @errors << error_data
-      end
-
-      def add_type_error(field, expected, got)
-        add_error(field: field, error: "must be a #{expected}", got: got, fix: "Change to a #{expected}")
-      end
+      def validate_announcement_button_keys
+        button = @config.dig("announcement", "button")
+        return unless button.is_a?(Hash)
 
-      def add_hash_error(field)
-        add_error(field: field, error: "must be a hash", got: @config[field].class.name,
-                  fix: "Change to a hash with platform names as keys and URLs as values")
+        @key_errors.concat(KeyValidator.validate(button, Schema::ANNOUNCEMENT_BUTTON, context: "announcement.button"))
       end
 
-      def add_array_error(field)
-        value = field.split(".").reduce(@config) { |h, k| h&.[](k) }
-        add_error(field: field, error: "must be an array", got: value.class.name, fix: "Change to an array")
+      def raise_key_errors
+        messages = @key_errors.map { |e| "#{e[:context]}: #{e[:message]}" }
+        raise ConfigError, "Error in docyard.yml:\n#{messages.join("\n")}"
       end
 
       def format_errors