jekyll-awesome-nav 0.0.1

data/README.md

@@ -0,0 +1,176 @@
+# Jekyll Awesome Nav
+
+`jekyll-awesome-nav` builds a full navigation tree from a folder hierarchy and lets any directory replace its subtree with a local `.nav.yml` file.
+
+The plugin is designed around the behavior described in [AGENTS.md](AGENTS.md):
+
+- navigation is generated from `site.pages` under one configured root
+- directories become sections and pages become leaves
+- `index.md` sets a section title and URL
+- `.nav.yml` replaces a directory subtree without merging
+- every page under the root gets the same full tree plus local subtree data
+
+## Installation
+
+Add the gem to your Jekyll site's `Gemfile`:
+
+```ruby
+gem "jekyll-awesome-nav"
+```
+
+Then enable it in `_config.yml`:
+
+```yaml
+plugins:
+  - jekyll-awesome-nav
+
+awesome_nav:
+  enabled: true
+  root: docs
+  nav_filename: .nav.yml
+```
+
+## Exposed Page Data
+
+Each page under the configured root receives:
+
+- `page.awesome_nav`: the full navigation tree rooted at `awesome_nav.root`
+- `page.awesome_nav_local`: the local subtree for the page's directory
+- `page.awesome_nav_dir`: the directory supplying the active nav context
+- `page.breadcrumbs`: breadcrumb items derived from the final tree
+- `page.awesome_nav_previous`: the previous linked nav item, when one exists
+- `page.awesome_nav_next`: the next linked nav item, when one exists
+
+The same data is also exposed on `site.config` as `awesome_nav_tree`, `awesome_nav_local_map`, and
+`awesome_nav_files`.
+
+Titles resolve in this order:
+
+1. `nav_title`
+2. `title`
+3. filename fallback
+
+## `.nav.yml` Format
+
+Overrides use a top-level `nav:` entry:
+
+```yaml
+nav:
+  - Guides: index.md
+  - Install: install.md
+  - Config: config.md
+```
+
+Override item rules:
+
+- paths are resolved through `site.pages`
+- relative paths are resolved from the `.nav.yml` directory first, then from `awesome_nav.root`
+- directory paths insert the generated directory section at that position
+- glob entries expand generated pages or directories using Ruby's stdlib glob matching
+- external URLs are preserved
+- override order is preserved exactly as written
+- manual sections are preserved as grouping sections unless they intentionally wrap the current directory
+
+Useful glob examples:
+
+```yaml
+nav:
+  - "*"
+  - "*.md"
+  - "*/"
+  - "**/*.md"
+  - glob: "*"
+```
+
+Recursive glob entries such as `**/*.md` are inserted as a flat list at that position. They do not preserve
+the matched files' directory nesting.
+
+Use manual sections to group items without linking the group itself:
+
+```yaml
+nav:
+  - Main:
+      - getting-started.md
+      - guides
+  - More Resources:
+      - Website: https://example.com
+```
+
+Use `append_unmatched` to append generated local items that were not matched by the manual nav. Child `.nav.yml`
+files inherit the closest parent setting unless they set their own value:
+
+```yaml
+append_unmatched: true
+nav:
+  - getting-started.md
+  - guides
+```
+
+Use `sort` to order generated batches from glob entries and `append_unmatched`. Manual entries stay in the order
+you write them:
+
+```yaml
+sort:
+  direction: asc
+  type: natural
+  by: filename
+  sections: last
+  ignore_case: true
+nav:
+  - intro.md
+  - "*.md"
+```
+
+`sort` is a file-level option. Per-glob options such as `- glob: "*"` with nested `sort:` are not currently
+supported.
+
+Use `ignore` to exclude generated items from glob entries and `append_unmatched`. Manual entries are still honored
+when you list them explicitly:
+
+```yaml
+ignore:
+  - "*.hidden.md"
+  - drafts/
+nav:
+  - visible.md
+  - "*.md"
+```
+
+Use `hide` in a directory's `.nav.yml` to keep that directory out of generated batches, explicit directory
+references, and child nav-file processing:
+
+```yaml
+hide: true
+```
+
+Options-only `.nav.yml` files are valid, so a hidden directory does not need a `nav:` array.
+
+## Documentation Site
+
+The source for the plugin documentation site lives in [`site/`](site). From the gem root, run:
+
+```sh
+bundle exec jekyll serve --source site
+```
+
+The docs site renders `page.awesome_nav`, `page.awesome_nav_local`, `page.breadcrumbs`, and previous/next links
+through a small layout in `site/_layouts/docs.html`.
+
+## Development
+
+Install dependencies and run the test suite:
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+You can also open an interactive console with:
+
+```sh
+bin/console
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << "test"
+  test.pattern = "test/**/*_test.rb"
+end
+
+task default: :test

data/jekyll-awesome-nav.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "lib/jekyll/awesome_nav/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "jekyll-awesome-nav"
+  spec.version = Jekyll::AwesomeNav::VERSION
+  spec.authors = ["Allison Thackston"]
+  spec.email = ["allison@allisonthackston.com"]
+
+  spec.summary = "Folder-based navigation for Jekyll with local subtree overrides."
+  spec.description = "Build a full navigation tree from a docs directory and let any folder replace its subtree with a local _nav.yml file."
+  spec.homepage = "https://github.com/PrimerPages/jekyll-awesome-nav"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
+  spec.metadata["documentation_uri"] = "https://primerpages.github.io/jekyll-awesome-nav/"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+  spec.add_dependency "jekyll", ">= 3.9", "< 5.0"
+end

data/lib/jekyll/awesome_nav/config.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module AwesomeNav
+    class Config
+      DEFAULTS = {
+        "enabled" => true,
+        "root" => "docs",
+        "nav_filename" => ".nav.yml"
+      }.freeze
+
+      def initialize(raw_config)
+        raise Error, "awesome_nav config must be a mapping" unless raw_config.nil? || raw_config.is_a?(Hash)
+
+        @data = DEFAULTS.merge(raw_config || {})
+      end
+
+      def enabled?
+        @data["enabled"]
+      end
+
+      def root_dir
+        Utils.normalize_dir(@data["root"])
+      end
+
+      def nav_filename
+        @data["nav_filename"].to_s
+      end
+    end
+  end
+end

data/lib/jekyll/awesome_nav/generator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module AwesomeNav
+    class Generator < Jekyll::Generator
+      safe true
+      priority :low
+
+      def generate(site)
+        config = Config.new(site.config["awesome_nav"])
+        return unless config.enabled?
+
+        pages = PageSet.new(site, config)
+        return if pages.empty?
+
+        tree = TreeBuilder.new(pages: pages, root_dir: config.root_dir).build
+        nav_map = NavFileLoader.new(site: site, config: config).load
+        resolved_tree = NavResolver.new(root_dir: config.root_dir, nav_map: nav_map).apply(tree, config.root_dir)
+        result = NavigationResult.new(
+          tree: resolved_tree,
+          root_dir: config.root_dir,
+          root_page: pages.root_page,
+          nav_map: nav_map
+        )
+
+        pages.each do |page|
+          page_dir = Utils.source_dir_for(page)
+          nav_dir = result.nav_dir_for(page_dir)
+          page_url = Utils.normalize_url(page.url)
+          page.data["awesome_nav"] = deep_copy(result.serialized_tree)
+          page.data["awesome_nav_local"] = deep_copy(result.local_nav_for(nav_dir))
+          page.data["awesome_nav_dir"] = nav_dir
+          page.data["breadcrumbs"] = result.breadcrumbs_for(page)
+          page.data["awesome_nav_previous"] = deep_copy(result.nav_entry_for(page_url)&.fetch("previous", nil))
+          page.data["awesome_nav_next"] = deep_copy(result.nav_entry_for(page_url)&.fetch("next", nil))
+        end
+
+        site.config["awesome_nav_tree"] = deep_copy(result.serialized_tree)
+        site.config["awesome_nav_local_map"] = deep_copy(result.serialized_local_nav_map)
+        site.config["awesome_nav_files"] = deep_copy(result.serialized_nav_files)
+      end
+
+      private
+
+      def deep_copy(value)
+        Marshal.load(Marshal.dump(value))
+      end
+    end
+  end
+end

data/lib/jekyll/awesome_nav/nav_file.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module AwesomeNav
+    class NavFile
+      attr_reader :items, :options
+
+      def initialize(items:, options:)
+        @items = items
+        @options = options
+      end
+    end
+  end
+end

data/lib/jekyll/awesome_nav/nav_file_loader.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Jekyll
+  module AwesomeNav
+    class NavFileLoader
+      OPTION_KEYS = %w[append_unmatched hide ignore sort].freeze
+
+      def initialize(site:, config:)
+        @site = site
+        @config = config
+        @page_urls_by_path = build_page_url_index
+      end
+
+      def load
+        pattern = File.join(@site.source, @config.root_dir, "**", @config.nav_filename)
+
+        Dir.glob(pattern).each_with_object({}) do |file, memo|
+          dir = Utils.normalize_dir(Utils.relative_dir(@site.source, File.dirname(file)))
+          items = load_file(file, dir)
+          memo[dir] = items if items
+        end
+      end
+
+      private
+
+      def load_file(file, dir)
+        data = YAML.safe_load_file(file, permitted_classes: [], aliases: false)
+        raise Error, "expected a mapping" unless data.is_a?(Hash)
+
+        nav = data["nav"]
+        raise Error, "expected nav to be an array" if data.key?("nav") && !nav.is_a?(Array)
+        raise Error, "expected nav to be an array or supported options" unless data.key?("nav") || options_only?(data)
+
+        items = Array(nav).map.with_index do |item, index|
+          normalize_item(item, file, dir, (index + 1).to_s)
+        end
+        NavFile.new(items: items, options: NavFileOptions.from(data))
+      rescue Psych::Exception, Error => e
+        Jekyll.logger.warn("AwesomeNav:", "Could not load #{file}: #{e.message}")
+        nil
+      end
+
+      def options_only?(data)
+        data.keys.any? { |key| OPTION_KEYS.include?(key.to_s) }
+      end
+
+      def normalize_item(item, file, dir, index_label)
+        case item
+        when Hash
+          normalize_mapping(item, file, dir, index_label)
+        when String
+          normalize_string(item, dir)
+        else
+          raise Error, "item #{index_label} in #{file} must be a mapping or path string"
+        end
+      end
+
+      def normalize_mapping(item, file, dir, index_label)
+        raise Error, "item #{index_label} in #{file} must have exactly one entry" unless item.length == 1
+
+        title, value = item.first
+        return normalize_glob(value, dir, index_label, file) if title.to_s == "glob"
+
+        title = title.to_s.strip
+        raise Error, "item #{index_label} in #{file} is missing a title" if title.empty?
+
+        case value
+        when Array
+          children = value.map.with_index do |child, child_index|
+            normalize_item(child, file, dir, "#{index_label}.#{child_index + 1}")
+          end
+          Node.section(
+            dir: nil,
+            title: title,
+            url: nil,
+            children: children,
+            path: nil,
+            filename: nil
+          )
+        when String
+          normalize_string(value, dir, title: title)
+        else
+          raise Error, "value for item #{index_label} in #{file} must be a path or array"
+        end
+      end
+
+      def normalize_string(value, dir, title: nil)
+        value = value.to_s.strip
+        raise Error, "navigation path cannot be empty" if value.empty?
+
+        return Node.page(dir: nil, title: title || value, url: value, path: value, filename: File.basename(value)) if Utils.external_url?(value)
+
+        Node.reference(dir: dir, title: title, target: value)
+      end
+
+      def normalize_glob(value, dir, index_label, file)
+        raise Error, "glob item #{index_label} in #{file} must be a path string" unless value.is_a?(String)
+
+        normalize_string(value, dir)
+      end
+
+      def build_page_url_index
+        @site.pages.each_with_object({}) do |page, index|
+          [page.path, page.relative_path, page.instance_variable_get(:@relative_path)].compact.each do |path|
+            normalized = Utils.normalize_dir(path)
+            index[normalized] = Utils.normalize_url(page.url)
+            index[without_index(normalized)] = Utils.normalize_url(page.url) if Utils.index_page?(page)
+          end
+        end
+      end
+
+      def section_url_for(dir)
+        normalized = Utils.normalize_dir(dir)
+        @page_urls_by_path[normalized] || @page_urls_by_path[File.join(normalized, "index.md")]
+      end
+
+      def source_path_for_section(dir)
+        normalized = Utils.normalize_dir(dir)
+        [File.join(normalized, "index.md"), normalized].find { |candidate| @page_urls_by_path.key?(candidate) } || normalized
+      end
+
+      def without_index(path)
+        path.sub(%r{(^|/)index(\.[^./]+)?\z}, "")
+      end
+
+      def dir_for(url)
+        return nil unless url
+        return nil if Utils.external_url?(url)
+
+        path = Utils.normalize_url(url).sub(%r{\A/}, "").sub(%r{/\z}, "")
+        return "" if path.empty?
+
+        segments = path.split("/")
+        File.extname(segments.last).empty? ? segments.join("/") : segments[0...-1].join("/")
+      end
+    end
+  end
+end

data/lib/jekyll/awesome_nav/nav_file_options.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module AwesomeNav
+    class NavFileOptions
+      UNSET = Object.new.freeze
+
+      attr_reader :ignore_patterns, :sort_options
+
+      def self.from(data)
+        new(
+          append_unmatched: data.key?("append_unmatched") ? data["append_unmatched"] : UNSET,
+          hide: data.key?("hide") ? data["hide"] : UNSET,
+          ignore: data.key?("ignore") ? data["ignore"] : UNSET,
+          sort: data.key?("sort") ? data["sort"] : UNSET
+        )
+      end
+
+      def initialize(append_unmatched: UNSET, hide: UNSET, ignore: UNSET, sort: UNSET)
+        @append_unmatched = append_unmatched
+        @hide = hide
+        @ignore_patterns = ignore == UNSET ? UNSET : normalize_ignore_patterns(ignore)
+        @sort_options = sort == UNSET ? UNSET : SortOptions.from(sort)
+      end
+
+      def append_unmatched_or(inherited)
+        return inherited if @append_unmatched == UNSET
+
+        !!@append_unmatched
+      end
+
+      def ignore_patterns_or(inherited)
+        return inherited if @ignore_patterns == UNSET
+
+        @ignore_patterns
+      end
+
+      def sort_options_or(inherited)
+        return inherited if @sort_options == UNSET
+
+        @sort_options
+      end
+
+      def hide?
+        @hide != UNSET && !!@hide
+      end
+
+      private
+
+      def normalize_ignore_patterns(value)
+        patterns =
+          case value
+          when String
+            [value]
+          when Array
+            value
+          else
+            raise Error, "ignore must be a path string or array of path strings"
+          end
+
+        patterns.map do |pattern|
+          raise Error, "ignore patterns must be path strings" unless pattern.is_a?(String)
+
+          pattern
+        end
+      end
+    end
+  end
+end