docyard 0.9.0 → 1.0.0

data/lib/docyard/navigation/sidebar/config_builder.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require_relative "item"
+
+module Docyard
+  module Sidebar
+    class ConfigBuilder
+      attr_reader :config_items, :current_path, :start_depth
+
+      def initialize(config_items, current_path: "/", start_depth: 1)
+        @config_items = config_items || []
+        @current_path = Utils::PathResolver.normalize(current_path)
+        @start_depth = start_depth
+      end
+
+      def build
+        parse_items(config_items, base_path: "", depth: start_depth).map(&:to_h)
+      end
+
+      private
+
+      def parse_items(items, base_path:, depth:)
+        items.map { |item| parse_item(item, base_path: base_path, depth: depth) }.compact
+      end
+
+      def parse_item(item_config, base_path:, depth:)
+        case item_config
+        when String
+          build_page_item(item_config, base_path: base_path)
+        when Hash
+          parse_hash_item(item_config, base_path: base_path, depth: depth)
+        end
+      end
+
+      def parse_hash_item(config, base_path:, depth:)
+        return build_external_link(config) if external_link?(config)
+
+        slug, options = extract_slug_and_options(config)
+        return build_page_item(slug, base_path: base_path, options: options) if leaf_item?(options)
+
+        build_group_item(slug, options: options, base_path: base_path, depth: depth)
+      end
+
+      def external_link?(config)
+        config.key?("link") || config.key?(:link)
+      end
+
+      def extract_slug_and_options(config)
+        if config.keys.first.is_a?(String) && !external_link?(config)
+          [config.keys.first.to_s, config.values.first || {}]
+        else
+          [nil, config]
+        end
+      end
+
+      def leaf_item?(options)
+        return true if options.nil?
+        return false if options.is_a?(Hash) && (options.key?("items") || options.key?(:items))
+
+        true
+      end
+
+      def build_page_item(slug, base_path:, options: {})
+        options = normalize_options(options)
+        url_path = build_url_path(base_path, slug)
+
+        Item.new(
+          slug: slug,
+          text: options[:text] || titleize_slug(slug),
+          path: url_path,
+          icon: options[:icon],
+          badge: options[:badge],
+          badge_type: options[:badge_type],
+          active: current_path == url_path,
+          type: :file,
+          section: false,
+          items: []
+        )
+      end
+
+      def build_group_item(slug, options:, base_path:, depth:)
+        options = normalize_options(options)
+        context = build_group_context(slug, options, base_path, depth)
+        children = parse_items(options[:items] || [], base_path: context[:new_base_path], depth: depth + 1)
+
+        create_group_item(slug, options, context, children)
+      end
+
+      def build_group_context(slug, options, base_path, depth)
+        is_section = section_at_depth?(options, depth)
+        is_virtual_group = options[:group] == true
+        has_index = options[:index] == true
+        new_base_path = compute_new_base_path(slug, base_path, is_virtual_group)
+        url_path = has_index && !is_section ? build_url_path(base_path, slug) : nil
+
+        { is_section: is_section, has_index: has_index, new_base_path: new_base_path, url_path: url_path }
+      end
+
+      def compute_new_base_path(slug, base_path, is_virtual_group)
+        return base_path if is_virtual_group
+        return base_path unless slug
+
+        File.join(base_path, slug)
+      end
+
+      def create_group_item(slug, options, context, children)
+        Item.new(
+          slug: slug,
+          text: options[:text] || titleize_slug(slug),
+          path: context[:url_path],
+          icon: options[:icon],
+          badge: options[:badge],
+          badge_type: options[:badge_type],
+          active: context[:has_index] && current_path == context[:url_path],
+          type: :directory,
+          section: context[:is_section],
+          collapsed: determine_collapsed_state(context[:is_section], options, children),
+          has_index: context[:has_index],
+          items: children
+        )
+      end
+
+      def build_external_link(config)
+        config = normalize_options(config)
+        url = config[:link]
+
+        Item.new(
+          slug: nil,
+          text: config[:text],
+          path: url,
+          link: url,
+          icon: config[:icon],
+          target: config[:target] || "_blank",
+          type: :external,
+          section: false,
+          items: []
+        )
+      end
+
+      def section_at_depth?(options, depth)
+        return false if options[:collapsible] == true
+        return false if options[:group] == true
+
+        depth == 1
+      end
+
+      def determine_collapsed_state(is_section, options, children)
+        return false if is_section
+        return false if child_active?(children)
+        return options[:collapsed] if options.key?(:collapsed)
+
+        true
+      end
+
+      def child_active?(children)
+        children.any? { |child| child.active || child_active?(child.items) }
+      end
+
+      def build_url_path(base_path, slug)
+        base_path = base_path.to_s.sub(%r{^/+}, "")
+        return base_path.empty? ? "/" : "/#{base_path}" if slug == "index"
+
+        path = [base_path, slug].reject(&:empty?).join("/")
+        "/#{path}"
+      end
+
+      def titleize_slug(slug)
+        Utils::TextFormatter.titleize(slug.to_s)
+      end
+
+      def normalize_options(options)
+        return {} if options.nil?
+        return options if options.is_a?(Hash) && options.keys.all? { |k| k.is_a?(Symbol) }
+
+        options.transform_keys(&:to_sym)
+      end
+    end
+  end
+end

data/lib/docyard/navigation/sidebar/distributed_builder.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require_relative "item"
+require_relative "local_config_loader"
+require_relative "config_builder"
+
+module Docyard
+  module Sidebar
+    class DistributedBuilder
+      attr_reader :docs_path, :current_path
+
+      def initialize(docs_path, current_path: "/")
+        @docs_path = docs_path
+        @current_path = Utils::PathResolver.normalize(current_path)
+      end
+
+      def build
+        root_config = load_root_config
+        return [] if root_config.empty?
+
+        root_config.map { |section_slug| build_section(section_slug) }
+      end
+
+      private
+
+      def load_root_config
+        loader = LocalConfigLoader.new(docs_path)
+        config = loader.load
+        raise_missing_root_config unless config
+
+        normalize_root_config(config)
+      end
+
+      def normalize_root_config(config)
+        config.map do |item|
+          case item
+          when String then item
+          when Hash then item.keys.first.to_s
+          end
+        end.compact
+      end
+
+      def build_section(section_slug)
+        section_path = File.join(docs_path, section_slug)
+        section_config = load_section_config(section_slug, section_path)
+
+        build_section_item(section_slug, section_config)
+      end
+
+      def load_section_config(section_slug, section_path)
+        loader = LocalConfigLoader.new(section_path)
+        raise_missing_section_config(section_slug) unless loader.config_file_exists?
+
+        raw_config = YAML.load_file(File.join(section_path, "_sidebar.yml"))
+        normalize_section_config(raw_config)
+      end
+
+      def normalize_section_config(config)
+        return { items: config } if config.is_a?(Array)
+
+        config.transform_keys(&:to_sym)
+      end
+
+      def build_section_item(section_slug, section_config)
+        items = section_config[:items] || []
+        children = build_section_children(items, section_slug)
+
+        Item.new(
+          slug: section_slug,
+          text: section_config[:text] || Utils::TextFormatter.titleize(section_slug),
+          path: nil,
+          icon: section_config[:icon],
+          type: :directory,
+          section: true,
+          collapsed: false,
+          has_index: false,
+          active: false,
+          items: children
+        ).to_h
+      end
+
+      def build_section_children(items, section_slug)
+        adjusted_current_path = adjust_current_path_for_section(section_slug)
+
+        builder = ConfigBuilder.new(items, current_path: adjusted_current_path, start_depth: 2)
+        tree = builder.build
+
+        prefix_paths(tree, section_slug)
+      end
+
+      def adjust_current_path_for_section(section_slug)
+        prefix = "/#{section_slug}"
+        return current_path unless current_path.start_with?(prefix)
+
+        relative = current_path.sub(prefix, "")
+        relative.empty? ? "/" : relative
+      end
+
+      def prefix_paths(items, prefix)
+        items.map do |item|
+          prefixed = prefix_item_path(item, prefix)
+          prefixed[:children] = prefix_paths(item[:children] || [], prefix) if item[:children]&.any?
+          prefixed
+        end
+      end
+
+      def prefix_item_path(item, prefix)
+        item = item.dup
+        return item if item[:path].nil? || external_path?(item[:path])
+
+        prefixed_path = "/#{prefix}#{item[:path]}"
+        item[:path] = prefixed_path.chomp("/")
+        item[:path] = "/" if item[:path].empty?
+        item[:active] = current_path == item[:path]
+        item
+      end
+
+      def external_path?(path)
+        path.start_with?("http://", "https://")
+      end
+
+      def raise_missing_root_config
+        raise SidebarConfigError, <<~MSG.strip
+          Distributed sidebar mode requires docs/_sidebar.yml
+
+          Either:
+            1. Create docs/_sidebar.yml listing your sections
+            2. Change to 'sidebar: config' in docyard.yml
+        MSG
+      end
+
+      def raise_missing_section_config(section_slug)
+        raise SidebarConfigError, <<~MSG.strip
+          Missing sidebar config for section '#{section_slug}'
+
+          Expected: docs/#{section_slug}/_sidebar.yml
+
+          Either:
+            1. Create docs/#{section_slug}/_sidebar.yml
+            2. Remove '#{section_slug}' from docs/_sidebar.yml
+        MSG
+      end
+    end
+  end
+end

data/lib/docyard/navigation/sidebar/local_config_loader.rb

@@ -11,6 +11,7 @@ module Docyard
 
       def initialize(docs_path)
         @docs_path = docs_path
+        @key_errors = []
       end
 
       def load
@@ -31,12 +32,17 @@ module Docyard
 
       def parse_config_file
         content = YAML.load_file(config_file_path)
-        normalize_config(content)
+        items = normalize_config(content)
+        validate_items(items) if items
+        report_key_errors
+        items
       rescue Psych::SyntaxError => e
-        warn "Warning: Invalid YAML in #{config_file_path}: #{e.message}"
+        Docyard.logger.warn("Invalid YAML in #{config_file_path}: #{e.message}")
         nil
+      rescue ConfigError
+        raise
       rescue StandardError => e
-        warn "Warning: Error reading #{config_file_path}: #{e.message}"
+        Docyard.logger.warn("Error reading #{config_file_path}: #{e.message}")
         nil
       end
 
@@ -46,6 +52,66 @@ module Docyard
 
         content["items"] if content.is_a?(Hash)
       end
+
+      def validate_items(items, path_prefix: "")
+        return unless items.is_a?(Array)
+
+        items.each_with_index do |item, idx|
+          validate_item(item, "#{path_prefix}[#{idx}]")
+        end
+      end
+
+      def validate_item(item, context)
+        return unless item.is_a?(Hash)
+
+        if external_link?(item)
+          validate_external_link(item, context)
+        else
+          validate_sidebar_item(item, context)
+        end
+      end
+
+      def external_link?(item)
+        item.key?("link") || item.key?(:link)
+      end
+
+      def validate_external_link(item, context)
+        errors = Config::KeyValidator.validate(item, Config::Schema::SIDEBAR_EXTERNAL_LINK, context: context)
+        @key_errors.concat(errors)
+      end
+
+      def validate_sidebar_item(item, context)
+        slug, options = extract_slug_and_options(item)
+        return unless options.is_a?(Hash)
+
+        errors = Config::KeyValidator.validate(options, Config::Schema::SIDEBAR_ITEM, context: context)
+        @key_errors.concat(errors)
+        validate_nested_items(options, slug, context)
+      end
+
+      def extract_slug_and_options(item)
+        first_key = item.keys.first
+        if first_key.is_a?(String) && !external_link?(item)
+          [first_key, item[first_key]]
+        else
+          [nil, item]
+        end
+      end
+
+      def validate_nested_items(options, slug, context)
+        nested = options["items"] || options[:items]
+        return unless nested
+
+        nested_context = slug ? "#{context}.#{slug}" : context
+        validate_items(nested, path_prefix: nested_context)
+      end
+
+      def report_key_errors
+        return if @key_errors.empty?
+
+        messages = @key_errors.map { |e| "#{e[:context]}: #{e[:message]}" }
+        raise ConfigError, "Error in #{config_file_path}:\n#{messages.join("\n")}"
+      end
     end
   end
 end

data/lib/docyard/navigation/sidebar/renderer.rb

@@ -19,6 +19,8 @@ module Docyard
         @header_ctas = header_ctas
       end
 
+      VALID_IVAR_PATTERN = /\A[a-z_][a-z0-9_]*\z/i
+
       def render(tree)
         return "" if tree.empty?
 
@@ -32,12 +34,21 @@ module Docyard
         template_path = File.join(PARTIALS_PATH, "_#{name}.html.erb")
         template = File.read(template_path)
 
-        locals.each { |key, value| instance_variable_set("@#{key}", value) }
+        locals.each do |key, value|
+          validate_variable_name!(key)
+          instance_variable_set("@#{key}", value)
+        end
 
         erb_binding = binding
         ERB.new(template).result(erb_binding)
       end
 
+      def validate_variable_name!(name)
+        return if name.to_s.match?(VALID_IVAR_PATTERN)
+
+        raise ArgumentError, "Invalid variable name: #{name}"
+      end
+
       def render_tree_with_sections(items)
         filtered_items = items.reject { |item| item[:title]&.downcase == site_title.downcase }
         grouped = group_items_by_section(filtered_items)

data/lib/docyard/navigation/sidebar_builder.rb

@@ -1,27 +1,27 @@
 # frozen_string_literal: true
 
-require_relative "sidebar/file_system_scanner"
-require_relative "sidebar/title_extractor"
-require_relative "sidebar/tree_builder"
+require_relative "sidebar/cache"
+require_relative "sidebar/config_builder"
+require_relative "sidebar/auto_builder"
+require_relative "sidebar/distributed_builder"
 require_relative "sidebar/renderer"
-require_relative "sidebar/config_parser"
-require_relative "sidebar/local_config_loader"
-require_relative "sidebar/path_prefixer"
 require_relative "sidebar/tree_filter"
+require_relative "sidebar/local_config_loader"
 
 module Docyard
   class SidebarBuilder
-    attr_reader :docs_path, :current_path, :config, :header_ctas
+    attr_reader :docs_path, :current_path, :config, :header_ctas, :sidebar_cache
 
-    def initialize(docs_path:, current_path: "/", config: nil, header_ctas: [])
+    def initialize(docs_path:, current_path: "/", config: nil, header_ctas: [], sidebar_cache: nil)
       @docs_path = docs_path
       @current_path = current_path
       @config = config
       @header_ctas = header_ctas
+      @sidebar_cache = sidebar_cache
     end
 
     def tree
-      @tree ||= build_scoped_tree
+      @tree ||= build_tree
     end
 
     def to_html
@@ -30,101 +30,63 @@ module Docyard
 
     private
 
-    def build_scoped_tree
-      active_tab = find_active_tab
-      return build_tree_for_path(docs_path) unless active_tab
-
-      build_tree_for_tab(active_tab)
-    end
-
-    def build_tree_for_tab(tab)
-      tab_path = tab["href"]&.chomp("/")
-      return build_tree_for_path(docs_path) if empty_tab_path?(tab_path)
+    def build_tree
+      return build_from_cache if sidebar_cache&.valid?
 
-      scoped_docs_path = resolve_scoped_path(tab_path)
-      build_scoped_or_filtered_tree(scoped_docs_path, tab_path)
+      build_without_cache
     end
 
-    def empty_tab_path?(tab_path)
-      tab_path.nil? || tab_path.empty? || tab_path == "/"
+    def build_from_cache
+      base_tree = sidebar_cache.get(current_path: current_path)
+      apply_tab_scoping(base_tree)
     end
 
-    def resolve_scoped_path(tab_path)
-      tab_folder = tab_path.sub(%r{^/}, "")
-      File.join(docs_path, tab_folder)
+    def build_without_cache
+      base_tree = build_tree_for_mode
+      apply_tab_scoping(base_tree)
     end
 
-    def build_scoped_or_filtered_tree(scoped_docs_path, tab_path)
-      if scoped_sidebar_available?(scoped_docs_path)
-        build_tree_for_path(scoped_docs_path, base_url_prefix: tab_path)
+    def build_tree_for_mode
+      case sidebar_mode
+      when "auto"
+        Sidebar::AutoBuilder.new(docs_path, current_path: current_path).build
+      when "distributed"
+        Sidebar::DistributedBuilder.new(docs_path, current_path: current_path).build
       else
-        Sidebar::TreeFilter.new(build_tree_for_path(docs_path), tab_path).filter
+        build_config_tree
       end
     end
 
-    def scoped_sidebar_available?(path)
-      File.directory?(path) && Sidebar::LocalConfigLoader.new(path).config_file_exists?
-    end
+    def build_config_tree
+      config_items = Sidebar::LocalConfigLoader.new(docs_path).load
+      return [] unless config_items
 
-    def build_tree_for_path(path, base_url_prefix: "")
-      config_items = Sidebar::LocalConfigLoader.new(path).load
-      tree = build_tree(config_items, path, base_url_prefix)
-      maybe_prepend_overview(tree, path, base_url_prefix)
+      Sidebar::ConfigBuilder.new(config_items, current_path: current_path).build
     end
 
-    def build_tree(config_items, path, base_url_prefix)
-      if config_items&.any?
-        build_tree_from_config(config_items, path, base_url_prefix)
-      else
-        build_tree_from_filesystem(path, base_url_prefix)
-      end
+    def sidebar_mode
+      config&.sidebar || "config"
     end
 
-    def maybe_prepend_overview(tree, path, base_url_prefix)
-      return tree if skip_overview?(tree, path, base_url_prefix)
+    def apply_tab_scoping(base_tree)
+      return base_tree if sidebar_mode == "auto"
+      return base_tree unless tabs_configured?
 
-      [build_overview_item(base_url_prefix)] + tree
-    end
-
-    def skip_overview?(tree, path, base_url_prefix)
-      base_url_prefix.empty? ||
-        tree.first&.dig(:section) ||
-        !File.file?(File.join(path, "index.md")) ||
-        tree.any? { |item| item[:path] == base_url_prefix }
-    end
-
-    def build_overview_item(base_url_prefix)
-      {
-        title: "Overview", path: base_url_prefix, icon: nil,
-        active: current_path == base_url_prefix, type: :file,
-        collapsed: false, collapsible: false, target: "_self",
-        has_index: false, section: false, children: []
-      }
-    end
-
-    def build_tree_from_config(items, path, base_url_prefix)
-      tree = Sidebar::ConfigParser.new(
-        items, docs_path: path, current_path: current_path_relative_to(base_url_prefix)
-      ).parse.map(&:to_h)
+      active_tab = find_active_tab
+      return base_tree unless active_tab
 
-      Sidebar::PathPrefixer.new(tree, base_url_prefix).prefix
+      filter_tree_for_tab(base_tree, active_tab)
     end
 
-    def build_tree_from_filesystem(path, base_url_prefix)
-      file_items = Sidebar::FileSystemScanner.new(path).scan
-      tree = Sidebar::TreeBuilder.new(
-        docs_path: path, current_path: current_path_relative_to(base_url_prefix)
-      ).build(file_items)
+    def filter_tree_for_tab(base_tree, tab)
+      tab_path = tab["href"]&.chomp("/")
+      return base_tree if empty_tab_path?(tab_path)
 
-      Sidebar::PathPrefixer.new(tree, base_url_prefix).prefix
+      Sidebar::TreeFilter.new(base_tree, tab_path).filter
     end
 
-    def current_path_relative_to(prefix)
-      return current_path if prefix.empty?
-      return current_path unless current_path.start_with?(prefix)
-
-      relative = current_path.sub(prefix, "")
-      relative.empty? ? "/" : relative
+    def empty_tab_path?(tab_path)
+      tab_path.nil? || tab_path.empty? || tab_path == "/"
     end
 
     def renderer

data/lib/docyard/rendering/branding_variables.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Docyard
+  module BrandingVariables
+    private
+
+    def assign_branding_variables(branding, current_path = "/")
+      assign_site_branding(branding)
+      assign_search_options(branding)
+      assign_credits_and_social(branding)
+      assign_tabs(branding, current_path)
+      assign_analytics(branding)
+    end
+
+    def assign_site_branding(branding)
+      @site_title = branding[:site_title] || Constants::DEFAULT_SITE_TITLE
+      @site_description = branding[:site_description] || ""
+      @logo = branding[:logo] || Constants::DEFAULT_LOGO_PATH
+      @logo_dark = branding[:logo_dark]
+      @favicon = branding[:favicon] || Constants::DEFAULT_FAVICON_PATH
+      @has_custom_logo = branding[:has_custom_logo] || false
+      @primary_color = branding[:primary_color]
+    end
+
+    def assign_search_options(branding)
+      @search_enabled = branding[:search_enabled].nil? || branding[:search_enabled]
+      @search_placeholder = branding[:search_placeholder] || "Search documentation..."
+    end
+
+    def assign_credits_and_social(branding)
+      @credits = branding[:credits] != false
+      @copyright = branding[:copyright]
+      @social = branding[:social] || []
+      @header_ctas = branding[:header_ctas] || []
+      @announcement = branding[:announcement]
+    end
+
+    def assign_analytics(branding)
+      @has_analytics = branding[:has_analytics] || false
+      @analytics_google = branding[:analytics_google]
+      @analytics_plausible = branding[:analytics_plausible]
+      @analytics_fathom = branding[:analytics_fathom]
+      @analytics_script = branding[:analytics_script]
+    end
+
+    def assign_tabs(branding, current_path)
+      tabs = branding[:tabs] || []
+      @tabs = tabs.map { |tab| tab.merge(active: tab_active?(tab[:href], current_path)) }
+      @has_tabs = branding[:has_tabs] || false
+      @current_path = current_path
+    end
+
+    def tab_active?(tab_href, current_path)
+      return false if tab_href.nil? || current_path.nil?
+      return false if tab_href.start_with?("http://", "https://")
+
+      normalized_tab = tab_href.chomp("/")
+      normalized_current = current_path.chomp("/")
+
+      return true if normalized_tab == normalized_current
+
+      current_path.start_with?("#{normalized_tab}/")
+    end
+  end
+end