docyard 0.7.0 → 0.9.0

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

@@ -3,21 +3,56 @@
 module Docyard
   module Sidebar
     class Item
-      attr_reader :slug, :text, :icon, :link, :target, :collapsed, :items, :path, :active, :type
+      attr_reader :slug, :text, :icon, :link, :target, :collapsed, :items, :path, :active, :type, :has_index, :section,
+                  :badge, :badge_type
+
+      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]
-        @target = options[:target] || "_self"
-        @collapsed = options[:collapsed] || false
-        @items = options[:items] || []
+        @badge = options[:badge]
+        @badge_type = options[:badge_type]
+      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[:active] || false
-        @type = options[:type] || :file
+        @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?
 
@@ -37,7 +72,11 @@ module Docyard
       end
 
       def collapsible?
-        children?
+        children? && !section
+      end
+
+      def section?
+        section == true
       end
 
       def to_h
@@ -50,6 +89,10 @@ module Docyard
           collapsed: collapsed,
           collapsible: collapsible?,
           target: target,
+          has_index: has_index,
+          section: section,
+          badge: badge,
+          badge_type: badge_type,
           children: children.map(&:to_h)
         }
       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,71 @@
+# 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, badge: nil, badge_type: nil } unless File.exist?(file_path)
+
+        markdown = Markdown.new(File.read(file_path))
+        {
+          text: markdown.sidebar_text || markdown.title,
+          icon: markdown.sidebar_icon,
+          badge: markdown.sidebar_badge,
+          badge_type: markdown.sidebar_badge_type
+        }
+      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,51 @@
+# 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,
+          badge: markdown.sidebar_badge,
+          badge_type: markdown.sidebar_badge_type
+        }
+      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,
+          badge: markdown.sidebar_badge,
+          badge_type: markdown.sidebar_badge_type
+        }
+      rescue StandardError
+        empty_index_metadata
+      end
+
+      private
+
+      def empty_file_metadata
+        { title: nil, icon: nil, collapsed: nil, order: nil, badge: nil, badge_type: nil }
+      end
+
+      def empty_index_metadata
+        { sidebar_text: nil, icon: nil, collapsed: nil, order: nil, badge: nil, badge_type: 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

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

@@ -1,28 +1,29 @@
 # frozen_string_literal: true
 
 require "erb"
+require_relative "../../rendering/icon_helpers"
 
 module Docyard
   module Sidebar
     class Renderer
       include Utils::UrlHelpers
+      include IconHelpers
 
       PARTIALS_PATH = File.join(__dir__, "../../templates/partials")
 
-      attr_reader :site_title, :base_url
+      attr_reader :site_title, :base_url, :header_ctas
 
-      def initialize(site_title: "Documentation", base_url: "/")
+      def initialize(site_title: "Documentation", base_url: "/", header_ctas: [])
         @site_title = site_title
         @base_url = normalize_base_url(base_url)
+        @header_ctas = header_ctas
       end
 
       def render(tree)
         return "" if tree.empty?
 
         nav_content = render_tree_with_sections(tree)
-        footer_html = render_partial(:sidebar_footer)
-
-        render_partial(:sidebar, nav_content: nav_content, footer_html: footer_html)
+        render_partial(:sidebar, nav_content: nav_content, header_ctas: header_ctas)
       end
 
       private
@@ -37,50 +38,52 @@ module Docyard
         ERB.new(template).result(erb_binding)
       end
 
-      def icon(name, weight = "regular")
-        Icons.render(name.to_s.tr("_", "-"), weight) || ""
-      end
-
       def render_tree_with_sections(items)
         filtered_items = items.reject { |item| item[:title]&.downcase == site_title.downcase }
-        grouped_items = group_by_section(filtered_items)
-
-        grouped_items.map do |section_name, section_items|
-          render_section(section_name, section_items)
+        grouped = group_items_by_section(filtered_items)
+
+        grouped.map do |group|
+          if group[:section]
+            render_section(group[:item])
+          else
+            render_item_group(group[:items])
+          end
         end.join
       end
 
-      def render_section(section_name, section_items)
-        section_content = render_tree(section_items)
-        render_partial(:nav_section, section_name: section_name, section_content: section_content)
-      end
-
-      def group_by_section(items)
-        sections = {}
-        root_items = []
+      def group_items_by_section(items)
+        groups = []
+        current_non_section_items = []
 
         items.each do |item|
-          process_section_item(item, sections, root_items)
+          if item[:section]
+            if current_non_section_items.any?
+              groups << { section: false, items: current_non_section_items }
+              current_non_section_items = []
+            end
+            groups << { section: true, item: item }
+          else
+            current_non_section_items << item
+          end
         end
 
-        build_section_result(sections, root_items)
+        groups << { section: false, items: current_non_section_items } if current_non_section_items.any?
+        groups
       end
 
-      def process_section_item(item, sections, root_items)
-        return if item[:title]&.downcase == site_title.downcase
-
-        if item[:type] == :directory && !item[:children].empty?
-          section_name = item[:title].upcase
-          sections[section_name] = item[:children]
-        else
-          root_items << item
-        end
+      def render_section(item)
+        section_content = render_tree(item[:children])
+        render_partial(:nav_section,
+                       section_name: item[:title],
+                       section_icon: item[:icon],
+                       section_content: section_content)
       end
 
-      def build_section_result(sections, root_items)
-        result = {}
-        result[nil] = root_items unless root_items.empty?
-        result.merge!(sections)
+      def render_item_group(items)
+        render_partial(:nav_section,
+                       section_name: nil,
+                       section_icon: nil,
+                       section_content: render_tree(items))
       end
 
       def render_tree(items)
@@ -93,6 +96,8 @@ module Docyard
       def render_item(item)
         item_content = if item[:children].empty?
                          render_leaf_item(item)
+                       elsif item[:section]
+                         render_nested_section(item)
                        else
                          render_group_item(item)
                        end
@@ -107,7 +112,19 @@ module Docyard
           title: item[:title],
           active: item[:active],
           icon: item[:icon],
-          target: item[:target]
+          target: item[:target],
+          badge: item[:badge],
+          badge_type: item[:badge_type]
+        )
+      end
+
+      def render_nested_section(item)
+        children_html = render_tree(item[:children])
+        render_partial(
+          :nav_nested_section,
+          title: item[:title],
+          icon: item[:icon],
+          children_html: children_html
         )
       end
 
@@ -116,9 +133,14 @@ module Docyard
         render_partial(
           :nav_group,
           title: item[:title],
+          path: item[:path],
+          active: item[:active],
           children_html: children_html,
           icon: item[:icon],
-          collapsed: item[:collapsed]
+          collapsed: item[:collapsed],
+          has_index: item[:has_index],
+          badge: item[:badge],
+          badge_type: item[:badge_type]
         )
       end
     end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Sidebar
+    module Sorter
+      module_function
+
+      def sort_by_order(items)
+        items.sort_by do |item|
+          order = item[:order]
+          title = item[:title]&.downcase || ""
+          if order.nil?
+            [1, title]
+          else
+            [0, order, title]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,65 +1,139 @@
 # frozen_string_literal: true
 
+require_relative "sorter"
+require_relative "local_config_loader"
+require_relative "config_parser"
+require_relative "metadata_reader"
+
 module Docyard
   module Sidebar
     class TreeBuilder
-      attr_reader :docs_path, :current_path, :title_extractor
+      attr_reader :docs_path, :current_path, :title_extractor, :metadata_reader
 
       def initialize(docs_path:, current_path:, title_extractor: TitleExtractor.new)
         @docs_path = docs_path
         @current_path = Utils::PathResolver.normalize(current_path)
         @title_extractor = title_extractor
+        @metadata_reader = MetadataReader.new
       end
 
       def build(file_items)
-        transform_items(file_items, "")
+        transform_items(file_items, "", depth: 1)
       end
 
       private
 
-      def transform_items(items, relative_base)
-        items.map do |item|
+      def transform_items(items, relative_base, depth:)
+        transformed = items.map do |item|
           if item[:type] == :directory
-            transform_directory(item, relative_base)
+            transform_directory(item, relative_base, depth: depth)
           else
             transform_file(item, relative_base)
           end
         end
+        Sorter.sort_by_order(transformed)
       end
 
-      def transform_directory(item, relative_base)
+      def transform_directory(item, relative_base, depth:)
         dir_path = File.join(relative_base, item[:name])
-        children = transform_items(item[:children], dir_path)
+        dir_context = build_directory_context(dir_path)
+        children = build_directory_children(item, dir_path, depth)
 
-        {
-          title: Utils::TextFormatter.titleize(item[:name]),
-          path: nil,
-          active: false,
-          type: :directory,
-          collapsible: true,
-          collapsed: !active_child?(children),
-          children: children
-        }
+        if depth == 1
+          build_section(item, children, dir_context)
+        else
+          build_collapsible_group(item, children, dir_context)
+        end
       end
 
-      def active_child?(children)
-        children.any? do |child|
-          child[:active] || active_child?(child[:children] || [])
+      def build_directory_children(item, dir_path, depth)
+        full_dir_path = File.join(docs_path, dir_path)
+        local_config = LocalConfigLoader.new(full_dir_path).load
+
+        if local_config
+          build_children_from_config(local_config, dir_path)
+        else
+          transform_items(item[:children], dir_path, depth: depth + 1)
+        end
+      end
+
+      def build_children_from_config(config_items, base_path)
+        full_base_path = File.join(docs_path, base_path)
+        parser = ConfigParser.new(config_items, docs_path: full_base_path, current_path: current_path)
+        parser.parse.map(&:to_h)
+      end
+
+      def build_directory_context(dir_path)
+        index_file_path = File.join(docs_path, dir_path, "index.md")
+        has_index = File.file?(index_file_path)
+        { index_file_path: index_file_path, has_index: has_index,
+          url_path: has_index ? Utils::PathResolver.to_url(dir_path) : nil }
+      end
+
+      def build_section(item, children, context)
+        filtered_children = filter_index_from_children(children, context[:url_path])
+        metadata = context[:has_index] ? metadata_reader.extract_index_metadata(context[:index_file_path]) : {}
+
+        if context[:has_index]
+          overview = build_overview_item(metadata, context[:url_path])
+          filtered_children = [overview] + filtered_children
         end
+
+        build_section_hash(item, filtered_children, metadata)
+      end
+
+      def build_section_hash(item, children, metadata)
+        { title: Utils::TextFormatter.titleize(item[:name]), path: nil, icon: metadata[:icon],
+          active: false, type: :directory, section: true,
+          collapsed: false, has_index: false, order: metadata[:order], children: children }
+      end
+
+      def build_collapsible_group(item, children, context)
+        filtered_children = filter_index_from_children(children, context[:url_path])
+        metadata = context[:has_index] ? metadata_reader.extract_index_metadata(context[:index_file_path]) : {}
+        is_active = context[:has_index] && current_path == context[:url_path]
+
+        build_collapsible_hash(item, filtered_children, context, metadata, is_active)
+      end
+
+      def build_collapsible_hash(item, children, context, metadata, is_active)
+        { title: Utils::TextFormatter.titleize(item[:name]), path: context[:url_path],
+          icon: metadata[:icon], active: is_active, type: :directory, section: false,
+          collapsed: collapsible_collapsed?(children, is_active), has_index: context[:has_index],
+          order: metadata[:order], children: children }
+      end
+
+      def collapsible_collapsed?(children, is_active)
+        return false if is_active || active_child?(children)
+
+        true
+      end
+
+      def build_overview_item(metadata, url_path)
+        { title: metadata[:sidebar_text] || "Overview", path: url_path,
+          icon: metadata[:icon], active: current_path == url_path, type: :file, children: [] }
+      end
+
+      def filter_index_from_children(children, index_url_path)
+        return children unless index_url_path
+
+        children.reject { |child| child[:path] == index_url_path }
+      end
+
+      def active_child?(children)
+        children.any? { |child| child[:active] || active_child?(child[:children] || []) }
       end
 
       def transform_file(item, relative_base)
         file_path = File.join(relative_base, "#{item[:name]}#{Constants::MARKDOWN_EXTENSION}")
         full_file_path = File.join(docs_path, file_path)
         url_path = Utils::PathResolver.to_url(file_path.delete_suffix(Constants::MARKDOWN_EXTENSION))
+        metadata = metadata_reader.extract_file_metadata(full_file_path)
 
-        {
-          title: title_extractor.extract(full_file_path),
-          path: url_path,
-          active: current_path == url_path,
-          type: :file,
-          children: []
-        }
+        { title: metadata[:title] || title_extractor.extract(full_file_path),
+          path: url_path, icon: metadata[:icon], active: current_path == url_path,
+          type: :file, order: metadata[:order], badge: metadata[:badge],
+          badge_type: metadata[:badge_type], children: [] }
       end
     end
   end