docyard 0.7.0 → 0.9.0

data/lib/docyard/navigation/breadcrumb_builder.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Docyard
+  class BreadcrumbBuilder
+    MAX_VISIBLE_ITEMS = 3
+
+    Item = Struct.new(:title, :href, :current, keyword_init: true)
+
+    attr_reader :sidebar_tree, :current_path
+
+    def initialize(sidebar_tree:, current_path:)
+      @sidebar_tree = sidebar_tree || []
+      @current_path = normalize_path(current_path)
+    end
+
+    def items
+      @items ||= build_items
+    end
+
+    def truncated?
+      full_path_items.length > MAX_VISIBLE_ITEMS
+    end
+
+    def should_show?
+      items.any? && !root_page?
+    end
+
+    private
+
+    def build_items
+      return [] if full_path_items.empty?
+
+      if truncated?
+        truncated_items
+      else
+        full_path_items
+      end
+    end
+
+    def truncated_items
+      path = full_path_items
+      [
+        Item.new(title: "...", href: nil, current: false),
+        path[-2],
+        path[-1]
+      ].compact
+    end
+
+    def full_path_items
+      @full_path_items ||= find_breadcrumb_path(sidebar_tree, [])
+    end
+
+    def find_breadcrumb_path(nodes, path)
+      nodes.each do |node|
+        result = process_node(node, path)
+        return result if result
+      end
+
+      []
+    end
+
+    def process_node(node, path)
+      node_path = normalize_path(node[:path])
+      node_title = truncate_title(node[:title] || "")
+
+      return build_current_item(path, node_title, node_path) if exact_match?(node_path)
+
+      search_in_ancestors(node, path, node_title, node_path) ||
+        search_in_children(node, path)
+    end
+
+    def build_current_item(path, title, href)
+      path + [Item.new(title: title, href: href, current: true)]
+    end
+
+    def search_in_ancestors(node, path, title, href)
+      return unless node[:children]&.any?
+
+      effective_href = href == "/" ? derive_section_path(node) : href
+      return unless path_is_ancestor?(effective_href)
+
+      result = find_breadcrumb_path(
+        node[:children],
+        path + [Item.new(title: title, href: effective_href, current: false)]
+      )
+      result.any? ? result : nil
+    end
+
+    def derive_section_path(node)
+      first_child = node[:children]&.first
+      return nil unless first_child
+
+      child_path = first_child[:path]
+      return nil if child_path.nil? || child_path.empty?
+
+      File.dirname(child_path)
+    end
+
+    def search_in_children(node, path)
+      return unless node[:children]&.any?
+
+      result = find_breadcrumb_path(node[:children], path)
+      result.any? ? result : nil
+    end
+
+    def exact_match?(node_path)
+      normalize_path(node_path) == current_path
+    end
+
+    def path_is_ancestor?(node_path)
+      return false if node_path.nil? || node_path.empty? || node_path == "/"
+
+      normalized = normalize_path(node_path)
+      current_path.start_with?("#{normalized}/") || current_path == normalized
+    end
+
+    def normalize_path(path)
+      return "/" if path.nil? || path.empty?
+
+      path.chomp("/")
+    end
+
+    def truncate_title(title)
+      return title if title.length <= 30
+
+      "#{title[0, 27]}..."
+    end
+
+    def root_page?
+      current_path == "/" || current_path.empty?
+    end
+  end
+end

data/lib/docyard/navigation/prev_next_builder.rb

@@ -124,7 +124,10 @@ module Docyard
     end
 
     def valid_navigation_item?(item)
-      item[:type] == :file && item[:path] && !external_link?(item[:path])
+      return false unless item[:path]
+      return false if external_link?(item[:path])
+
+      item[:type] == :file || (item[:type] == :directory && item[:has_index])
     end
 
     def build_link(item)

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Sidebar
+    class ChildrenDiscoverer
+      attr_reader :docs_path
+
+      def initialize(docs_path:)
+        @docs_path = docs_path
+      end
+
+      def discover(relative_path, depth:, &item_builder)
+        full_path = File.join(docs_path, relative_path)
+        return [] unless File.directory?(full_path)
+
+        local_config = load_local_sidebar_config(full_path)
+        return yield(local_config, relative_path, depth) if local_config
+
+        discover_from_filesystem(full_path, relative_path, depth, &item_builder)
+      end
+
+      private
+
+      def load_local_sidebar_config(dir_path)
+        LocalConfigLoader.new(dir_path).load
+      end
+
+      def discover_from_filesystem(full_path, relative_path, depth, &item_builder)
+        entries = filtered_entries(full_path)
+        entries.map { |entry| build_entry(entry, full_path, relative_path, depth, &item_builder) }.compact
+      end
+
+      def filtered_entries(full_path)
+        Dir.children(full_path)
+          .reject { |e| e.start_with?(".") || e.start_with?("_") || e == "index.md" }
+          .sort
+      end
+
+      def build_entry(entry, full_path, relative_path, depth)
+        entry_path = File.join(full_path, entry)
+
+        if File.directory?(entry_path)
+          yield(:directory, entry, relative_path, depth)
+        elsif entry.end_with?(".md")
+          slug = entry.delete_suffix(".md")
+          yield(:file, slug, relative_path, depth)
+        end
+      end
+    end
+  end
+end

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

@@ -2,178 +2,206 @@
 
 require_relative "item"
 require_relative "title_extractor"
+require_relative "metadata_extractor"
+require_relative "children_discoverer"
+require_relative "file_resolver"
 
 module Docyard
   module Sidebar
-    class ConfigParser
-      attr_reader :config_items, :docs_path, :current_path, :title_extractor
+    class ConfigParser # rubocop:disable Metrics/ClassLength
+      attr_reader :config_items, :docs_path, :current_path, :metadata_extractor,
+                  :children_discoverer, :file_resolver
 
       def initialize(config_items, docs_path:, current_path: "/", title_extractor: TitleExtractor.new)
         @config_items = config_items || []
         @docs_path = docs_path
         @current_path = Utils::PathResolver.normalize(current_path)
-        @title_extractor = title_extractor
+        @metadata_extractor = MetadataExtractor.new(docs_path: docs_path, title_extractor: title_extractor)
+        @children_discoverer = ChildrenDiscoverer.new(docs_path: docs_path)
+        @file_resolver = FileResolver.new(
+          docs_path: docs_path, current_path: @current_path, metadata_extractor: metadata_extractor
+        )
       end
 
       def parse
-        parse_items(config_items)
+        parse_items(config_items, "", depth: 1)
       end
 
       private
 
-      def parse_items(items, base_path = "")
-        items.map do |item_config|
-          parse_item(item_config, base_path)
-        end.compact
+      def parse_items(items, base_path, depth:)
+        items.map { |item_config| parse_item(item_config, base_path, depth: depth) }.compact
       end
 
-      def parse_item(item_config, base_path)
+      def parse_item(item_config, base_path, depth:)
         case item_config
-        when String
-          resolve_file_item(item_config, base_path)
-        when Hash
-          parse_hash_item(item_config, base_path)
+        when String then resolve_string_item(item_config, base_path, depth: depth)
+        when Hash then parse_hash_item(item_config, base_path, depth: depth)
         end
       end
 
-      def parse_hash_item(item_config, base_path)
-        return parse_link_item(item_config) if link_item?(item_config)
-        return parse_nested_item(item_config, base_path) if nested_item?(item_config)
-        return resolve_file_item(item_config.keys.first, base_path, {}) if nil_value_item?(item_config)
-
-        slug = item_config.keys.first
-        options = item_config.values.first || {}
-        resolve_file_item(slug, base_path, options)
-      end
-
-      def link_item?(config)
-        config.key?("link") || config.key?(:link)
+      def resolve_string_item(slug, base_path, depth:)
+        if File.directory?(File.join(docs_path, base_path, slug))
+          build_directory_item(slug, {}, [], base_path, depth: depth)
+        else
+          file_resolver.resolve(slug, base_path)
+        end
       end
 
-      def nested_item?(config)
-        config.size == 1 && config.values.first.is_a?(Hash)
-      end
+      def parse_hash_item(item_config, base_path, depth:)
+        return file_resolver.build_link_item(item_config) if external_link?(item_config)
 
-      def nil_value_item?(config)
-        config.size == 1 && config.values.first.nil?
-      end
+        slug = item_config.keys.first
+        options = item_config.values.first
 
-      def parse_link_item(config)
-        link = config["link"] || config[:link]
-        text = config["text"] || config[:text]
-        icon = config["icon"] || config[:icon]
-        target = config["target"] || config[:target] || "_blank"
+        return file_resolver.resolve(slug, base_path, {}) if options.nil?
+        return parse_nested_item(slug, options, base_path, depth: depth) if options.is_a?(Hash)
 
-        Item.new(
-          text: text,
-          link: link,
-          path: link,
-          icon: icon,
-          target: target,
-          type: :external
-        )
+        file_resolver.resolve(slug, base_path, options)
       end
 
-      def parse_nested_item(item_config, base_path)
-        slug = item_config.keys.first.to_s
-        options = item_config.values.first || {}
-        nested_items = extract_nested_items(options)
+      def external_link?(config)
+        config.key?("link") || config.key?(:link)
+      end
 
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def parse_nested_item(slug, options, base_path, depth:)
+        slug = slug.to_s
+        nested_items = options["items"] || options[:items] || []
         dir_path = File.join(docs_path, base_path, slug)
+        is_virtual_group = (options["section"] == false || options[:section] == false) && nested_items.any?
 
-        if File.directory?(dir_path)
-          build_directory_item(slug, options, nested_items, base_path)
+        if is_virtual_group
+          build_virtual_group_item(slug, options, nested_items, base_path, depth: depth)
+        elsif File.directory?(dir_path)
+          build_directory_item(slug, options, nested_items, base_path, depth: depth)
         elsif nested_items.any?
-          build_file_with_children_item(slug, options, nested_items, base_path)
+          build_file_with_children_item(slug, options, nested_items, base_path, depth: depth)
         else
-          resolve_file_item(slug, base_path, options)
+          file_resolver.resolve(slug, base_path, options)
         end
       end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
-      def extract_nested_items(options)
-        options["items"] || options[:items] || []
-      end
-
-      def extract_common_options(options)
-        {
-          text: options["text"] || options[:text],
-          icon: options["icon"] || options[:icon],
-          collapsed: options["collapsed"] || options[:collapsed] || false
-        }
-      end
-
-      def build_directory_item(slug, options, nested_items, base_path)
-        common_opts = extract_common_options(options)
-        new_base_path = File.join(base_path, slug)
-        parsed_items = parse_items(nested_items, new_base_path)
+      def build_virtual_group_item(slug, options, nested_items, base_path, depth:)
+        common_opts = metadata_extractor.extract_common_options(options)
+        parsed_items = parse_items(nested_items, base_path, depth: depth + 1)
+        is_collapsed = common_opts[:collapsed] != false && !active_child?(parsed_items)
 
         Item.new(
           slug: slug,
           text: common_opts[:text] || Utils::TextFormatter.titleize(slug),
+          path: nil,
           icon: common_opts[:icon],
-          collapsed: common_opts[:collapsed],
+          collapsed: is_collapsed,
+          active: false,
           items: parsed_items,
-          type: :directory
+          type: :directory,
+          section: false
         )
       end
 
-      def build_file_with_children_item(slug, options, nested_items, base_path)
-        common_opts = extract_common_options(options)
-        file_path = File.join(docs_path, base_path, "#{slug}.md")
-        url_path = Utils::PathResolver.to_url(File.join(base_path, slug))
-        resolved_text = common_opts[:text] || extract_file_title(file_path, slug)
+      def build_directory_item(slug, options, nested_items, base_path, depth:)
+        context = build_directory_context(slug, options, nested_items, base_path, depth)
+        context[:parsed_items] = prepend_intro_if_needed(context, depth)
+        create_directory_item(slug, context, depth)
+      end
+
+      def build_directory_context(slug, options, nested_items, base_path, depth)
+        new_base_path = File.join(base_path, slug)
+        {
+          common_opts: metadata_extractor.extract_common_options(options),
+          parsed_items: resolve_directory_children(nested_items, new_base_path, depth),
+          **build_index_info(new_base_path)
+        }
+      end
+
+      def build_index_info(base_path)
+        index_file_path = File.join(docs_path, base_path, "index.md")
+        has_index = File.file?(index_file_path)
+        url_path = has_index ? Utils::PathResolver.to_url(base_path) : nil
+
+        { index_file_path: index_file_path, has_index: has_index,
+          url_path: url_path, is_active: has_index && current_path == url_path }
+      end
+
+      def resolve_directory_children(nested_items, base_path, depth)
+        return parse_items(nested_items, base_path, depth: depth + 1) if nested_items.any?
+
+        auto_discover_children(base_path, depth: depth + 1)
+      end
+
+      def prepend_intro_if_needed(context, depth)
+        is_section = section_for_depth?(context[:common_opts][:section], depth)
+        return context[:parsed_items] unless is_section && context[:has_index]
+
+        [build_introduction_item(context[:index_file_path], context[:url_path])] + context[:parsed_items]
+      end
 
+      def create_directory_item(slug, context, depth)
+        is_section = section_for_depth?(context[:common_opts][:section], depth)
         Item.new(
           slug: slug,
-          text: resolved_text,
-          path: url_path,
-          icon: common_opts[:icon],
-          collapsed: common_opts[:collapsed],
-          items: parse_items(nested_items, base_path),
-          active: current_path == url_path,
-          type: :file
+          text: context[:common_opts][:text] || Utils::TextFormatter.titleize(slug),
+          path: is_section ? nil : context[:url_path],
+          icon: context[:common_opts][:icon],
+          collapsed: is_section ? false : directory_collapsed?(context),
+          active: is_section ? false : context[:is_active],
+          has_index: is_section ? false : context[:has_index],
+          items: context[:parsed_items],
+          type: :directory,
+          section: is_section
         )
       end
 
-      def extract_file_title(file_path, slug)
-        File.exist?(file_path) ? title_extractor.extract(file_path) : Utils::TextFormatter.titleize(slug)
-      end
+      def section_for_depth?(explicit_section, depth)
+        return explicit_section unless explicit_section.nil?
 
-      def resolve_file_item(slug, base_path, options = {})
-        slug_str = slug.to_s
-        options ||= {}
+        depth == 1
+      end
 
-        file_path = File.join(docs_path, base_path, "#{slug_str}.md")
-        url_path = Utils::PathResolver.to_url(File.join(base_path, slug_str))
+      def directory_collapsed?(context)
+        return false if context[:is_active] || active_child?(context[:parsed_items])
 
-        frontmatter = extract_frontmatter_metadata(file_path)
-        text = resolve_item_text(slug_str, file_path, options, frontmatter[:text])
-        icon = resolve_item_icon(options, frontmatter[:icon])
-        final_path = options["link"] || options[:link] || url_path
+        context[:common_opts][:collapsed] != false
+      end
 
+      def build_introduction_item(index_file_path, url_path)
+        metadata = metadata_extractor.extract_index_metadata(index_file_path)
         Item.new(
-          slug: slug_str, text: text, path: final_path, icon: icon,
-          active: current_path == final_path, type: :file
+          slug: "index", text: metadata[:sidebar_text] || "Overview",
+          path: url_path, icon: metadata[:icon], active: current_path == url_path, type: :file
         )
       end
 
-      def extract_frontmatter_metadata(file_path)
-        return { text: nil, icon: nil } unless File.exist?(file_path)
+      def build_file_with_children_item(slug, options, nested_items, base_path, depth:)
+        file_resolver.build_file_with_children(
+          slug: slug, options: options, base_path: base_path,
+          parsed_items: parse_items(nested_items, base_path, depth: depth + 1),
+          depth: depth
+        )
+      end
 
-        markdown = Markdown.new(File.read(file_path))
-        {
-          text: markdown.sidebar_text || markdown.title,
-          icon: markdown.sidebar_icon
-        }
+      def auto_discover_children(relative_path, depth:)
+        children_discoverer.discover(relative_path, depth: depth) do |config_or_type, *args|
+          if config_or_type.is_a?(Array)
+            parse_items(config_or_type, args[0], depth: args[1])
+          else
+            build_discovered_item(config_or_type, args[0], args[1], depth)
+          end
+        end
       end
 
-      def resolve_item_text(slug, file_path, options, frontmatter_text)
-        text = options["text"] || options[:text] || frontmatter_text
-        text || extract_file_title(file_path, slug)
+      def build_discovered_item(type, slug, base_path, depth)
+        if type == :directory
+          build_directory_item(slug, {}, [], base_path, depth: depth)
+        else
+          file_resolver.resolve(slug, base_path)
+        end
       end
 
-      def resolve_item_icon(options, frontmatter_icon)
-        options["icon"] || options[:icon] || frontmatter_icon
+      def active_child?(items)
+        items.any? { |item| item.active || active_child?(item.items) }
       end
     end
   end

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "item"
+
+module Docyard
+  module Sidebar
+    class FileResolver
+      attr_reader :docs_path, :current_path, :metadata_extractor
+
+      def initialize(docs_path:, current_path:, metadata_extractor:)
+        @docs_path = docs_path
+        @current_path = current_path
+        @metadata_extractor = metadata_extractor
+      end
+
+      def resolve(slug, base_path, options = {})
+        context = build_context(slug.to_s, base_path, options || {})
+        Item.new(**context)
+      end
+
+      def build_link_item(config)
+        Item.new(
+          text: config["text"] || config[:text],
+          link: config["link"] || config[:link],
+          path: config["link"] || config[:link],
+          icon: config["icon"] || config[:icon],
+          target: config["target"] || config[:target] || "_blank",
+          type: :external,
+          section: false
+        )
+      end
+
+      def build_file_with_children(slug:, options:, base_path:, parsed_items:, depth: 1)
+        common_opts = metadata_extractor.extract_common_options(options)
+        file_path = File.join(docs_path, base_path, "#{slug}.md")
+        url_path = Utils::PathResolver.to_url(File.join(base_path, slug))
+        is_section = section_for_depth?(common_opts[:section], depth)
+
+        Item.new(
+          slug: slug,
+          text: common_opts[:text] || metadata_extractor.extract_file_title(file_path, slug),
+          path: is_section ? nil : url_path,
+          icon: common_opts[:icon],
+          collapsed: is_section ? false : common_opts[:collapsed],
+          items: parsed_items,
+          active: is_section ? false : current_path == url_path,
+          type: is_section ? :section : :file,
+          section: is_section
+        )
+      end
+
+      private
+
+      def section_for_depth?(explicit_section, depth)
+        return explicit_section unless explicit_section.nil?
+
+        depth == 1
+      end
+
+      def build_context(slug, base_path, options)
+        paths = resolve_paths(slug, base_path, options)
+        frontmatter = metadata_extractor.extract_frontmatter_metadata(paths[:file])
+
+        build_context_hash(slug, paths, options, frontmatter)
+      end
+
+      def resolve_paths(slug, base_path, options)
+        file_path = File.join(docs_path, base_path, "#{slug}.md")
+        url_path = Utils::PathResolver.to_url(File.join(base_path, slug))
+        final_path = options["link"] || options[:link] || url_path
+
+        { file: file_path, final: final_path }
+      end
+
+      def build_context_hash(slug, paths, options, frontmatter)
+        {
+          slug: slug,
+          text: metadata_extractor.resolve_item_text(slug, paths[:file], options, frontmatter[:text]),
+          path: paths[:final],
+          icon: metadata_extractor.resolve_item_icon(options, frontmatter[:icon]),
+          badge: frontmatter[:badge],
+          badge_type: frontmatter[:badge_type],
+          active: current_path == paths[:final],
+          type: :file,
+          section: false
+        }
+      end
+    end
+  end
+end

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

@@ -66,7 +66,8 @@ module Docyard
       def hidden_or_ignored?(entry, relative_path)
         entry.start_with?(".") ||
           entry.start_with?("_") ||
-          (entry == "index.md" && relative_path.empty?)
+          (entry == "index.md" && relative_path.empty?) ||
+          (entry == "public" && relative_path.empty?)
       end
 
       def sort_key(entry)