jekyll-awesome-nav 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92223e2c3e03f661381ed950b514da942c9ce18ddc97b5a51e1ffd3536971efa
-  data.tar.gz: a12d8cc9e0500e4deb65803b8ad1bd94cfa88f291b452f21edceb9fd16016c32
+  metadata.gz: 2cfc859de2a4762ba5046338aa7bc12049da70bfb2d9ac27d727eace95322f11
+  data.tar.gz: 0f14a593b81ec5882b65db61b82e93d8bd8f9a3656a8d730cd0f4175a2da65e3
 SHA512:
-  metadata.gz: e9fdc037fed9c4fa24186e83047cb98a6ed0bd36e313163d9cc6b8ae87b02bfe07225e6bd1180c502ab437c0764242c78de8ae5bcef5558d29ad2ede34951f88
-  data.tar.gz: 0f973ac341990dc4dfebb041621e8e90e8ab3650d3ea701a4e87bcf8e94a276d360a44af9699306d768cb64810ef1fa74a9a67f8bbcb7716894d82894664b2f2
+  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: 467877a
+_commit: afa589e
 _src_path: gh:athackst/ci
 automerge_mode: poll
 bump_script_path: ''

data/lib/jekyll/awesome_nav/nav_resolver.rb

@@ -75,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)
@@ -415,7 +418,9 @@ module Jekyll
 
         normalized = Utils.normalize_dir(candidate)
         root_index_path = Utils.normalize_dir(File.join(@root_dir, "index.md"))
-        return nil unless [@root_dir, root_index_path, "index.md"].include?(normalized)
+        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,

data/lib/jekyll/awesome_nav/version.rb

@@ -2,7 +2,7 @@
 
 module Jekyll
   module AwesomeNav
-    VERSION = "0.1.1"
+    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.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Allison Thackston
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-11 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