jekyll-awesome-nav 0.1.4 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b77d4ad15599d518da1a7535f19fc68b945e6e16544b8198f591f94aab1bed5
-  data.tar.gz: f9c47d4e02a46679fa8e87f838ed9c2cb00d5b4d1bb0c5dfd7c4f561bc4b4366
+  metadata.gz: e774b814992c440448bfbbd49e3ac507c6e854d6c855cef20f1c8315bbfdcf2e
+  data.tar.gz: dea01e1a09990359b88048bd4ac16df166c3889803920467c8bca09d0b7e224c
 SHA512:
-  metadata.gz: 925d4fc6bc37d7243c906f480f017b96ec48f7315a1e18a42ab8b08060445ffe868ee5f592945fc1ae446e08c0fb5a68ef1079d8237ad78354f65612675ba565
-  data.tar.gz: a01bbf7f22823601fb1c6bc34e2b2ace36a69618af1ba584c2c0d3aef62fdd4ffb76715db5663b9fa6e74246e3295b8c363869c4ac3331977c52c2339d506fcd
+  metadata.gz: f1314cc3258497190ca58305f91227d79595eb1b051cfcfab6d6406d943017ca936417817dad3919219f0730d8ac91f13e8b78908121eb779cf76146426fccc5
+  data.tar.gz: 0a005443a0997e10642cf718970efc1b1b30f0b4148261d96de45acc2287e9d927b18ea147f7139f3c91a6c139683377cdc6a7d0c72e8e40ac5693584701a108

data/.copier-answers.ci.yml

@@ -1,11 +1,12 @@
 # Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
-_commit: 618054b
+_commit: v0.7.0-3-g7e5e928
 _src_path: gh:athackst/ci
-automerge_mode: poll
-bump_script_path: ''
+automerge_mode: native
 do_releases: true
 release_template: '## What''s changed
 
 
-    $CHANGES '
+    $CHANGES
+
+    '
 site_generator: none

data/.devcontainer/devcontainer.json

@@ -5,7 +5,7 @@
 	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
 	"image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04",
 	"features": {
-		"ghcr.io/devcontainers/features/ruby:1": {
+		"ghcr.io/devcontainers/features/ruby:2": {
 			"version": "3.3.4"
 		}
 	},

data/README.md

@@ -65,10 +65,10 @@ awesome_nav:
 
 Each page under the configured root receives:
 
-- `page.awesome_nav`: the full navigation tree rooted at `awesome_nav.root`
+- `page.awesome_nav`: the full navigation tree rooted at `awesome_nav.root`, annotated with `current` and `contains_current`
 - `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.breadcrumbs`: lightweight breadcrumb items with `title` and `url`
 - `page.awesome_nav_previous`: the previous linked nav item, when one exists
 - `page.awesome_nav_next`: the next linked nav item, when one exists
 

data/lib/jekyll/awesome_nav/generator.rb

@@ -46,7 +46,7 @@ module Jekyll
           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"] = deep_copy(result.annotated_tree_for(page_url))
           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)

data/lib/jekyll/awesome_nav/navigation_result.rb

@@ -14,6 +14,10 @@ module Jekyll
         @serialized_tree ||= Serializer.serialize_tree(@tree)
       end
 
+      def annotated_tree_for(page_url)
+        annotate_current(serialized_tree, Utils.normalize_url(page_url)).first
+      end
+
       def serialized_local_nav_map
         @serialized_local_nav_map ||= Serializer.serialize_map(local_nav_nodes)
       end
@@ -46,14 +50,7 @@ module Jekyll
         return root_breadcrumb(page) if trail.nil? && Utils.source_dir_for(page) == @root_dir && Utils.index_page?(page)
         return [] unless trail
 
-        breadcrumbs = trail.filter_map do |item|
-          next if item["title"].to_s.empty?
-
-          crumb = { "title" => item["title"] }
-          crumb["url"] = item["url"] if item["url"]
-          crumb["dir"] = item["__dir"] if item.key?("__dir")
-          crumb
-        end
+        breadcrumbs = trail.filter_map { |item| breadcrumb_item_for(item) }
 
         prepend_root_breadcrumb(breadcrumbs)
       end
@@ -89,14 +86,13 @@ module Jekyll
       end
 
       def root_breadcrumb(page)
-        [{ "title" => root_breadcrumb_title, "url" => Utils.normalize_url(page.url), "dir" => @root_dir }]
+        [{ "title" => root_breadcrumb_title, "url" => Utils.normalize_url(page.url) }]
       end
 
       def prepend_root_breadcrumb(breadcrumbs)
         root_crumb = {
           "title" => root_breadcrumb_title,
-          "url" => Utils.normalize_url(@root_page&.url || "/#{@root_dir}/"),
-          "dir" => @root_dir
+          "url" => Utils.normalize_url(@root_page&.url || "/#{@root_dir}/")
         }
 
         return [root_crumb] + breadcrumbs[1..] if same_breadcrumb_url?(breadcrumbs.first, root_crumb)
@@ -146,6 +142,36 @@ module Jekyll
         nil
       end
 
+      def annotate_current(items, target_url)
+        annotated_items = Array(items).map do |item|
+          annotated_children, child_contains_current = annotate_current(item["children"], target_url)
+          current = current_item?(item, target_url)
+          contains_current = child_contains_current || current
+
+          annotated_item = deep_copy(item)
+          annotated_item["current"] = current
+          annotated_item["contains_current"] = contains_current
+          annotated_item["children"] = annotated_children if annotated_item["children"].is_a?(Array)
+          annotated_item
+        end
+
+        [annotated_items, annotated_items.any? { |item| item["contains_current"] }]
+      end
+
+      def breadcrumb_item_for(item)
+        return if item["title"].to_s.empty?
+
+        crumb = { "title" => item["title"] }
+        crumb["url"] = item["url"] if item["url"]
+        crumb
+      end
+
+      def current_item?(item, target_url)
+        return false unless item["url"]
+
+        Utils.normalize_url(item["url"]) == target_url
+      end
+
       def deep_copy(value)
         Marshal.load(Marshal.dump(value))
       end

data/lib/jekyll/awesome_nav/version.rb

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

data/site/_config.yml

@@ -1,4 +1,4 @@
-theme: jekyll-theme-profile
+theme: jekyll-theme-primerpages
 title: Jekyll Awesome Nav
 description: Folder-based navigation for Jekyll with automatic generation and local subtree overrides.
 repository: PrimerPages/jekyll-awesome-nav

data/site/_includes/awesome-nav-tree.html

@@ -3,7 +3,7 @@
     {% if item.url %}
       <a
         href="{{ item.url | relative_url }}"
-        {% if item.url == page.url %}aria-current="page"{% endif %}
+        {% if item.current %}aria-current="page"{% endif %}
       >
         {{ item.title }}
       </a>

data/site/_layouts/awesome_nav_demo.html

@@ -239,6 +239,63 @@ layout: default
     margin-top: 1.25rem;
   }
 
+  .awesome-nav-demo__debug {
+    margin-top: 1.5rem;
+  }
+
+  .awesome-nav-demo__debug details {
+    border-radius: 1.25rem;
+    overflow: hidden;
+  }
+
+  .awesome-nav-demo__debug summary {
+    align-items: center;
+    cursor: pointer;
+    display: flex;
+    font-weight: 800;
+    gap: 0.75rem;
+    justify-content: space-between;
+    list-style: none;
+    padding: 1rem 1.15rem;
+  }
+
+  .awesome-nav-demo__debug summary::-webkit-details-marker {
+    display: none;
+  }
+
+  .awesome-nav-demo__debug-summary-copy {
+    font-size: 0.82rem;
+    font-weight: 600;
+    opacity: 0.82;
+  }
+
+  .awesome-nav-demo__debug-grid {
+    display: grid;
+    gap: 1rem;
+    grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr));
+    padding: 0 1rem 1rem;
+  }
+
+  .awesome-nav-demo__debug-card {
+    border-radius: 1rem;
+    min-width: 0;
+    padding: 0.9rem;
+  }
+
+  .awesome-nav-demo__debug-card h2 {
+    font-size: 0.95rem;
+    margin: 0 0 0.65rem;
+  }
+
+  .awesome-nav-demo__debug-card pre {
+    font-size: 0.78rem;
+    line-height: 1.5;
+    margin: 0;
+    overflow: auto;
+    white-space: pre-wrap;
+    word-break: break-word;
+  }
+
   .awesome-nav-demo__pager a {
     border-radius: 1.25rem;
     display: flex;
@@ -342,7 +399,11 @@ layout: default
             <ol>
               {% for item in page.breadcrumbs %}
                 <li>
-                  <a href="{{ item.url | relative_url }}">{{ item.title }}</a>
+                  {% if item.url %}
+                    <a href="{{ item.url | relative_url }}">{{ item.title }}</a>
+                  {% else %}
+                    <span>{{ item.title }}</span>
+                  {% endif %}
                 </li>
               {% endfor %}
             </ol>
@@ -365,6 +426,47 @@ layout: default
         {{ content | inject_anchors }}
       </article>
 
+      <section class="awesome-nav-demo__debug" aria-label="Plugin debug data">
+        <details>
+          <summary>
+            <span>Plugin data</span>
+            <span class="awesome-nav-demo__debug-summary-copy">Resolved page variables for this page</span>
+          </summary>
+
+          <div class="awesome-nav-demo__debug-grid">
+            <section class="awesome-nav-demo__debug-card">
+              <h2><code>page.breadcrumbs</code></h2>
+              <pre>{{ page.breadcrumbs | jsonify }}</pre>
+            </section>
+
+            <section class="awesome-nav-demo__debug-card">
+              <h2><code>page.awesome_nav</code></h2>
+              <pre>{{ page.awesome_nav | jsonify }}</pre>
+            </section>
+
+            <section class="awesome-nav-demo__debug-card">
+              <h2><code>page.awesome_nav_local</code></h2>
+              <pre>{{ page.awesome_nav_local | jsonify }}</pre>
+            </section>
+
+            <section class="awesome-nav-demo__debug-card">
+              <h2><code>page.awesome_nav_dir</code></h2>
+              <pre>{{ page.awesome_nav_dir | jsonify }}</pre>
+            </section>
+
+            <section class="awesome-nav-demo__debug-card">
+              <h2><code>page.awesome_nav_previous</code></h2>
+              <pre>{{ page.awesome_nav_previous | jsonify }}</pre>
+            </section>
+
+            <section class="awesome-nav-demo__debug-card">
+              <h2><code>page.awesome_nav_next</code></h2>
+              <pre>{{ page.awesome_nav_next | jsonify }}</pre>
+            </section>
+          </div>
+        </details>
+      </section>
+
       {% if previous_item or next_item %}
         <nav class="awesome-nav-demo__pager" aria-label="Pagination">
           {% if previous_item %}

data/site/docs/.nav.yml

@@ -0,0 +1,7 @@
+nav:
+  - Getting Started: getting-started.md
+  - guides
+  - Examples:
+    - Examples Home: examples/index.md
+    - Basic Folder Navigation: examples/basic-folder-navigation.md
+    - Local Override: examples/local-override.md

data/site/docs/examples/basic-folder-navigation.md

@@ -0,0 +1,26 @@
+---
+title: Basic Folder Navigation
+---
+
+Use plain folders and pages when you want navigation to come directly from the docs tree.
+
+```text
+docs/
+├── index.md
+├── getting-started.md
+└── guides/
+    ├── index.md
+    ├── install.md
+    └── config.md
+```
+
+With no `.nav.yml` files, the plugin turns that structure into sections and pages automatically.
+
+```yaml
+awesome_nav:
+  enabled: true
+  root: docs
+  nav_filename: .nav.yml
+```
+
+This is a good default when the filesystem already reflects the order and grouping you want.

data/site/docs/examples/index.md

@@ -0,0 +1,10 @@
+---
+title: Examples
+---
+
+These examples show common ways to use `jekyll-awesome-nav` in a docs folder.
+
+## Examples
+
+- [Basic Folder Navigation]({{ "/docs/examples/basic-folder-navigation/" | relative_url }}) shows navigation generated from folders and pages.
+- [Local Override]({{ "/docs/examples/local-override/" | relative_url }}) shows a folder-level `.nav.yml` file with curated labels and order.

data/site/docs/examples/local-override.md

@@ -0,0 +1,25 @@
+---
+title: Local Override Example
+---
+
+Add a `.nav.yml` file when one folder needs a curated order or friendlier labels.
+
+```text
+docs/
+└── guides/
+    ├── .nav.yml
+    ├── index.md
+    ├── install.md
+    └── config.md
+```
+
+Example override:
+
+```yaml
+nav:
+  - Guides Home: index.md
+  - Install Guide: install.md
+  - Configuration: config.md
+```
+
+That file replaces the generated navigation for `docs/guides/` only. The rest of the docs tree still uses normal folder-based generation.

data/site/docs/guides/data.md

@@ -8,10 +8,10 @@ The plugin writes navigation data onto each page under the configured docs root.
 
 | Variable | Description |
 | --- | --- |
-| `page.awesome_nav` | Full resolved docs tree. |
+| `page.awesome_nav` | Full resolved docs tree with `current` and `contains_current` state for rendering. |
 | `page.awesome_nav_local` | Navigation items for the current directory context. |
 | `page.awesome_nav_dir` | Directory that supplied the current local nav context. |
-| `page.breadcrumbs` | Breadcrumb entries for the current page. |
+| `page.breadcrumbs` | Lightweight breadcrumb entries for the current page. |
 | `page.awesome_nav_previous` | Previous page in the resolved navigation order. |
 | `page.awesome_nav_next` | Next page in the resolved navigation order. |
 
@@ -19,16 +19,25 @@ For README-indexed directories, these values are computed using the directory in
 
 ## Tree item shape
 
-Navigation entries are hashes with a title, URL, and optional children:
+Navigation entries are hashes with a title, URL, optional children, and current-state flags:
 
 ```yaml
 title: Install Guide
 url: /docs/guides/install/
+current: true
+contains_current: true
 children: []
 ```
 
 Layouts should treat `children` as optional because leaf pages do not need nested items.
 
+Breadcrumb items stay lightweight. Linked entries include `url`; grouping entries may only include `title`:
+
+```yaml
+title: Install Guide
+url: /docs/guides/install/
+```
+
 ## Site variables
 
 The plugin also writes resolved data into `site.config` for advanced theme use:

data/site/docs/guides/layouts.md

@@ -37,7 +37,13 @@ The plugin writes breadcrumbs to `page.breadcrumbs`.
 <nav aria-label="Breadcrumbs">
   <ol>
     {% for item in page.breadcrumbs %}
-      <li><a href="{{ item.url | relative_url }}">{{ item.title }}</a></li>
+      <li>
+        {% if item.url %}
+          <a href="{{ item.url | relative_url }}">{{ item.title }}</a>
+        {% else %}
+          <span>{{ item.title }}</span>
+        {% endif %}
+      </li>
     {% endfor %}
   </ol>
 </nav>
@@ -46,14 +52,17 @@ The plugin writes breadcrumbs to `page.breadcrumbs`.
 
 ## Render a sidebar
 
-Use `page.awesome_nav` for the full docs tree:
+Use `page.awesome_nav` for the full docs tree. Each item includes `current` for the exact page match and `contains_current` for the active branch:
 
 ```liquid
 {% raw %}<nav aria-label="Documentation">
   <ul>
     {% for item in page.awesome_nav %}
       <li>
-        <a href="{{ item.url | relative_url }}">{{ item.title }}</a>
+        <a href="{{ item.url | relative_url }}"{% if item.current %} aria-current="page"{% endif %}>{{ item.title }}</a>
+        {% if item.contains_current %}
+          <span class="visually-hidden">(current section)</span>
+        {% endif %}
         {% if item.children %}
           <ul>
             {% for child in item.children %}

data/site/docs/index.md

@@ -9,6 +9,7 @@ The plugin does not require collections. It reads pages under the configured `aw
 ## Start here
 
 - [Getting Started]({{ "/docs/getting-started/" | relative_url }}) shows the minimum install and config.
+- [Examples]({{ "/docs/examples/" | relative_url }}) shows a few concrete folder and `.nav.yml` setups.
 - [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.
@@ -22,6 +23,10 @@ This documentation site uses a plain `docs/` folder:
 ```text
 docs/
 ├── index.md
+├── examples/
+│   ├── index.md
+│   ├── basic-folder-navigation.md
+│   └── local-override.md
 ├── getting-started.md
 └── guides/
     ├── index.md

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-awesome-nav
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.1
 platform: ruby
 authors:
 - Allison Thackston
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-19 00:00:00.000000000 Z
+date: 2026-07-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -69,6 +69,10 @@ files:
 - site/_config.yml
 - site/_includes/awesome-nav-tree.html
 - site/_layouts/awesome_nav_demo.html
+- site/docs/.nav.yml
+- site/docs/examples/basic-folder-navigation.md
+- site/docs/examples/index.md
+- site/docs/examples/local-override.md
 - site/docs/getting-started.md
 - site/docs/guides/.nav.yml
 - site/docs/guides/config.md