docyard 0.6.0 → 0.8.0

data/lib/docyard/{prev_next_builder.rb → navigation/prev_next_builder.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "renderer"
-require_relative "utils/path_resolver"
+require_relative "../rendering/renderer"
+require_relative "../utils/path_resolver"
 
 module Docyard
   class PrevNextBuilder
@@ -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

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+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 # 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)
+        @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, "", depth: 1)
+      end
+
+      private
+
+      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, depth:)
+        case item_config
+        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 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 parse_hash_item(item_config, base_path, depth:)
+        return file_resolver.build_link_item(item_config) if external_link?(item_config)
+
+        slug = item_config.keys.first
+        options = item_config.values.first
+
+        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)
+
+        file_resolver.resolve(slug, base_path, options)
+      end
+
+      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 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, depth: depth)
+        else
+          file_resolver.resolve(slug, base_path, options)
+        end
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      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: is_collapsed,
+          active: false,
+          items: parsed_items,
+          type: :directory,
+          section: false
+        )
+      end
+
+      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: 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 section_for_depth?(explicit_section, depth)
+        return explicit_section unless explicit_section.nil?
+
+        depth == 1
+      end
+
+      def directory_collapsed?(context)
+        return false if context[:is_active] || active_child?(context[:parsed_items])
+
+        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: "index", text: metadata[:sidebar_text] || "Overview",
+          path: url_path, icon: metadata[:icon], active: current_path == url_path, type: :file
+        )
+      end
+
+      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
+
+      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 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 active_child?(items)
+        items.any? { |item| item.active || active_child?(item.items) }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# 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)
+        file_path = File.join(docs_path, base_path, "#{slug}.md")
+        url_path = Utils::PathResolver.to_url(File.join(base_path, slug))
+        frontmatter = metadata_extractor.extract_frontmatter_metadata(file_path)
+        final_path = options["link"] || options[:link] || url_path
+
+        {
+          slug: slug,
+          text: metadata_extractor.resolve_item_text(slug, file_path, options, frontmatter[:text]),
+          path: final_path,
+          icon: metadata_extractor.resolve_item_icon(options, frontmatter[:icon]),
+          active: current_path == final_path,
+          type: :file,
+          section: false
+        }
+      end
+    end
+  end
+end

data/lib/docyard/{sidebar → 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)

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Sidebar
+    class Item
+      attr_reader :slug, :text, :icon, :link, :target, :collapsed, :items, :path, :active, :type, :has_index, :section
+
+      DEFAULTS = {
+        target: "_self",
+        collapsed: false,
+        items: [],
+        active: false,
+        type: :file,
+        has_index: false,
+        section: true
+      }.freeze
+
+      def initialize(**options)
+        assign_required_attributes(options)
+        assign_optional_attributes(options)
+      end
+
+      private
+
+      def assign_required_attributes(options)
+        @slug = options[:slug]
+        @text = options[:text]
+        @icon = options[:icon]
+        @link = options[:link]
+      end
+
+      def assign_optional_attributes(options)
+        assign_navigation_attributes(options)
+        assign_state_attributes(options)
+      end
+
+      def assign_navigation_attributes(options)
+        @target = options.fetch(:target, DEFAULTS[:target])
+        @path = options[:path] || options[:link]
+        @active = options.fetch(:active, DEFAULTS[:active])
+        @type = options.fetch(:type, DEFAULTS[:type])
+      end
+
+      def assign_state_attributes(options)
+        @collapsed = options.fetch(:collapsed, DEFAULTS[:collapsed])
+        @items = options.fetch(:items, DEFAULTS[:items])
+        @has_index = options.fetch(:has_index, DEFAULTS[:has_index])
+        @section = options.fetch(:section, DEFAULTS[:section])
+      end
+
+      public
+
+      def external?
+        return false if path.nil?
+
+        path.start_with?("http://", "https://")
+      end
+
+      def children?
+        items.any?
+      end
+
+      def title
+        text
+      end
+
+      def children
+        items
+      end
+
+      def collapsible?
+        children? && !section
+      end
+
+      def section?
+        section == true
+      end
+
+      def to_h
+        {
+          title: title,
+          path: path,
+          icon: icon,
+          active: active,
+          type: type,
+          collapsed: collapsed,
+          collapsible: collapsible?,
+          target: target,
+          has_index: has_index,
+          section: section,
+          children: children.map(&:to_h)
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Docyard
+  module Sidebar
+    class LocalConfigLoader
+      SIDEBAR_CONFIG_FILE = "_sidebar.yml"
+
+      attr_reader :docs_path
+
+      def initialize(docs_path)
+        @docs_path = docs_path
+      end
+
+      def load
+        return nil unless config_file_exists?
+
+        parse_config_file
+      end
+
+      def config_file_exists?
+        File.file?(config_file_path)
+      end
+
+      private
+
+      def config_file_path
+        File.join(docs_path, SIDEBAR_CONFIG_FILE)
+      end
+
+      def parse_config_file
+        content = YAML.load_file(config_file_path)
+        normalize_config(content)
+      rescue Psych::SyntaxError => e
+        warn "Warning: Invalid YAML in #{config_file_path}: #{e.message}"
+        nil
+      rescue StandardError => e
+        warn "Warning: Error reading #{config_file_path}: #{e.message}"
+        nil
+      end
+
+      def normalize_config(content)
+        return nil if content.nil?
+        return content if content.is_a?(Array)
+
+        content["items"] if content.is_a?(Hash)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Sidebar
+    class MetadataExtractor
+      attr_reader :docs_path, :title_extractor
+
+      def initialize(docs_path:, title_extractor:)
+        @docs_path = docs_path
+        @title_extractor = title_extractor
+      end
+
+      def extract_index_metadata(file_path)
+        return { sidebar_text: nil, icon: nil } unless File.file?(file_path)
+
+        markdown = Markdown.new(File.read(file_path))
+        {
+          sidebar_text: markdown.sidebar_text,
+          icon: markdown.sidebar_icon
+        }
+      rescue StandardError
+        { sidebar_text: nil, icon: nil }
+      end
+
+      def extract_frontmatter_metadata(file_path)
+        return { text: nil, icon: nil } unless File.exist?(file_path)
+
+        markdown = Markdown.new(File.read(file_path))
+        {
+          text: markdown.sidebar_text || markdown.title,
+          icon: markdown.sidebar_icon
+        }
+      end
+
+      def extract_file_title(file_path, slug)
+        File.exist?(file_path) ? title_extractor.extract(file_path) : Utils::TextFormatter.titleize(slug)
+      end
+
+      def extract_common_options(options)
+        collapsed_value = options["collapsed"]
+        collapsed_value = options[:collapsed] if collapsed_value.nil?
+        collapsible_value = options["collapsible"]
+        collapsible_value = options[:collapsible] if collapsible_value.nil?
+        collapsible_value = true if !collapsed_value.nil? && collapsible_value.nil?
+        {
+          text: options["text"] || options[:text],
+          icon: options["icon"] || options[:icon],
+          collapsed: collapsed_value,
+          section: section_from_collapsible(collapsible_value)
+        }
+      end
+
+      def section_from_collapsible(collapsible_value)
+        return nil if collapsible_value.nil?
+
+        collapsible_value != true
+      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)
+      end
+
+      def resolve_item_icon(options, frontmatter_icon)
+        options["icon"] || options[:icon] || frontmatter_icon
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Sidebar
+    class MetadataReader
+      def extract_file_metadata(file_path)
+        return empty_file_metadata unless File.file?(file_path)
+
+        content = File.read(file_path)
+        markdown = Markdown.new(content)
+        {
+          title: markdown.sidebar_text || markdown.title,
+          icon: markdown.sidebar_icon,
+          collapsed: markdown.sidebar_collapsed,
+          order: markdown.sidebar_order
+        }
+      rescue StandardError
+        empty_file_metadata
+      end
+
+      def extract_index_metadata(file_path)
+        return empty_index_metadata unless File.file?(file_path)
+
+        content = File.read(file_path)
+        markdown = Markdown.new(content)
+        {
+          sidebar_text: markdown.sidebar_text,
+          icon: markdown.sidebar_icon,
+          collapsed: markdown.sidebar_collapsed,
+          order: markdown.sidebar_order
+        }
+      rescue StandardError
+        empty_index_metadata
+      end
+
+      private
+
+      def empty_file_metadata
+        { title: nil, icon: nil, collapsed: nil, order: nil }
+      end
+
+      def empty_index_metadata
+        { sidebar_text: nil, icon: nil, collapsed: nil, order: nil }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Sidebar
+    class PathPrefixer
+      def initialize(tree, prefix)
+        @tree = tree
+        @prefix = prefix
+      end
+
+      def prefix
+        return @tree if @prefix.empty?
+
+        @tree.map { |item| prefix_item(item) }
+      end
+
+      private
+
+      def prefix_item(item)
+        prefixed = item.dup
+        prefixed[:path] = prefixed_path(prefixed[:path])
+        prefixed[:children] = self.class.new(prefixed[:children], @prefix).prefix if prefixed[:children]&.any?
+        prefixed
+      end
+
+      def prefixed_path(path)
+        return path if path.nil? || path.start_with?("http")
+
+        path_without_slash = path.sub(%r{^/}, "")
+        path_without_slash.empty? ? @prefix : "#{@prefix}/#{path_without_slash}"
+      end
+    end
+  end
+end