Allow unlimited multi-level navigation

This PR is intended to supersede just-the-docs#462. The only user-level difference from just-the-docs#462 is that disambiguation of parent pages has to use either `grand_parent` or `ancestor` titles: the somewhat unnatural `section_id` and `in_section` fields are not supported. The implementation has been significantly simplified by the changes introduced in v0.7.0 of the theme. This initial draft has not yet been rigorously tested nor profiled.
pdmosses · Feb 24, 2024 · c45f622 · c45f622
1 parent 5357ffa
commit c45f622
Show file tree

Hide file tree

Showing 41 changed files with 324 additions and 218 deletions.
diff --git a/Gemfile b/Gemfile
@@ -4,5 +4,6 @@ gemspec
 gem "jekyll-github-metadata", ">= 2.15"
 
 gem "jekyll-include-cache", group: :jekyll_plugins
+gem "jekyll-default-layout", group: :jekyll_plugins
 
 gem "html-proofer", "~> 5.0", :group => :development
diff --git a/Gemfile.lock b/Gemfile.lock
@@ -14,34 +14,33 @@ GEM
     addressable (2.8.6)
       public_suffix (>= 2.0.2, < 6.0)
     afm (0.2.2)
-    async (2.6.3)
+    async (2.8.2)
       console (~> 1.10)
       fiber-annotation
       io-event (~> 1.1)
       timers (~> 4.1)
-    base64 (0.2.0)
     colorator (1.1.0)
-    concurrent-ruby (1.2.2)
-    console (1.23.2)
+    concurrent-ruby (1.2.3)
+    console (1.23.4)
       fiber-annotation
       fiber-local
+      json
     em-websocket (0.5.3)
       eventmachine (>= 0.12.9)
       http_parser.rb (~> 0)
     ethon (0.16.0)
       ffi (>= 1.15.0)
     eventmachine (1.2.7)
-    faraday (2.8.1)
-      base64
-      faraday-net_http (>= 2.0, < 3.1)
-      ruby2_keywords (>= 0.0.4)
-    faraday-net_http (3.0.2)
+    faraday (2.9.0)
+      faraday-net_http (>= 2.0, < 3.2)
+    faraday-net_http (3.1.0)
+      net-http
     ffi (1.16.3)
     fiber-annotation (0.2.0)
     fiber-local (1.0.0)
     forwardable-extended (2.6.0)
-    google-protobuf (3.25.1-arm64-darwin)
-    google-protobuf (3.25.1-x86_64-linux)
+    google-protobuf (3.25.3-arm64-darwin)
+    google-protobuf (3.25.3-x86_64-linux)
     hashery (2.1.2)
     html-proofer (5.0.8)
       addressable (~> 2.3)
@@ -55,7 +54,7 @@ GEM
     http_parser.rb (0.8.0)
     i18n (1.14.1)
       concurrent-ruby (~> 1.0)
-    io-event (1.2.3)
+    io-event (1.4.4)
     jekyll (4.3.3)
       addressable (~> 2.4)
       colorator (~> 1.0)
@@ -72,6 +71,8 @@ GEM
       safe_yaml (~> 1.0)
       terminal-table (>= 1.8, < 4.0)
       webrick (~> 1.7)
+    jekyll-default-layout (0.1.5)
+      jekyll (>= 3.0, < 5.0)
     jekyll-github-metadata (2.16.1)
       jekyll (>= 3.4, < 5.0)
       octokit (>= 4, < 7, != 4.4.0)
@@ -83,15 +84,18 @@ GEM
       jekyll (>= 3.8, < 5.0)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
+    json (2.7.1)
     kramdown (2.4.0)
       rexml
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
     liquid (4.0.4)
-    listen (3.8.0)
+    listen (3.9.0)
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     mercenary (0.4.0)
+    net-http (0.4.1)
+      uri
     nokogiri (1.16.2-arm64-darwin)
       racc (~> 1.4)
     nokogiri (1.16.2-x86_64-linux)
@@ -101,7 +105,7 @@ GEM
       sawyer (~> 0.9)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
-    pdf-reader (2.11.0)
+    pdf-reader (2.12.0)
       Ascii85 (~> 1.0)
       afm (~> 0.2.1)
       hashery (~> 2.0)
@@ -117,11 +121,10 @@ GEM
     rexml (3.2.6)
     rouge (4.2.0)
     ruby-rc4 (0.1.5)
-    ruby2_keywords (0.0.5)
     safe_yaml (1.0.5)
-    sass-embedded (1.69.6-arm64-darwin)
+    sass-embedded (1.71.1-arm64-darwin)
       google-protobuf (~> 3.25)
-    sass-embedded (1.69.6-x86_64-linux-gnu)
+    sass-embedded (1.71.1-x86_64-linux-gnu)
       google-protobuf (~> 3.25)
     sawyer (0.9.2)
       addressable (>= 2.3.5)
@@ -130,12 +133,13 @@ GEM
       unicode-display_width (>= 1.1.1, < 3)
     timers (4.3.5)
     ttfunk (1.7.0)
-    typhoeus (1.4.0)
+    typhoeus (1.4.1)
       ethon (>= 0.9.0)
     unicode-display_width (2.5.0)
+    uri (0.13.0)
     webrick (1.8.1)
     yell (2.2.2)
-    zeitwerk (2.6.11)
+    zeitwerk (2.6.13)
 
 PLATFORMS
   arm64-darwin
@@ -144,6 +148,7 @@ PLATFORMS
 DEPENDENCIES
   bundler (>= 2.3.5)
   html-proofer (~> 5.0)
+  jekyll-default-layout
   jekyll-github-metadata (>= 2.15)
   jekyll-include-cache
   just-the-docs!

diff --git a/_config.yml b/_config.yml
@@ -171,6 +171,7 @@ plugins:
   - jekyll-seo-tag
   - jekyll-github-metadata
   - jekyll-include-cache
+  - jekyll-default-layout
 
 kramdown:
   syntax_highlighter_opts:

diff --git a/_includes/components/breadcrumbs.html b/_includes/components/breadcrumbs.html
@@ -2,7 +2,14 @@
   Include as: {%- include components/breadcrumbs.html -%}
   Depends on: page, site.
   Results in: HTML for the breadcrumbs component.
+  Issues:
+    For pages that are excluded from the main navigation, the resulting
+    breadcrumbs are limited to the specified parent and grandparent pages,
+    and they require `has_children: true`.
   Overwrites:
+    nav_list_link, site_nav, nav_list_simple, nav_list_link_class, nav_category,
+    nav_anchor_splits, nav_breadcrumbs, nav_split, nav_split_next, nav_split_test,
+    nav_breadcrumb_link, nav_list_end_less, nav_list_end_count, nav_breadcrumb,
     node, pages_list, parent_page, grandparent_page.
 {%- endcomment -%}
 
@@ -79,9 +86,14 @@
   {%- endunless -%}
   {%- endfor -%}
 
-  {%- assign nav_parent_link = nav_breadcrumbs[-1] -%}
-  {%- assign nav_grandparent_link = nav_breadcrumbs[-2] -%}
-
+  <nav aria-label="Breadcrumb" class="breadcrumb-nav">
+    <ol class="breadcrumb-nav-list">
+      {%- for nav_breadcrumb in nav_breadcrumbs -%}
+      <li class="breadcrumb-nav-list-item">{{ nav_breadcrumb }}</li>
+      {%- endfor %}
+      <li class="breadcrumb-nav-list-item"><span>{{ page.title }}</span></li>
+    </ol>
+  </nav>
 {%- else -%}
 
   {%- comment -%}
@@ -119,26 +131,22 @@
 
   {%- endfor -%}
 
-  {%- capture nav_parent_link -%}
-    <a href="{{ parent_page.url | relative_url }}">{{ page.parent }}</a>
-  {%- endcapture -%}
-
-  {%- if page.grand_parent %}
-    {%- capture nav_grandparent_link -%}
-      <a href="{{ grandparent_page.url | relative_url }}">{{ page.grand_parent }}</a>
-    {%- endcapture -%}
-  {%- endif -%}
-
+  <nav aria-label="Breadcrumb" class="breadcrumb-nav">
+    <ol class="breadcrumb-nav-list">
+      {%- if page.grandparent %}
+      <li class="breadcrumb-nav-list-item">
+        <a href="{{ grandparent_page.url | relative_url }}">{{ page.grand_parent }}</a>
+      </li>
+      {%- endif %}
+      <li class="breadcrumb-nav-list-item">
+        <a href="{{ parent_page.url | relative_url }}">{{ page.parent }}</a>
+      </li>
+      <li class="breadcrumb-nav-list-item">
+        <span>{{ page.title }}</span>
+      </li>
+    </ol>
+  </nav>
+
 {%- endif -%}
 
-<nav aria-label="Breadcrumb" class="breadcrumb-nav">
-  <ol class="breadcrumb-nav-list">
-  {%- if nav_grandparent_link %}
-    <li class="breadcrumb-nav-list-item">{{ nav_grandparent_link }}</li>
-  {%- endif %}
-    <li class="breadcrumb-nav-list-item">{{ nav_parent_link }}</li>
-    <li class="breadcrumb-nav-list-item"><span>{{ page.title }}</span></li>
-  </ol>
-</nav>
-
 {%- endif -%}
diff --git a/_includes/components/children_nav.html b/_includes/components/children_nav.html
@@ -2,11 +2,14 @@
   Include as: {%- include components/children_nav.html -%}
   Depends on: page, site.
   Results in: HTML for the children-navigation component.
+  Issues:
+    For sites with more than 3 levels of navigation links, or which use
+    `ancestor` fields, the resulting child links are currently incorrect.
   Includes:
-    sorted_pages.html
+    components/nav/sorted.html
     toc_heading_custom.html
   Overwrites:
-    child_pages.
+    child_pages, child.
 {%- endcomment -%}
 
 {%- if page.has_children == true and page.has_toc != false -%}
@@ -15,7 +18,7 @@
         | where: "parent", page.title
         | where: "grand_parent", page.parent -%}
 
-  {%- include sorted_pages.html pages = child_pages -%}
+  {%- include components/nav/sorted.html pages = child_pages -%}
 
   {%- if page.child_nav_order == 'desc' or page.child_nav_order == 'reversed' -%}
     {%- assign sorted_pages = sorted_pages | reverse -%}
@@ -25,9 +28,9 @@
 <hr>
 {% include toc_heading_custom.html %}
 <ul>
-{% for child in sorted_pages %}
+  {% for child in sorted_pages %}
   <li>
     <a href="{{ child.url | relative_url }}">{{ child.title }}</a>{% if child.summary %} - {{ child.summary }}{% endif %}
   </li>
-{% endfor %}
+  {% endfor %}
 </ul>
diff --git a/_includes/components/nav.html b/_includes/components/nav.html
diff --git a/_includes/components/nav/children.html b/_includes/components/nav/children.html
@@ -0,0 +1,29 @@
+{%- comment -%}
+  Include as:   {%- include components/nav/children.html node=node ancestors=title_array -%}
+  Depends on: include.node, include.ancestors.
+  Assigns to: nav_children.
+  Overwrites:
+    nav_candidates, nav_child, nav_child_ok.
+{%- endcomment -%}
+
+{%- assign nav_candidates = nav_parenthood
+      | where: "name", include.node.title | map: "items" | first -%}
+{%- assign nav_children = "" | split: "" -%}
+
+{%- for nav_child in nav_candidates -%}
+  {%- assign nav_child_ok = true -%}
+
+  {%- if nav_child.grand_parent and nav_child.grand_parent != include.node.parent -%}
+    {%- assign nav_child_ok = false -%}
+  {%- endif -%}
+
+  {%- if nav_child.ancestor and nav_child.ancestor != include.node.title -%}
+    {%- unless include.ancestors contains nav_child.ancestor -%}
+      {%- assign nav_child_ok = false -%}
+    {%- endunless -%}
+  {%- endif -%}
+
+  {%- if nav_child_ok -%}
+    {%- assign nav_children = nav_children | push: nav_child -%}
+  {%- endif -%}
+{%- endfor -%}