docyard 0.9.0 → 1.0.0

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

@@ -16,35 +16,34 @@ module Docyard
         def preprocess(content)
           @current_file = context[:current_file]
           @docs_root = context[:docs_root] || "docs"
-          @included_files = Set.new
 
           process_outside_code_blocks(content) do |segment|
-            process_includes(segment)
+            process_includes(segment, Set.new)
           end
         end
 
         private
 
-        def process_includes(content)
-          content.gsub(INCLUDE_PATTERN) { |_| process_include(Regexp.last_match) }
+        def process_includes(content, included_files)
+          content.gsub(INCLUDE_PATTERN) { |_| process_include(Regexp.last_match, included_files) }
         end
 
-        def process_include(match)
+        def process_include(match, included_files)
           filepath = match[1]
           full_path = resolve_path(filepath)
 
-          error = validate_include(filepath, full_path)
+          error = validate_include(filepath, full_path, included_files)
           return error if error
 
-          @included_files.add(full_path)
+          updated_included_files = included_files.dup.add(full_path)
           file_content = File.read(full_path)
 
-          process_includes(file_content.strip)
+          process_includes(file_content.strip, updated_included_files)
         end
 
-        def validate_include(filepath, full_path)
+        def validate_include(filepath, full_path, included_files)
           return include_error(filepath, "File not found") unless full_path && File.exist?(full_path)
-          return include_error(filepath, "Circular include detected") if @included_files.include?(full_path)
+          return include_error(filepath, "Circular include detected") if included_files.include?(full_path)
           return include_error(filepath, "Use code snippets for non-markdown files") unless markdown_file?(filepath)
 
           nil
@@ -78,6 +77,7 @@ module Docyard
         end
 
         def include_error(filepath, message)
+          Docyard.logger.warn("Include failed: #{filepath} - #{message}")
           "> [!WARNING]\n> Include error: #{filepath} - #{message}\n"
         end
       end

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

@@ -147,14 +147,25 @@ module Docyard
         end
 
         def build_wrapper_style(attrs)
-          return "" unless attrs["width"] || attrs["height"]
+          width = validate_dimension(attrs["width"])
+          height = validate_dimension(attrs["height"])
+          return "" unless width || height
 
           styles = []
-          styles << "max-width: #{escape_attr(attrs['width'])}px" if attrs["width"]
-          styles << "height: #{escape_attr(attrs['height'])}px" if attrs["height"]
+          styles << "max-width: #{width}px" if width
+          styles << "height: #{height}px" if height
           " style=\"#{styles.join('; ')}\""
         end
 
+        def validate_dimension(value)
+          return nil if value.nil? || value.to_s.empty?
+
+          int_value = value.to_s.to_i
+          return nil unless int_value.positive? && int_value <= 10_000
+
+          int_value
+        end
+
         def build_iframe_attrs(url, attrs, provider)
           iframe_attrs = [
             "src=\"#{url}\"",

data/lib/docyard/components/support/code_block/feature_extractor.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "patterns"
+require_relative "../../../rendering/icons"
 
 module Docyard
   module Components
@@ -18,7 +19,8 @@ module Docyard
             cleaned = markdown.gsub(CODE_FENCE_REGEX) do
               block_data = extract_block_data(Regexp.last_match)
               blocks << block_data
-              "```#{block_data[:lang]}\n#{block_data[:cleaned_content]}```"
+              highlight_lang = Icons.highlight_language(block_data[:lang])
+              "```#{highlight_lang}\n#{block_data[:cleaned_content]}```"
             end
             { cleaned_markdown: cleaned, blocks: blocks }
           end

data/lib/docyard/components/support/code_block/icon_detector.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../../../rendering/language_mapping"
+require_relative "../../../rendering/icons"
 
 module Docyard
   module Components
@@ -22,20 +22,13 @@ module Docyard
               }
             end
 
-            icon, icon_source = auto_detect_icon(language)
-            { title: title, icon: icon, icon_source: icon_source }
+            { title: title, icon: language, icon_source: "language" }
           end
 
-          def auto_detect_icon(language)
-            return [nil, nil] if language.nil?
+          def render_icon(language)
+            return "" if language.nil? || language.to_s.empty?
 
-            if LanguageMapping.terminal_language?(language)
-              %w[terminal-window phosphor]
-            elsif (ext = LanguageMapping.extension_for(language))
-              [ext, "file-extension"]
-            else
-              %w[file phosphor]
-            end
+            Icons.render_for_language(language)
           end
         end
       end

data/lib/docyard/components/support/code_block/line_number_resolver.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Components
+    module Support
+      module CodeBlock
+        module LineNumberResolver
+          module_function
+
+          def enabled?(option)
+            return false if option == ":no-line-numbers"
+
+            option&.start_with?(":line-numbers") || false
+          end
+
+          def start_line(option)
+            return 1 unless option&.include?("=")
+
+            option.split("=").last.to_i
+          end
+
+          def generate_numbers(code_text, start = 1)
+            line_count = [code_text.lines.count, 1].max
+            (start...(start + line_count)).to_a
+          end
+        end
+      end
+    end
+  end
+end

data/lib/docyard/components/support/code_detector.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../../rendering/language_mapping"
+require_relative "../../rendering/icons"
 
 module Docyard
   module Components
@@ -20,7 +20,7 @@ module Docyard
           language = extract_language
           return nil unless language
 
-          icon_for_language(language)
+          { language: language }
         end
 
         private
@@ -45,16 +45,6 @@ module Docyard
 
           lang_line.downcase
         end
-
-        def icon_for_language(language)
-          if LanguageMapping.terminal_language?(language)
-            { icon: "terminal-window", source: "phosphor" }
-          elsif (extension = LanguageMapping.extension_for(language))
-            { icon: extension, source: "file-extension" }
-          else
-            { icon: "file", source: "phosphor" }
-          end
-        end
       end
     end
   end

data/lib/docyard/components/support/code_group/html_builder.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "../code_block/icon_detector"
 require_relative "../../../rendering/icons"
 
 module Docyard
@@ -53,17 +52,14 @@ module Docyard
                 class="docyard-code-group__tab"
                 tabindex="#{tabindex}"
                 data-label="#{escape_html(block[:label])}"
-              >#{icon_html}#{escape_html(block[:label])}</button>
+              >#{icon_html}<span class="docyard-code-group__tab-label">#{escape_html(block[:label])}</span></button>
             HTML
           end
 
           def render_icon(lang)
             return "" if lang.nil? || lang.empty?
 
-            icon, icon_source = CodeBlock::IconDetector.auto_detect_icon(lang)
-            return "" unless icon && icon_source == "file-extension"
-
-            Icons.render_file_extension(icon) || ""
+            Icons.render_for_language(lang)
           end
 
           def build_copy_button

data/lib/docyard/components/support/tabs/icon_detector.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../code_detector"
+require_relative "../../../rendering/icons"
 
 module Docyard
   module Components
@@ -41,10 +42,13 @@ module Docyard
             detected = CodeDetector.detect(tab_content)
             return nil unless detected
 
+            language = detected[:language]
+            return nil unless Icons.devicon?(language)
+
             {
               name: tab_name,
-              icon: detected[:icon],
-              icon_source: detected[:source]
+              icon: language,
+              icon_source: "language"
             }
           end
 

data/lib/docyard/components/support/tabs/parser.rb

@@ -3,6 +3,7 @@
 require_relative "../code_block/feature_extractor"
 require_relative "../code_block/icon_detector"
 require_relative "../code_block/line_wrapper"
+require_relative "../code_block/line_number_resolver"
 require_relative "icon_detector"
 require_relative "../../../rendering/icons"
 require_relative "../../../rendering/renderer"
@@ -21,6 +22,7 @@ module Docyard
           CodeBlockFeatureExtractor = CodeBlock::FeatureExtractor
           CodeBlockIconDetector = CodeBlock::IconDetector
           CodeBlockLineWrapper = CodeBlock::LineWrapper
+          LineNumbers = CodeBlock::LineNumberResolver
 
           def self.parse(content)
             new(content).parse
@@ -120,15 +122,15 @@ module Docyard
               focus_lines: block_data[:focus_lines] || {},
               error_lines: block_data[:error_lines] || {},
               warning_lines: block_data[:warning_lines] || {},
-              start_line: extract_start_line(block_data[:option])
+              start_line: LineNumbers.start_line(block_data[:option])
             }
             CodeBlockLineWrapper.wrap_code_block(html, wrapper_data)
           end
 
           def build_full_locals(processed_html, code_text, block_data)
             title_data = CodeBlockIconDetector.detect(block_data[:title], block_data[:lang])
-            show_line_numbers = line_numbers_enabled?(block_data[:option])
-            start_line = extract_start_line(block_data[:option])
+            show_line_numbers = LineNumbers.enabled?(block_data[:option])
+            start_line = LineNumbers.start_line(block_data[:option])
 
             base_locals(processed_html, code_text, show_line_numbers, start_line)
               .merge(feature_locals(block_data))
@@ -141,7 +143,7 @@ module Docyard
               code_text: escape_html_attribute(code_text),
               copy_icon: Icons.render("copy", "regular") || "",
               show_line_numbers: show_line_numbers,
-              line_numbers: show_line_numbers ? generate_line_numbers(code_text, start_line) : [],
+              line_numbers: show_line_numbers ? LineNumbers.generate_numbers(code_text, start_line) : [],
               start_line: start_line
             }
           end
@@ -164,25 +166,6 @@ module Docyard
             }
           end
 
-          def line_numbers_enabled?(block_option)
-            return false if block_option == ":no-line-numbers"
-            return true if block_option&.start_with?(":line-numbers")
-
-            false
-          end
-
-          def extract_start_line(block_option)
-            return 1 unless block_option&.include?("=")
-
-            block_option.split("=").last.to_i
-          end
-
-          def generate_line_numbers(code_text, start_line)
-            line_count = code_text.lines.count
-            line_count = 1 if line_count.zero?
-            (start_line...(start_line + line_count)).to_a
-          end
-
           def extract_code_text(html)
             text = html.gsub(/<[^>]+>/, "")
             text = CGI.unescapeHTML(text)

data/lib/docyard/config/analytics_resolver.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Docyard
+  module AnalyticsResolver
+    def analytics_options
+      analytics = config.analytics
+      {
+        analytics_google: analytics.google,
+        analytics_plausible: analytics.plausible,
+        analytics_fathom: analytics.fathom,
+        analytics_script: analytics.script,
+        has_analytics: any_analytics_configured?(analytics)
+      }
+    end
+
+    private
+
+    def any_analytics_configured?(analytics)
+      [analytics.google, analytics.plausible, analytics.fathom, analytics.script].any? do |value|
+        value.is_a?(String) && !value.strip.empty?
+      end
+    end
+  end
+end

data/lib/docyard/config/branding_resolver.rb

@@ -1,22 +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
 
@@ -40,31 +34,31 @@ 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)
-        .merge(announcement_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 || LogoDetector.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 || LogoDetector.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: LogoDetector.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
@@ -84,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
 
-      { platform: platform, url: url, icon: SOCIAL_ICON_MAP[platform] || platform }
+    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: "custom", url: item["href"], icon: item["icon"] }
+      end
     end
 
     def valid_url?(url)
@@ -174,5 +174,36 @@ module Docyard
         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

@@ -4,23 +4,23 @@ module Docyard
   module LogoDetector
     module_function
 
-    def auto_detect_logo
-      detect_public_file("logo", %w[svg png])
+    def auto_detect_logo(public_dir: "docs/public")
+      detect_public_file("logo", %w[svg png], public_dir: public_dir)
     end
 
-    def auto_detect_favicon
-      detect_public_file("favicon", %w[ico svg png])
+    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)
+    def detect_public_file(name, extensions, public_dir: "docs/public")
       extensions.each do |ext|
-        path = File.join(Constants::PUBLIC_DIR, "#{name}.#{ext}")
+        path = File.join(public_dir, "#{name}.#{ext}")
         return "#{name}.#{ext}" if File.exist?(path)
       end
       nil
     end
 
-    def detect_dark_logo(logo)
+    def detect_dark_logo(logo, public_dir: "docs/public")
       return nil unless logo
 
       ext = File.extname(logo)
@@ -31,7 +31,7 @@ module Docyard
         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)
+        dark_path = File.join(public_dir, dark_filename)
         File.exist?(dark_path) ? dark_filename : logo
       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