jekyll-awesome-nav 0.0.1

data/site/docs/guides/install.md

@@ -0,0 +1,53 @@
+---
+title: Install
+---
+
+This page appears under the overridden guides subtree.
+
+## Gemfile
+
+Add the plugin to your site's `Gemfile`:
+
+```ruby
+gem "jekyll-awesome-nav"
+```
+
+If you use a `:jekyll_plugins` group, it is fine to place it there:
+
+```ruby
+group :jekyll_plugins do
+  gem "jekyll-awesome-nav"
+end
+```
+
+## Jekyll config
+
+Add the plugin to `_config.yml`:
+
+```yaml
+plugins:
+  - jekyll-awesome-nav
+```
+
+Then configure the docs root:
+
+```yaml
+awesome_nav:
+  enabled: true
+  root: docs
+  nav_filename: .nav.yml
+```
+
+## Layout default
+
+Set a layout for the docs folder so every generated page receives the same navigation UI:
+
+```yaml
+defaults:
+  - scope:
+      path: "docs"
+    values:
+      layout: docs
+```
+
+The plugin generates the data. The layout decides how that data looks.

data/site/docs/guides/layouts.md

@@ -0,0 +1,116 @@
+---
+title: Layout Integration
+---
+
+`jekyll-awesome-nav` generates navigation data. Your layout renders it.
+
+This site uses its own small layout at `site/_layouts/docs.html`, with a recursive include at `site/_includes/awesome-nav-tree.html`.
+
+You can use those files as a starting point when wiring the same data into another Jekyll theme.
+
+## Enable a docs layout
+
+Set a layout for every page under your docs root:
+
+```yaml
+defaults:
+  - scope:
+      path: "docs"
+    values:
+      layout: docs
+```
+
+Inside that layout, check for generated navigation before rendering plugin-specific UI:
+
+```liquid
+{% raw %}{% if page.awesome_nav %}
+  <!-- Render awesome nav UI -->
+{% endif %}{% endraw %}
+```
+
+## Render breadcrumbs
+
+The plugin writes breadcrumbs to `page.breadcrumbs`.
+
+```liquid
+{% raw %}{% if page.breadcrumbs %}
+<nav aria-label="Breadcrumbs">
+  <ol>
+    {% for item in page.breadcrumbs %}
+      <li><a href="{{ item.url | relative_url }}">{{ item.title }}</a></li>
+    {% endfor %}
+  </ol>
+</nav>
+{% endif %}{% endraw %}
+```
+
+## Render a sidebar
+
+Use `page.awesome_nav` for the full docs tree:
+
+```liquid
+{% raw %}<nav aria-label="Documentation">
+  <ul>
+    {% for item in page.awesome_nav %}
+      <li>
+        <a href="{{ item.url | relative_url }}">{{ item.title }}</a>
+        {% if item.children %}
+          <ul>
+            {% for child in item.children %}
+              <li><a href="{{ child.url | relative_url }}">{{ child.title }}</a></li>
+            {% endfor %}
+          </ul>
+        {% endif %}
+      </li>
+    {% endfor %}
+  </ul>
+</nav>{% endraw %}
+```
+
+For deeply nested docs, move the recursive portion into an include and call it for each `children` collection.
+
+## Render the current section
+
+Use `page.awesome_nav_local` when you want a compact menu for the current directory:
+
+```liquid
+{% raw %}{% if page.awesome_nav_local %}
+<nav aria-label="This section">
+  <ul>
+    {% for item in page.awesome_nav_local %}
+      <li><a href="{{ item.url | relative_url }}">{{ item.title }}</a></li>
+    {% endfor %}
+  </ul>
+</nav>
+{% endif %}{% endraw %}
+```
+
+## Render previous and next links
+
+The plugin calculates previous and next pages from the final resolved tree, including local `.nav.yml` overrides.
+
+```liquid
+{% raw %}<nav aria-label="Pagination">
+  {% if page.awesome_nav_previous %}
+    <a href="{{ page.awesome_nav_previous.url | relative_url }}">
+      Previous: {{ page.awesome_nav_previous.title }}
+    </a>
+  {% endif %}
+
+  {% if page.awesome_nav_next %}
+    <a href="{{ page.awesome_nav_next.url | relative_url }}">
+      Next: {{ page.awesome_nav_next.title }}
+    </a>
+  {% endif %}
+</nav>{% endraw %}
+```
+
+## Theme includes
+
+If you maintain a theme, a clean pattern is:
+
+- one include for breadcrumbs
+- one recursive include for tree rendering
+- one layout that chooses full-tree or local-section navigation
+
+That keeps the plugin data plain and lets the theme own the HTML and CSS.

data/site/docs/guides/overrides.md

@@ -0,0 +1,42 @@
+---
+title: Navigation Overrides
+---
+
+By default, the plugin builds navigation from files and folders. A local `.nav.yml` lets a folder replace its own subtree.
+
+This demo has an override at `docs/guides/.nav.yml`:
+
+```yaml
+nav:
+  - Guides Hub: index.md
+  - Install Guide: install.md
+  - Layout Integration: layouts.md
+  - Configuration: config.md
+```
+
+## When to use an override
+
+Use `.nav.yml` when a section needs:
+
+- a custom order
+- shorter or clearer labels
+- links that do not map one-to-one with filenames
+- a curated subset of pages
+
+## What gets replaced
+
+An override replaces the subtree for the directory where it appears. Other directories still use generated navigation.
+
+For example, `docs/guides/.nav.yml` controls the guides section only. The root `docs/` tree is still generated from the folder structure and then uses the guides override for that branch.
+
+## Link format
+
+Each item uses a `Title: path.md` entry. Nested sections use a list:
+
+```yaml
+nav:
+  - Section:
+      - Page: section/page.md
+```
+
+Use Markdown source paths. The plugin resolves them through Jekyll pages and then uses the final page URL.

data/site/docs/index.md

@@ -0,0 +1,35 @@
+---
+title: Documentation
+---
+
+These docs show how `jekyll-awesome-nav` turns a normal folder of Markdown files into navigation data your layouts can render.
+
+The plugin does not require collections. It reads pages under the configured `awesome_nav.root`, builds a tree, and writes the result onto each docs page.
+
+## Start here
+
+- [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.
+- [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.
+
+## Folder shape
+
+This documentation site uses a plain `docs/` folder:
+
+```text
+docs/
+├── index.md
+├── getting-started.md
+└── guides/
+    ├── index.md
+    ├── install.md
+    ├── layouts.md
+    ├── overrides.md
+    ├── data.md
+    ├── config.md
+    └── .nav.yml
+```
+
+Pages are included in the generated tree when they live under `awesome_nav.root`. A folder can provide an `index.md` page to represent the section itself.

data/site/index.md

@@ -0,0 +1,66 @@
+---
+layout: profile
+title: Jekyll Awesome Nav
+permalink: /
+links:
+  - name: Browse the docs
+    url: /docs/
+    octicon: file
+  - name: Install the gem
+    url: /docs/getting-started/
+    octicon: package
+  - name: View the source
+    url: https://github.com/PrimerPages/jekyll-awesome-nav
+    octicon: mark-github
+  - name: Read the README
+    url: https://github.com/PrimerPages/jekyll-awesome-nav/blob/main/README.md
+    octicon: book
+---
+
+# Folder-based docs navigation for Jekyll
+
+`jekyll-awesome-nav` builds a full navigation tree from your docs folder and lets any directory replace its own subtree with a local `.nav.yml` file.
+
+It is designed for documentation sites that want sensible defaults from folder structure, while still giving authors precise local control when a section needs a custom order or grouping.
+
+## What it does
+
+- Builds navigation from `site.pages` under one configured root such as `docs/`
+- Uses `index.md` as the section title and section URL
+- Exposes the full tree on every page as `page.awesome_nav`
+- Exposes the current directory subtree as `page.awesome_nav_local`
+- Computes breadcrumbs from the final resolved tree
+- Replaces a directory subtree entirely when `.nav.yml` is present
+
+## Quick start
+
+Add the gem to your site:
+
+```ruby
+gem "jekyll-awesome-nav"
+```
+
+Enable it in `_config.yml`:
+
+```yaml
+plugins:
+  - jekyll-awesome-nav
+
+awesome_nav:
+  enabled: true
+  root: docs
+  nav_filename: .nav.yml
+```
+
+Then create docs pages under `docs/`. If you want a section to use a custom structure, add a local `.nav.yml` in that folder.
+
+## This site
+
+This site is the plugin documentation source. The docs section demonstrates:
+
+- automatically generated navigation
+- a local `.nav.yml` override in `docs/guides/`
+- glob expansion and generated-batch options
+- breadcrumb generation
+- per-page `awesome_nav` data for theme rendering
+ 

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-awesome-nav
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Allison Thackston
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-05-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Build a full navigation tree from a docs directory and let any folder
+  replace its subtree with a local _nav.yml file.
+email:
+- allison@allisonthackston.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".copier-answers.ci.yml"
+- ".devcontainer/devcontainer.json"
+- ".devcontainer/post-create.sh"
+- ".rubocop.yml"
+- ".ruby-version"
+- ".vscode/tasks.json"
+- AGENTS.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- jekyll-awesome-nav.gemspec
+- lib/jekyll-awesome-nav.rb
+- lib/jekyll/awesome_nav.rb
+- lib/jekyll/awesome_nav/config.rb
+- lib/jekyll/awesome_nav/generator.rb
+- lib/jekyll/awesome_nav/nav_file.rb
+- lib/jekyll/awesome_nav/nav_file_loader.rb
+- lib/jekyll/awesome_nav/nav_file_options.rb
+- lib/jekyll/awesome_nav/nav_resolver.rb
+- lib/jekyll/awesome_nav/navigation_result.rb
+- lib/jekyll/awesome_nav/node.rb
+- lib/jekyll/awesome_nav/page_set.rb
+- lib/jekyll/awesome_nav/serializer.rb
+- lib/jekyll/awesome_nav/sort_options.rb
+- lib/jekyll/awesome_nav/tree_builder.rb
+- lib/jekyll/awesome_nav/utils.rb
+- lib/jekyll/awesome_nav/version.rb
+- site/_config.yml
+- site/_includes/awesome-nav-demo-tree.html
+- site/_includes/awesome-nav-tree.html
+- site/_layouts/awesome_nav_demo.html
+- site/docs/getting-started.md
+- site/docs/guides/.nav.yml
+- site/docs/guides/config.md
+- site/docs/guides/data.md
+- site/docs/guides/index.md
+- site/docs/guides/install.md
+- site/docs/guides/layouts.md
+- site/docs/guides/overrides.md
+- site/docs/index.md
+- site/index.md
+homepage: https://github.com/PrimerPages/jekyll-awesome-nav
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/PrimerPages/jekyll-awesome-nav
+  source_code_uri: https://github.com/PrimerPages/jekyll-awesome-nav
+  bug_tracker_uri: https://github.com/PrimerPages/jekyll-awesome-nav/issues
+  documentation_uri: https://primerpages.github.io/jekyll-awesome-nav/
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Folder-based navigation for Jekyll with local subtree overrides.
+test_files: []