jekyll-awesome-nav 0.0.1

data/lib/jekyll/awesome_nav/sort_options.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module AwesomeNav
+    class SortOptions
+      DEFAULTS = {
+        "direction" => "asc",
+        "type" => "alphabetical",
+        "by" => "path",
+        "sections" => "first",
+        "ignore_case" => true
+      }.freeze
+
+      def self.from(value)
+        new(value)
+      end
+
+      def initialize(value)
+        raise Error, "sort must be a mapping" unless value.nil? || value.is_a?(Hash)
+
+        @data = DEFAULTS.merge(value || {})
+      end
+
+      def sort(items)
+        sorted = Array(items).sort_by { |item| sort_key(item) }
+        direction == "desc" ? sorted.reverse : sorted
+      end
+
+      private
+
+      def sort_key(item)
+        [
+          section_rank(item),
+          value_key(value_for(item))
+        ]
+      end
+
+      def section_rank(item)
+        case sections
+        when "first"
+          item.section? ? 0 : 1
+        when "last"
+          item.section? ? 1 : 0
+        else
+          0
+        end
+      end
+
+      def value_key(value)
+        value = value.to_s
+        value = value.downcase if ignore_case?
+        type == "natural" ? natural_key(value) : value
+      end
+
+      def natural_key(value)
+        value.split(/(\d+)/).map { |part| part.match?(/\A\d+\z/) ? part.to_i : part }
+      end
+
+      def value_for(item)
+        case by
+        when "filename"
+          item.filename || File.basename(item.path.to_s)
+        when "title"
+          item.title
+        else
+          item.path || item.dir || item.title
+        end
+      end
+
+      def direction
+        @data["direction"].to_s
+      end
+
+      def type
+        @data["type"].to_s
+      end
+
+      def by
+        @data["by"].to_s
+      end
+
+      def sections
+        @data["sections"].to_s
+      end
+
+      def ignore_case?
+        @data["ignore_case"] != false
+      end
+    end
+  end
+end

data/lib/jekyll/awesome_nav/tree_builder.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module AwesomeNav
+    class TreeBuilder
+      def initialize(pages:, root_dir:)
+        @pages = pages
+        @root_dir = root_dir
+      end
+
+      def build
+        root = Node.section(dir: @root_dir)
+        @pages.each { |page| add_page(root, page) }
+        root.children.sort_by! { |child| sort_key(child) }
+        sort_sections(root.children)
+      end
+
+      private
+
+      def add_page(root, page)
+        page_path = Utils.source_path_for(page)
+        dir = Utils.source_dir_for(page)
+        relative_dir = Utils.relative_to_root(dir, @root_dir)
+        current = root
+        current_dir = @root_dir
+
+        Utils.path_segments(relative_dir).each do |segment|
+          current_dir = [current_dir, segment].reject(&:empty?).join("/")
+          child = current.children.find { |node| node.section? && Utils.last_segment(node.dir) == segment }
+          unless child
+            child = Node.section(dir: current_dir, title: Utils.titleize(segment))
+            current.children << child
+          end
+          current = child
+        end
+
+        basename = File.basename(page.path, File.extname(page.path))
+        title = Utils.page_title(page, basename)
+        url = Utils.normalize_url(page.url)
+
+        if basename == "index"
+          current.title = title
+          current.url = url
+          current.path = page_path
+          current.filename = File.basename(page_path)
+        else
+          current.children << Node.page(
+            dir: [dir, basename].reject(&:empty?).join("/"),
+            title: title,
+            url: url,
+            path: page_path,
+            filename: File.basename(page_path)
+          )
+        end
+      end
+
+      def sort_sections(items)
+        items.each do |child|
+          next unless child.section?
+
+          child.children.sort_by! { |nested| sort_key(nested) }
+          sort_sections(child.children)
+        end
+      end
+
+      def sort_key(child)
+        [
+          child.section? ? 0 : 1,
+          child.path.to_s.downcase,
+          child.title.to_s.downcase
+        ]
+      end
+    end
+  end
+end

data/lib/jekyll/awesome_nav/utils.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module AwesomeNav
+    module Utils
+      module_function
+
+      def normalize_dir(dir)
+        dir.to_s.strip.sub(%r{\A/+}, "").sub(%r{/+\z}, "")
+      end
+
+      def path_segments(dir)
+        normalize_dir(dir).split("/").reject(&:empty?)
+      end
+
+      def parent_dir(dir)
+        segments = path_segments(dir)
+        return "" if segments.length <= 1
+
+        segments[0...-1].join("/")
+      end
+
+      def last_segment(path)
+        path_segments(path).last.to_s
+      end
+
+      def relative_to_root(dir, root_dir)
+        return "" if dir == root_dir
+        return dir.delete_prefix("#{root_dir}/") if dir.start_with?("#{root_dir}/")
+
+        dir
+      end
+
+      def relative_dir(source, absolute_dir)
+        absolute_dir
+          .sub(%r{\A#{Regexp.escape(source)}/?}, "")
+          .sub(%r{\A/+}, "")
+          .sub(%r{/+\z}, "")
+      end
+
+      def external_url?(value)
+        value.to_s.match?(%r{\A([a-z][a-z0-9+\-.]*:)?//}i)
+      end
+
+      def normalize_url(url)
+        value = url.to_s.strip
+        return "/" if value.empty?
+        return value if external_url?(value)
+
+        value = "/#{value}" unless value.start_with?("/")
+        value = value.sub(/index\.html\z/, "")
+        value = value.gsub(%r{/+}, "/")
+        value = "#{value}/" if File.extname(value).empty? && !value.end_with?("/")
+        value
+      end
+
+      def titleize(value)
+        value.to_s
+             .tr("_-", " ")
+             .split
+             .map { |part| part[0] ? "#{part[0].upcase}#{part[1..]}" : part }
+             .join(" ")
+      end
+
+      def index_page?(page)
+        File.basename(page.path, File.extname(page.path)) == "index"
+      end
+
+      def source_dir_for(page)
+        source_dir_for_path(source_path_for(page))
+      end
+
+      def source_dir_for_path(path)
+        dir = File.dirname(path.to_s)
+        normalize_dir(dir == "." ? "" : dir)
+      end
+
+      def source_path_for(page)
+        path =
+          if page.respond_to?(:relative_path) && !page.relative_path.nil?
+            page.relative_path
+          else
+            page.path
+          end
+
+        normalize_dir(path)
+      end
+
+      def page_title(page, basename)
+        page.data["nav_title"] || page.data["title"] || titleize(basename)
+      end
+    end
+  end
+end

data/lib/jekyll/awesome_nav/version.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module AwesomeNav
+    VERSION = "0.0.1"
+
+    def self.warn_if_unstamped_version(output = $stderr)
+      return unless VERSION == "0.0.0"
+      return if @unstamped_version_warning_emitted
+
+      output.puts(
+        "Warning: jekyll-awesome-nav is using unstamped source version 0.0.0. " \
+        "Release builds should stamp lib/jekyll/awesome_nav/version.rb before packaging."
+      )
+      @unstamped_version_warning_emitted = true
+    end
+    private_class_method :warn_if_unstamped_version
+  end
+end

data/lib/jekyll/awesome_nav.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "jekyll"
+
+require_relative "awesome_nav/utils"
+require_relative "awesome_nav/config"
+require_relative "awesome_nav/node"
+require_relative "awesome_nav/sort_options"
+require_relative "awesome_nav/nav_file_options"
+require_relative "awesome_nav/nav_file"
+require_relative "awesome_nav/page_set"
+require_relative "awesome_nav/tree_builder"
+require_relative "awesome_nav/nav_file_loader"
+require_relative "awesome_nav/nav_resolver"
+require_relative "awesome_nav/serializer"
+require_relative "awesome_nav/navigation_result"
+require_relative "awesome_nav/version"
+require_relative "awesome_nav/generator"
+
+module Jekyll
+  module AwesomeNav
+    class Error < StandardError; end
+  end
+end
+
+Jekyll::AwesomeNav.send(:warn_if_unstamped_version)

data/lib/jekyll-awesome-nav.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "jekyll/awesome_nav"

data/site/_config.yml

@@ -0,0 +1,33 @@
+theme: jekyll-theme-profile
+title: Jekyll Awesome Nav
+description: Folder-based navigation for Jekyll with automatic generation and local subtree overrides.
+repository: PrimerPages/jekyll-awesome-nav
+permalink: pretty
+style: appbar
+repo_info: true
+user_metadata: false
+profile_link: false
+nav:
+  - name: Overview
+    url: /
+  - name: Docs Home
+    url: /docs/
+  - name: Getting Started
+    url: /docs/getting-started/
+plugins:
+  - jekyll-seo-tag
+  - jekyll-awesome-nav
+awesome_nav:
+  enabled: true
+  root: docs
+  nav_filename: .nav.yml
+markdown: kramdown
+defaults:
+  - scope:
+      path: ""
+    values:
+      layout: page
+  - scope:
+      path: "docs"
+    values:
+      layout: docs

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

@@ -0,0 +1,15 @@
+{% for item in include.items %}
+  <li>
+    <a
+      href="{{ item.url | relative_url }}"
+      {% if item.url == page.url %}aria-current="page"{% endif %}
+    >
+      {{ item.title }}
+    </a>
+    {% if item.children %}
+      <ul>
+        {% include awesome-nav-demo-tree.html items=item.children %}
+      </ul>
+    {% endif %}
+  </li>
+{% endfor %}

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

@@ -0,0 +1,19 @@
+{% for item in include.items %}
+  <li>
+    {% if item.url %}
+      <a
+        href="{{ item.url | relative_url }}"
+        {% if item.url == page.url %}aria-current="page"{% endif %}
+      >
+        {{ item.title }}
+      </a>
+    {% else %}
+      <span>{{ item.title }}</span>
+    {% endif %}
+    {% if item.children %}
+      <ul>
+        {% include awesome-nav-tree.html items=item.children %}
+      </ul>
+    {% endif %}
+  </li>
+{% endfor %}

data/site/_layouts/awesome_nav_demo.html

@@ -0,0 +1,128 @@
+---
+layout: default
+---
+<style>
+  .awesome-nav-docs {
+    display: grid;
+    gap: 2rem;
+    grid-template-columns: minmax(14rem, 18rem) minmax(0, 1fr);
+    max-width: 72rem;
+    margin: 0 auto;
+    padding: 2rem 1rem;
+  }
+
+  .awesome-nav-docs__sidebar {
+    align-self: start;
+    position: sticky;
+    top: 1rem;
+  }
+
+  .awesome-nav-docs__sidebar ul {
+    list-style: none;
+    margin: 0;
+    padding-left: 0;
+  }
+
+  .awesome-nav-docs__sidebar ul ul {
+    margin-top: 0.25rem;
+    padding-left: 1rem;
+  }
+
+  .awesome-nav-docs__sidebar li {
+    margin: 0.25rem 0;
+  }
+
+  .awesome-nav-docs__sidebar a,
+  .awesome-nav-docs__sidebar span {
+    display: block;
+    padding: 0.25rem 0;
+  }
+
+  .awesome-nav-docs__sidebar a[aria-current="page"] {
+    font-weight: 700;
+  }
+
+  .awesome-nav-docs__breadcrumbs ol {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.25rem;
+    list-style: none;
+    margin: 0 0 1rem;
+    padding: 0;
+  }
+
+  .awesome-nav-docs__breadcrumbs li {
+    margin: 0.25rem;
+  }
+
+  .awesome-nav-docs__breadcrumbs li:not(:last-child)::after {
+    content: "/";
+    margin-left: 0.25rem;
+  }
+
+  .awesome-nav-docs__pager {
+    border-top: 1px solid var(--borderColor-default, #d0d7de);
+    display: flex;
+    justify-content: space-between;
+    gap: 1rem;
+    margin-top: 3rem;
+    padding-top: 1rem;
+  }
+
+  @media (max-width: 48rem) {
+    .awesome-nav-docs {
+      grid-template-columns: 1fr;
+    }
+
+    .awesome-nav-docs__sidebar {
+      position: static;
+    }
+  }
+</style>
+
+<div class="awesome-nav-docs">
+  <aside class="awesome-nav-docs__sidebar">
+    <h2>Docs</h2>
+    {% if page.awesome_nav %}
+      <nav aria-label="Documentation">
+        <ul>
+          {% include awesome-nav-tree.html items=page.awesome_nav %}
+        </ul>
+      </nav>
+    {% endif %}
+  </aside>
+
+  <main class="markdown-body">
+    {% if page.breadcrumbs %}
+      <nav class="awesome-nav-docs__breadcrumbs" aria-label="Breadcrumbs">
+        <ol>
+          {% for item in page.breadcrumbs %}
+            <li>
+              <a href="{{ item.url | relative_url }}">{{ item.title }}</a>
+            </li>
+          {% endfor %}
+        </ol>
+      </nav>
+    {% endif %}
+
+    <h1>{{ page.title }}</h1>
+    {{ content }}
+
+    <nav class="awesome-nav-docs__pager" aria-label="Pagination">
+      <div>
+        {% if page.awesome_nav_previous %}
+          <a href="{{ page.awesome_nav_previous.url | relative_url }}">
+            Previous: {{ page.awesome_nav_previous.title }}
+          </a>
+        {% endif %}
+      </div>
+      <div>
+        {% if page.awesome_nav_next %}
+          <a href="{{ page.awesome_nav_next.url | relative_url }}">
+            Next: {{ page.awesome_nav_next.title }}
+          </a>
+        {% endif %}
+      </div>
+    </nav>
+  </main>
+</div>

data/site/docs/getting-started.md

@@ -0,0 +1,68 @@
+---
+title: Getting Started
+---
+
+Add the gem to your Jekyll site and enable it in `_config.yml`.
+
+## Install the gem
+
+```ruby
+gem "jekyll-awesome-nav"
+```
+
+Then install your bundle:
+
+```bash
+bundle install
+```
+
+## Enable the plugin
+
+```yaml
+plugins:
+  - jekyll-awesome-nav
+
+awesome_nav:
+  enabled: true
+  root: docs
+  nav_filename: .nav.yml
+```
+
+## Add docs pages
+
+Create Markdown files under the configured root:
+
+```text
+docs/
+├── index.md
+├── getting-started.md
+└── guides/
+    ├── index.md
+    └── install.md
+```
+
+Each page should have a title:
+
+```markdown
+---
+title: Install
+---
+
+Install instructions go here.
+```
+
+The plugin builds navigation from these pages during the normal Jekyll build. Your layout can then render `page.awesome_nav`, `page.breadcrumbs`, and the previous/next links.
+
+## Render it
+
+If your theme already supports `jekyll-awesome-nav`, choose that docs layout for pages under your docs root. This site uses its docs layout through defaults:
+
+```yaml
+defaults:
+  - scope:
+      path: "docs"
+    values:
+      layout: docs
+```
+
+If your theme does not support it yet, use the examples in [Layout Integration]({{ "/docs/guides/layouts/" | relative_url }}) to wire the data into your own layout.

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

@@ -0,0 +1,7 @@
+nav:
+  - Guides:
+      - Install Guide: install.md
+      - Layout Integration: layouts.md
+      - Configuration: config.md
+      - Navigation Overrides: overrides.md
+      - Generated Data: data.md

data/site/docs/guides/config.md

@@ -0,0 +1,37 @@
+---
+title: Configuration
+---
+
+Configure the plugin in `_config.yml`.
+
+```yaml
+awesome_nav:
+  enabled: true
+  root: docs
+  nav_filename: .nav.yml
+```
+
+## Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `enabled` | `true` | Turns generation on or off. |
+| `root` | `docs` | Folder that contains your documentation pages. |
+| `nav_filename` | `.nav.yml` | Filename used for local subtree overrides. |
+
+## Page titles
+
+Generated items use page front matter when it is available:
+
+```yaml
+---
+title: Configuration
+nav_title: Config
+---
+```
+
+Use `title` for the page heading and `nav_title` when the navigation label should be shorter.
+
+## URLs
+
+Jekyll controls the final page URL. The plugin reads those URLs from generated pages, so settings like `permalink: pretty` work normally.

data/site/docs/guides/data.md

@@ -0,0 +1,40 @@
+---
+title: Generated Data
+---
+
+The plugin writes navigation data onto each page under the configured docs root.
+
+## Page variables
+
+| Variable | Description |
+| --- | --- |
+| `page.awesome_nav` | Full resolved docs tree. |
+| `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.awesome_nav_previous` | Previous page in the resolved navigation order. |
+| `page.awesome_nav_next` | Next page in the resolved navigation order. |
+
+## Tree item shape
+
+Navigation entries are hashes with a title, URL, and optional children:
+
+```yaml
+title: Install Guide
+url: /docs/guides/install/
+children: []
+```
+
+Layouts should treat `children` as optional because leaf pages do not need nested items.
+
+## Site variables
+
+The plugin also writes resolved data into `site.config` for advanced theme use:
+
+| Variable | Description |
+| --- | --- |
+| `site.awesome_nav_tree` | Full resolved tree. |
+| `site.awesome_nav_local_map` | Local navigation lookup by directory. |
+| `site.awesome_nav_files` | Loaded `.nav.yml` data. |
+
+Most layouts should prefer the `page.*` variables because they are already scoped to the current page.

data/site/docs/guides/index.md

@@ -0,0 +1,15 @@
+---
+title: Guides
+---
+
+The guides section demonstrates local control over one part of the docs tree.
+
+The `docs/guides/.nav.yml` file replaces this subtree, which means the guides can be ordered and titled independently of filenames.
+
+## Guides
+
+- [Install Guide]({{ "/docs/guides/install/" | relative_url }})
+- [Layout Integration]({{ "/docs/guides/layouts/" | relative_url }})
+- [Configuration]({{ "/docs/guides/config/" | relative_url }})
+- [Navigation Overrides]({{ "/docs/guides/overrides/" | relative_url }})
+- [Generated Data]({{ "/docs/guides/data/" | relative_url }})