jekyll-awesome-nav 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01fa08c8a44630c6314fb330db8db6de0977bc66adb8e2c48dd5f127ede6ff8d
-  data.tar.gz: 29964bc8684fc64593bb76b9385ec19706b578aef5ee780155be2f518c50873b
+  metadata.gz: 2cfc859de2a4762ba5046338aa7bc12049da70bfb2d9ac27d727eace95322f11
+  data.tar.gz: 0f14a593b81ec5882b65db61b82e93d8bd8f9a3656a8d730cd0f4175a2da65e3
 SHA512:
-  metadata.gz: d191dc308b3c7b7b2431417f12c4cdfe59b7acb4c2461364beec68a481909b81dad07724405ee2a2a1644203b6bf13705e86f60af8e98b0895363b3a202a5cb1
-  data.tar.gz: ef4ed52b48b7595d0994ff1f19ba64d70d4e81998ea1ded6b14b395f165a11a0ea5efe43bff3de73ebd8c7e35a48a5e06e7ec1054ff2407becfc838e7ceae6ae
+  metadata.gz: 39eccdb01ce4ecd9c828f2c66b6997b6ef769ec199ffb6a94a206fa6f449c615f84edf7928290029adde02b97bdc24a9050ae70654047915181c26bd81c72a49
+  data.tar.gz: '008767e37db8c06b2b2c77ffa4a1cc9f437653a33684a90994d7e7da854b836b5c39687ed3065d0adcd1e6692f757a1e9346cec259e85725d5853495112f33bb'

data/.copier-answers.ci.yml

@@ -1,5 +1,5 @@
 # Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
-_commit: aac269f
+_commit: afa589e
 _src_path: gh:athackst/ci
 automerge_mode: poll
 bump_script_path: ''

data/lib/jekyll/awesome_nav/generator.rb

@@ -15,35 +15,52 @@ module Jekyll
         pages = PageSet.new(site, config)
         return if pages.empty?
 
+        result = build_navigation_result(site, config, pages)
+        assign_page_navigation(pages, result)
+        assign_site_navigation(site, result)
+      end
+
+      private
+
+      def build_navigation_result(site, config, pages)
         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(
+        resolved_tree = NavResolver.new(
+          root_dir: config.root_dir,
+          nav_map: nav_map,
+          root_page: pages.root_page
+        ).apply(tree, config.root_dir)
+
+        NavigationResult.new(
           tree: resolved_tree,
           root_dir: config.root_dir,
           root_page: pages.root_page,
           nav_map: nav_map
         )
+      end
 
+      def assign_page_navigation(pages, result)
         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_entry = result.nav_entry_for(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))
+          page.data["awesome_nav_previous"] = deep_copy(page_entry&.fetch("previous", nil))
+          page.data["awesome_nav_next"] = deep_copy(page_entry&.fetch("next", nil))
         end
+      end
 
+      def assign_site_navigation(site, result)
         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

data/lib/jekyll/awesome_nav/nav_resolver.rb

@@ -2,12 +2,16 @@
 
 module Jekyll
   module AwesomeNav
+    # This class centralizes override resolution, matching, and unmatched append
+    # behavior, so a narrow class-length suppression keeps the logic together.
+    # rubocop:disable Metrics/ClassLength
     class NavResolver
       ResolutionContext = Struct.new(:append_unmatched, :sort_options, :ignore_patterns, keyword_init: true)
 
-      def initialize(root_dir:, nav_map:)
+      def initialize(root_dir:, nav_map:, root_page: nil)
         @root_dir = root_dir
         @nav_map = nav_map
+        @root_page = root_page
         @generated_by_dir = {}
         @generated_by_path = {}
       end
@@ -71,7 +75,10 @@ module Jekyll
       end
 
       def same_dir_wrapper?(items, current_dir)
-        items.length == 1 && items.first.section? && Utils.normalize_dir(items.first.dir) == current_dir
+        items.length == 1 &&
+          items.first.section? &&
+          !items.first.dir.nil? &&
+          Utils.normalize_dir(items.first.dir) == current_dir
       end
 
       def raw_same_dir_wrapper?(current_dir)
@@ -149,7 +156,13 @@ module Jekyll
         return [] unless generated
         return [] if hidden?(generated)
 
-        return [section_page_node(generated, item.title)] if generated.section? && Utils.normalize_dir(generated.dir) == current_dir
+        if generated.section? &&
+           (Utils.normalize_dir(generated.dir) == current_dir || references_section_index?(item, current_dir, generated))
+          node = section_page_node(generated, item.title)
+          mark_matched(node, matched)
+          mark_section_consumed(generated, matched)
+          return [node]
+        end
 
         node = generated.deep_dup
         node.title = item.title if item.title
@@ -229,7 +242,10 @@ module Jekyll
           next if ignored?(item, current_dir, context.ignore_patterns)
 
           node = item.deep_dup
-          with_resolved_children(node, Utils.normalize_dir(node.dir), context)
+          pruned = prune_matched_descendants(node, matched, context, current_dir)
+          next if pruned.nil?
+
+          with_resolved_children(pruned, Utils.normalize_dir(pruned.dir), context)
         end
       end
 
@@ -240,6 +256,9 @@ module Jekyll
 
           section = @generated_by_dir[candidate]
           return section if section
+
+          root = root_page_node_for(candidate)
+          return root if root
         end
 
         nil
@@ -337,10 +356,38 @@ module Jekyll
         matched[node_key(item)]
       end
 
+      def prune_matched_descendants(item, matched, context, current_dir)
+        return nil if matched?(item, matched)
+        return item unless item.section?
+
+        child_dir = Utils.normalize_dir(item.dir)
+        pruned_children = item.children.filter_map do |child|
+          next if hidden?(child)
+          next if ignored?(child, child_dir.empty? ? current_dir : child_dir, context.ignore_patterns)
+
+          prune_matched_descendants(child.deep_dup, matched, context, child_dir.empty? ? current_dir : child_dir)
+        end
+
+        return nil if pruned_children.empty? && item.url.nil?
+
+        Node.section(
+          dir: item.dir,
+          title: item.title,
+          url: item.url,
+          children: pruned_children,
+          path: item.path,
+          filename: item.filename
+        )
+      end
+
       def node_key(item)
         item.section? ? "dir:#{Utils.normalize_dir(item.dir)}" : "path:#{Utils.normalize_dir(item.path || item.url)}"
       end
 
+      def mark_section_consumed(item, matched)
+        matched["dir:#{Utils.normalize_dir(item.dir)}"] = true
+      end
+
       def child_dir_for_item(parent_dir, item)
         return Utils.normalize_dir(item.dir) if item.dir
         return nil unless item.url
@@ -365,6 +412,31 @@ module Jekyll
         segments = path.split("/")
         File.extname(segments.last).empty? ? segments.join("/") : segments[0...-1].join("/")
       end
+
+      def root_page_node_for(candidate)
+        return nil unless @root_page
+
+        normalized = Utils.normalize_dir(candidate)
+        root_index_path = Utils.normalize_dir(File.join(@root_dir, "index.md"))
+        root_readme_path = Utils.normalize_dir(File.join(@root_dir, "README.md"))
+        root_readme_lower_path = Utils.normalize_dir(File.join(@root_dir, "readme.md"))
+        return nil unless [@root_dir, root_index_path, "index.md", root_readme_path, root_readme_lower_path].include?(normalized)
+
+        Node.page(
+          dir: @root_dir,
+          title: Utils.page_title(@root_page, File.basename(@root_page.path, File.extname(@root_page.path))),
+          url: Utils.normalize_url(@root_page.url),
+          path: Utils.source_path_for(@root_page),
+          filename: File.basename(Utils.source_path_for(@root_page))
+        )
+      end
+
+      def references_section_index?(item, current_dir, generated)
+        return false unless generated.path
+
+        candidates_for(item.target, current_dir).include?(Utils.normalize_dir(generated.path))
+      end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/jekyll/awesome_nav/version.rb

@@ -2,7 +2,7 @@
 
 module Jekyll
   module AwesomeNav
-    VERSION = "0.1.0"
+    VERSION = "0.1.2"
 
     def self.warn_if_unstamped_version(output = $stderr)
       return unless VERSION == "0.0.0"

data/site/docs/guides/.nav.yml

@@ -3,5 +3,6 @@ nav:
       - Install Guide: install.md
       - Layout Integration: layouts.md
       - Configuration: config.md
+      - .nav.yml Reference: nav-file.md
       - Navigation Overrides: overrides.md
       - Generated Data: data.md

data/site/docs/guides/index.md

@@ -11,5 +11,6 @@ The `docs/guides/.nav.yml` file replaces this subtree, which means the guides ca
 - [Install Guide]({{ "/docs/guides/install/" | relative_url }})
 - [Layout Integration]({{ "/docs/guides/layouts/" | relative_url }})
 - [Configuration]({{ "/docs/guides/config/" | relative_url }})
+- [.nav.yml Reference]({{ "/docs/guides/nav-file/" | relative_url }})
 - [Navigation Overrides]({{ "/docs/guides/overrides/" | relative_url }})
 - [Generated Data]({{ "/docs/guides/data/" | relative_url }})

data/site/docs/guides/nav-file.md

@@ -0,0 +1,260 @@
+---
+title: .nav.yml Reference
+---
+
+`.nav.yml` lets a directory replace its generated navigation subtree with a hand-authored one.
+
+Put the file in the directory you want to control:
+
+```text
+docs/
+  guides/
+    .nav.yml
+    index.md
+    install.md
+    config.md
+```
+
+The override applies only to that directory subtree. Parent sections and sibling sections keep using their own generated or overridden navigation.
+
+## Minimal file
+
+The smallest useful `.nav.yml` defines a `nav:` array:
+
+```yaml
+nav:
+  - Guides Home: index.md
+  - Install: install.md
+  - Configuration: config.md
+```
+
+Each item is either:
+
+- a string path like `install.md`
+- a titled path mapping like `Install: install.md`
+- a titled section with nested children
+- a glob entry such as `"*.md"`
+
+## Top-level options
+
+These keys are supported at the top level of `.nav.yml`:
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `nav` | array | Manual nav entries for this directory. |
+| `append_unmatched` | boolean | Appends generated items that were not matched by `nav`. |
+| `ignore` | string or array | Excludes generated items from globs and `append_unmatched`. |
+| `sort` | mapping | Sorts generated batches from globs and `append_unmatched`. |
+| `hide` | boolean | Hides this directory from generated nav, manual directory references, and child nav processing. |
+
+Options-only files are valid, so this works when you only want to hide a directory:
+
+```yaml
+hide: true
+```
+
+## `nav` items
+
+### String paths
+
+Use a string when you want the generated page or section title:
+
+```yaml
+nav:
+  - index.md
+  - install.md
+  - guides
+```
+
+- File paths insert a page.
+- Directory paths insert that directory's generated section.
+- External URLs are allowed and stay as-is.
+
+### Titled paths
+
+Use a mapping to rename an item in navigation:
+
+```yaml
+nav:
+  - Guides Hub: index.md
+  - Install Guide: install.md
+  - Project Website: https://example.com
+```
+
+### Manual sections
+
+Use a titled list to create a group:
+
+```yaml
+nav:
+  - Main:
+      - getting-started.md
+      - Guides: guides
+  - More:
+      - API Reference: ../reference.md
+      - Project Website: https://example.com
+```
+
+Manual sections are grouping nodes. They do not get their own URL unless you point them at a page instead of a child list.
+
+## Path resolution
+
+Paths are resolved in this order:
+
+1. Relative to the directory that contains the `.nav.yml`
+2. Relative to `awesome_nav.root`
+
+That means a file in `docs/guides/.nav.yml` can usually use short local paths like `install.md`, while a shared page can still be referenced from the root, such as `reference.md`.
+
+## Globs
+
+Globs pull in generated items without listing each one manually:
+
+```yaml
+nav:
+  - getting-started.md
+  - "*.md"
+  - "*/"
+  - "archive/**/*.md"
+```
+
+Useful patterns:
+
+- `"*.md"` matches pages in the current directory
+- `"*/"` matches child sections only
+- `"**/*.md"` matches pages recursively
+
+Recursive globs insert matches as a flat list at that position. They do not preserve nested folder structure.
+
+You can also write a glob entry explicitly:
+
+```yaml
+nav:
+  - glob: "*.md"
+```
+
+## `append_unmatched`
+
+By default, a manual `nav:` array is a complete replacement for the local generated subtree. Items you leave out stay out.
+
+Set `append_unmatched: true` when you want to hand-place a few items and then append the rest of the generated local items afterward:
+
+```yaml
+append_unmatched: true
+nav:
+  - getting-started.md
+  - guides
+```
+
+Child `.nav.yml` files inherit the nearest parent `append_unmatched` setting unless they set their own value.
+
+## `ignore`
+
+`ignore` filters generated items from:
+
+- glob matches
+- appended unmatched items
+
+It does not block a page you list explicitly in `nav:`.
+
+```yaml
+ignore:
+  - "*.hidden.md"
+  - "drafts/"
+nav:
+  - visible.md
+  - "*.md"
+```
+
+Here, `visible.md` still appears even if it also matches an ignore pattern, because it was added manually.
+
+## `sort`
+
+`sort` controls the order of generated batches only:
+
+- glob expansions
+- `append_unmatched` output
+
+Manual entries stay in the exact order you wrote them.
+
+```yaml
+sort:
+  direction: desc
+  type: natural
+  by: filename
+  sections: last
+  ignore_case: true
+nav:
+  - intro.md
+  - "*.md"
+```
+
+Supported sort fields:
+
+| Key | Values | Default |
+| --- | --- | --- |
+| `direction` | `asc`, `desc` | `asc` |
+| `type` | `alphabetical`, `natural` | `alphabetical` |
+| `by` | `path`, `filename`, `title` | `path` |
+| `sections` | `first`, `last` | `first` |
+| `ignore_case` | `true`, `false` | `true` |
+
+Per-glob sort settings are not supported. Sorting is configured once for the whole file.
+
+## `hide`
+
+Use `hide: true` in a directory's own `.nav.yml` when that subtree should disappear from navigation entirely:
+
+```yaml
+hide: true
+```
+
+When a directory is hidden:
+
+- it is skipped in generated navigation
+- manual references to that directory do not insert it
+- child `.nav.yml` files under that directory are not used
+
+## Common patterns
+
+### Curated local section
+
+```yaml
+nav:
+  - Guides Home: index.md
+  - Install: install.md
+  - Configuration: config.md
+```
+
+### Manual intro, generated remainder
+
+```yaml
+append_unmatched: true
+nav:
+  - index.md
+  - getting-started.md
+```
+
+### Rename a section and include its generated children
+
+```yaml
+nav:
+  - User Guides: guides
+```
+
+### Group links under headings
+
+```yaml
+nav:
+  - Learn:
+      - getting-started.md
+      - guides
+  - External:
+      - API Docs: https://example.com/api
+```
+
+## Notes
+
+- `.nav.yml` replaces the local subtree. It does not merge with generated items unless you opt into `append_unmatched`.
+- Duplicate items are automatically deduplicated when a manual entry and a glob point at the same generated source.
+- Paths must resolve to pages or directories already known to Jekyll under the configured root.

data/site/docs/guides/overrides.md

@@ -22,6 +22,8 @@ Use `.nav.yml` when a section needs:
 - shorter or clearer labels
 - links that do not map one-to-one with filenames
 - a curated subset of pages
+- generated batches mixed with manual items
+- hidden sections or filtered globs
 
 ## What gets replaced
 
@@ -40,3 +42,15 @@ nav:
 ```
 
 Use Markdown source paths. The plugin resolves them through Jekyll pages and then uses the final page URL.
+
+## More options
+
+`.nav.yml` also supports:
+
+- glob entries like `"*.md"` and `"*/"`
+- `append_unmatched: true` to append generated items you did not list manually
+- `ignore:` to filter generated matches
+- `sort:` to order generated batches
+- `hide: true` to remove a subtree entirely
+
+The full syntax and option reference lives in [.nav.yml Reference]({{ "/docs/guides/nav-file/" | relative_url }}).

data/site/docs/index.md

@@ -11,6 +11,7 @@ The plugin does not require collections. It reads pages under the configured `aw
 - [Getting Started]({{ "/docs/getting-started/" | relative_url }}) shows the minimum install and config.
 - [Layout Integration]({{ "/docs/guides/layouts/" | relative_url }}) shows how to render sidebars, breadcrumbs, and previous/next links.
 - [Configuration]({{ "/docs/guides/config/" | relative_url }}) explains the available plugin settings.
+- [.nav.yml Reference]({{ "/docs/guides/nav-file/" | relative_url }}) documents override syntax, options, and common patterns.
 - [Navigation Overrides]({{ "/docs/guides/overrides/" | relative_url }}) shows how local `.nav.yml` files customize sections.
 - [Generated Data]({{ "/docs/guides/data/" | relative_url }}) lists the page variables available to themes and layouts.
 
@@ -26,6 +27,7 @@ docs/
     ├── index.md
     ├── install.md
     ├── layouts.md
+    ├── nav-file.md
     ├── overrides.md
     ├── data.md
     ├── config.md

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-awesome-nav
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Allison Thackston
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-07 00:00:00.000000000 Z
+date: 2026-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -76,6 +76,7 @@ files:
 - site/docs/guides/index.md
 - site/docs/guides/install.md
 - site/docs/guides/layouts.md
+- site/docs/guides/nav-file.md
 - site/docs/guides/overrides.md
 - site/docs/index.md
 - site/index.md