just-the-docs 0.9.0 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce292fe4d8d3ed40611eb39229671ef8e38e86134e288d54c7e9f93412c4eedc
-  data.tar.gz: fc63da23207b3c16826bd634257efa1becc71abb2a2a3004a92f9136a52b04ad
+  metadata.gz: 699cb64eadf9b3149580ea5751976d46c49a461437731e59b8e38ee65805c745
+  data.tar.gz: e797cc9bea526d75c794feb3b392e4721f5d3de5b6f33ea86dc6a4ac1e068a60
 SHA512:
-  metadata.gz: 811ca2371d262ed21c7009f7fcb86811274bdb8d42e64960fe32be6adab4a63a734d3561a8b3011b24d3601c91516cbb70fd1533200d125cc1771a380fba0ca8
-  data.tar.gz: 33ee2161b4b212f16e42e2d1c858004a8c06860a69efe7d5ff673a8217bd44b5d657465bbe7336593f45adb040991ddb0a369aaba6104e10d00d80560e79e249
+  metadata.gz: 8fcba642e7b774f78fdd8a68427a74161ecebbbf6b89cd3c0c38f2dd98c8a3c11c099bfb8d1012dbdc4b80ec4845d65704f8046ec05994e061ff708ccc9f4d03
+  data.tar.gz: c8381ca89fcbcf87f47495db27d9a35574d1643678888d6c52cfc412a6a2e186f712378185beb08846b3a46b94a114ea1542131630dcc35b88aa1e2398e61a7c

data/CHANGELOG.md

@@ -23,6 +23,74 @@ Docs changes made since the latest release:
 
 - N/A
 
+## Release v0.10.1
+
+Hi folks! This patch fixes two bugs related to generated navigation elements and improves our docs.
+
+This release should be a straightforward upgrade for all users of Just the Docs. Thank you for your continued support!
+
+### Bugfixes
+
+- Fixed: `back_to_top` not displaying when no other footer variables are set by [@mattxwang] in [#1461]
+- Fixed: auto-generated child navigation (TOC) by [@pdmosses] in [#1590]
+
+### Documentation
+
+- Fixed: incorrect docs for example with minimal layout parent, default layout child by [@janbrasna] in [#1540]
+- Fixed: unclear docs on using in-page table of contents by [@sebjameswml] in [#1551]
+
+### New Contributors
+
+- [@janbrasna] made their first contribution in [#1540]
+- [@sebjameswml] made their first contribution in [#1551]
+
+[@janbrasna]: https://github.com/janbrasna
+[@sebjameswml]: https://github.com/sebjameswml
+
+[#1461]: https://github.com/just-the-docs/just-the-docs/pull/1461
+[#1540]: https://github.com/just-the-docs/just-the-docs/pull/1540
+[#1551]: https://github.com/just-the-docs/just-the-docs/pull/1551
+[#1590]: https://github.com/just-the-docs/just-the-docs/pull/1590
+
+## Release v0.10.0
+
+Hi folks! This minor release adds one of our most-requested features: unlimited multi-level navigation (also known as recursive navigation). Huge thanks to [@pdmosses] for his wonderful work in implementing this feature!
+
+This release should be a straightforward upgrade for all users of Just the Docs. Thank you for your continued support!
+
+### Using Release `v0.10.0`
+
+Users who have not pinned the theme version will be **automatically upgraded to `v0.9.0` the next time they build their site**.
+
+To use this release explicitly as a remote theme:
+
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.10.0
+```
+
+To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
+
+```ruby
+gem "just-the-docs", "0.10.0"
+```
+
+To use and pin a previous version of the theme, replace the `0.10.0` with the desired release tag.
+
+### New Features
+
+- Added: Allow unlimited multi-level navigation by [@pdmosses] in [#1431]
+
+### Documentation
+
+- Added: Allow unlimited multi-level navigation by [@pdmosses] in [#1440]
+- Added: sitemap (via `jekyll-sitemap` plugin) by [@mattxwang] in [#1530]
+- Fixed: (non-systemic) accessibility issues flagged by aXe by [@mattxwang] in [#1531]
+
+[#1431]: https://github.com/just-the-docs/just-the-docs/pull/1431
+[#1440]: https://github.com/just-the-docs/just-the-docs/pull/1440
+[#1530]: https://github.com/just-the-docs/just-the-docs/pull/1530
+[#1530]: https://github.com/just-the-docs/just-the-docs/pull/1531
+
 ## Release v0.9.0
 
 Hi folks! This minor release adds a `nav_enabled` set of variables to enable/disable the navigation at a site, layout, and page level --- and uses that to add search and auxilary links to the `minimal` layout. In addition, it fixes `search-data.json` corruption with default layouts and some minor CSS/SCSS issues.
@@ -31,7 +99,7 @@ This release should be a straightforward upgrade for all users of Just the Docs.
 
 ### Using Release `v0.9.0`
 
-Users who have not pinned the theme version will be **automatically upgraded to `v0.8.0` the next time they build their site**.
+Users who have not pinned the theme version will be **automatically upgraded to `v0.9.0` the next time they build their site**.
 
 To use this release explicitly as a remote theme:
 
@@ -601,7 +669,7 @@ We're so excited to release Just the Docs `v0.4.0`. This release has been almost
 - [callouts](https://just-the-docs.com/docs/ui-components/callouts/), a new design component to highlight content
 - [configuring mermaid.js](https://just-the-docs.com/docs/ui-components/code/#mermaid-diagram-code-blocks), a markdown-native diagram visualization library
 - [copy code button](https://just-the-docs.com/docs/ui-components/code/#copy-button) for code snippets
-- [external navigation links](https://just-the-docs.com/docs/navigation-structure/#external-navigation-links)
+- external navigation links
 - major improvements to nav generation efficiency and robustness
 - minor improvements to built-in accessibility (SVG icons, nav titles, skip to main content)
 - [modularized site components](https://just-the-docs.com/docs/customization/#custom-layouts-and-includes) (advanced feature)

data/README.md

@@ -32,7 +32,7 @@ More specifically, the created site:
 
 Other than that, you're free to customize sites that you create with the template, however you like. You can easily change the versions of `just-the-docs` and Jekyll it uses, as well as adding further plugins.
 
-### Use RubyGems
+### Use as a Ruby Gem
 
 Alternatively, you can install the theme as a Ruby Gem, without creating a new site.
 
@@ -48,17 +48,11 @@ And add this line to your Jekyll site's `_config.yml`:
 theme: just-the-docs
 ```
 
-And then execute:
+And then install all relevant dependencies:
 
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install just-the-docs
-
-Alternatively, you can run it inside Docker while developing your site
-
-    $ docker-compose up
+```shell
+$ bundle
+```
 
 ## Usage
 

data/_includes/components/breadcrumbs.html

@@ -1,144 +1,96 @@
 {%- comment -%}
   Include as: {%- include components/breadcrumbs.html -%}
   Depends on: page, site.
+  Includes: components/site_nav.html.
   Results in: HTML for the breadcrumbs component.
   Overwrites:
-    node, pages_list, parent_page, grandparent_page.
+    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_end_index, nav_breadcrumb.
 {%- endcomment -%}
 
-{%- if page.url != "/" and page.parent -%}
+{%- if page.url != "/" and page.parent and page.title -%}
+
+{%- capture site_nav -%}
+{%- include_cached components/site_nav.html all=true -%}
+{%- endcapture -%}
 
 {%- capture nav_list_link -%}
 <a href="{{ page.url | relative_url }}" class="nav-list-link">
 {%- endcapture -%}
 
-{%- capture site_nav -%}
-{%- include_cached components/site_nav.html -%}
+{%- capture nav_list_simple -%}
+<ul class="nav-list">
 {%- endcapture -%}
 
-{%- if site_nav contains nav_list_link -%}
-
-  {%- capture nav_list_simple -%}
-  <ul class="nav-list">
-  {%- endcapture -%}
-
-  {%- capture nav_list_link_class %} class="nav-list-link">
-  {%- endcapture -%}
-
-  {%- capture nav_category -%}
-  <div class="nav-category">
-  {%- endcapture -%}
-
-  {%- assign nav_anchor_splits =
-        site_nav | split: nav_list_link |
-        first | split: nav_category |
-        last | split: "</a>" -%}
-
-  {%- comment -%}
-    The ordinary pages (if any) and the collections pages (if any) are separated by
-    occurrences of nav_category.
-    
-    Any ancestor nav-links of the page are contained in the last group of pages,
-    immediately preceding nav-lists. After splitting at "</a>", the anchor that
-    was split is a potential ancestor link when the following split starts with
-    a nav-list. 
-    
-    The array nav_breadcrumbs is the stack of current potential ancestors of the
-    current page. A split that contains one or more "</ul>"s requires that number
-    of potential ancestors to be popped from the stack.
-    
-    The number of occurrences of a string in nav_split_next is computed by removing
-    them all, then dividing the resulting size difference by the length of the string.
-  {%- endcomment %}
-
-  {%- assign nav_breadcrumbs = "" | split: "" -%}
-
-  {%- for nav_split in nav_anchor_splits -%}
-  {%- unless forloop.last -%}
-
-  {%- assign nav_split_next = nav_anchor_splits[forloop.index] | strip -%}
-
-  {%- assign nav_split_test =
-        nav_split_next | remove_first: nav_list_simple | prepend: nav_list_simple -%}
-  {%- if nav_split_test == nav_split_next -%}
-    {%- assign nav_breadcrumb_link =
-          nav_split | split: "<a " | last | prepend: "<a " |
-          replace: nav_list_link_class, ">" | append: "</a>" -%}
-    {%- assign nav_breadcrumbs = nav_breadcrumbs | push: nav_breadcrumb_link -%}
-  {%- endif -%}
-
-  {%- if nav_split_next contains "</ul>" -%}
-    {%- assign nav_list_end_less = nav_split_next | remove: "</ul>" -%}
-    {%- assign nav_list_end_count =
-          nav_split_next.size | minus: nav_list_end_less.size | divided_by: 5 -%}
-    {% for nav_end_index in (1..nav_list_end_count) %}
-      {%- assign nav_breadcrumbs = nav_breadcrumbs | pop -%}
-    {%- endfor -%}
-  {%- endif -%}
-
-  {%- endunless -%}
-  {%- endfor -%}
-
-  {%- assign nav_parent_link = nav_breadcrumbs[-1] -%}
-  {%- assign nav_grandparent_link = nav_breadcrumbs[-2] -%}
+{%- capture nav_list_link_class %} class="nav-list-link">
+{%- endcapture -%}
 
-{%- else -%}
+{%- capture nav_category -%}
+<div class="nav-category">
+{%- endcapture -%}
 
-  {%- comment -%}
-    Pages whose links are excluded from the main navigation may still have
-    breadcrumbs. Determining them appears to require inspecting the front matter
-    of all the pages in the same group. For sites with 100s of pages, this is too
-    inefficient in Jekyll 3 (also when the for-loop is replaced by where-filters).
-  {%- endcomment -%}
+{%- assign nav_anchor_splits =
+      site_nav | split: nav_list_link |
+      first | split: nav_category |
+      last | split: "</a>" -%}
 
-  {%- assign pages_list = site[page.collection] | default: site.html_pages -%}
+{%- comment -%}
+  The ordinary pages (if any) and the collections pages (if any) are separated by
+  occurrences of nav_category.
   
-  {%- assign parent_page = nil -%}
-  {%- assign grandparent_page = nil -%}
-
-  {%- for node in pages_list -%}
+  Any ancestor nav-links of the page are contained in the last group of pages,
+  immediately preceding nav-lists. After splitting at "</a>", the anchor that
+  was split is a potential ancestor link when the following split starts with
+  a nav-list. 
+  
+  The array nav_breadcrumbs is the stack of current potential ancestors of the
+  current page. A split that contains one or more "</ul>"s requires that number
+  of potential ancestors to be popped from the stack.
   
-    {%- if node.has_children and page.grand_parent -%}
+  The number of occurrences of a string in nav_split_next is computed by removing
+  them all, then dividing the resulting size difference by the length of the string.
+{%- endcomment %}
 
-      {%- if node.title == page.parent and node.parent == page.grand_parent -%}
-        {%- assign parent_page = node -%}
-      {%- endif -%}
-      {%- if node.title ==  page.grand_parent -%}
-        {%- assign grandparent_page = node -%}
-      {%- endif -%}
-      {%- if parent_page and grandparent_page -%}
-        {%- break -%}
-      {%- endif -%}
+{%- assign nav_breadcrumbs = "" | split: "" -%}
 
-    {%- elsif node.has_children and node.title == page.parent and node.parent == nil -%}
+{%- for nav_split in nav_anchor_splits -%}
+{%- unless forloop.last -%}
 
-      {%- assign parent_page = node -%}
-      {%- break -%}
+{%- assign nav_split_next = nav_anchor_splits[forloop.index] | strip -%}
 
-    {%- endif -%}
+{%- assign nav_split_test =
+      nav_split_next | remove_first: nav_list_simple | prepend: nav_list_simple -%}
+{%- if nav_split_test == nav_split_next -%}
+  {%- assign nav_breadcrumb_link =
+        nav_split | split: "<a " | last | prepend: "<a " |
+        replace: nav_list_link_class, ">" | append: "</a>" -%}
+  {%- assign nav_breadcrumbs = nav_breadcrumbs | push: nav_breadcrumb_link -%}
+{%- endif -%}
 
+{%- if nav_split_next contains "</ul>" -%}
+  {%- assign nav_list_end_less = nav_split_next | remove: "</ul>" -%}
+  {%- assign nav_list_end_count =
+        nav_split_next.size | minus: nav_list_end_less.size | divided_by: 5 -%}
+  {% for nav_end_index in (1..nav_list_end_count) %}
+    {%- assign nav_breadcrumbs = nav_breadcrumbs | pop -%}
   {%- 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 -%}
-
 {%- endif -%}
 
+{%- endunless -%}
+{%- endfor -%}
+
 <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>
+    {%- 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>
 
+{% if site.nav_error_report %}
+{{ nav_error_report }}
+{% endif %}
+
 {%- endif -%}

data/_includes/components/children_nav.html

@@ -1,33 +1,90 @@
 {%- comment -%}
   Include as: {%- include components/children_nav.html -%}
-  Depends on: page, site.
+  Depends on: page, site, nav_breadcrumbs.
   Results in: HTML for the children-navigation component.
-  Includes:
-    sorted_pages.html
-    toc_heading_custom.html
+  Includes: components/nav/sorted.html, toc_heading_custom.html.
   Overwrites:
-    child_pages.
+    nav_ancestor_links, nav_top_node_titles, nav_child_candidates, nav_children,
+    nav_child, nav_child_ok, nav_child_ancestor, nav_sorted.
 {%- endcomment -%}
 
-{%- if page.has_children == true and page.has_toc != false -%}
-  {%- assign child_pages = site[page.collection]
-        | default: site.html_pages
-        | where: "parent", page.title
-        | where: "grand_parent", page.parent -%}
+{%- comment -%}
+  Whether a page has any children is checked efficiently by inspecting the cached
+  site_nav. If the page has no children, nav_children is set to an empty array;
+  otherwise nav_children is left unset. (The site_nav is rendered the first time
+  it is included, and that may overwrite various variables.)
+{%- endcomment -%}
 
-  {%- include sorted_pages.html pages = child_pages -%}
+{%- if page.has_children == false -%}
+  {%- assign nav_children = "" | split: "" -%}
+{%- else -%}
 
-  {%- if page.child_nav_order == 'desc' or page.child_nav_order == 'reversed' -%}
-    {%- assign sorted_pages = sorted_pages | reverse -%}
+  {%- capture site_nav -%}
+  {%- include_cached components/site_nav.html all=true -%}
+  {%- endcapture -%}
+
+  {%- assign nav_children = nil -%}
+
+  {%- capture nav_list_link -%}
+  <a href="{{ page.url | relative_url }}" class="nav-list-link">
+  {%- endcapture -%}
+
+  {%- capture nav_list_simple -%}
+  <ul class="nav-list">
+  {%- endcapture -%}
+
+  {%- assign nav_child_start = site_nav
+        | split: nav_list_link | last
+        | split: "</a>" | slice: 1 | first -%}
+
+  {%- assign nav_child_test = nav_child_start 
+        | remove_first: nav_list_simple | prepend: nav_list_simple -%}
+    
+  {%- if nav_child_start != nav_child_test -%}
+    {%- assign nav_children = "" | split: "" -%}
   {%- endif -%}
+
 {%- endif -%}
 
+{%- unless nav_children -%}
+
+  {%- comment -%}
+    The layout is assumed to include components/breadcrumbs.html before this file,
+    otherwise it needs to be included here.
+  {%- endcomment -%}
+
+  {%- assign nav_ancestors = "" | split: "" -%}
+  {%- for nav_link in nav_breadcrumbs -%}
+    {%- assign nav_title = nav_link | split: ">" | slice: 1 | first | append: ">" | remove: "</a>" -%}
+    {%- assign nav_ancestors = nav_ancestors | push: nav_title -%}
+  {%- endfor -%}
+
+  {%- assign nav_parenthood = site[page.collection] | default: site.html_pages
+    | where_exp: "item", "item.title != nil" | group_by: "parent" -%}
+
+  {%- assign nav_top_nodes = nav_parenthood
+      | where_exp: "item", "item.name == ''" | map: "items" | first -%}
+
+  {% assign nav_top_node_titles = nav_top_nodes | map: "title" -%}
+
+  {%- include components/nav/children.html node=page ancestors=nav_ancestors all=true -%}
+
+{%- endunless -%}
+
+{%- if nav_children.size >= 1 -%}
+
+  {%- if page.child_nav_order == 'desc' or page.child_nav_order == 'reversed' -%}
+    {%- assign nav_children = nav_children | reverse -%}
+  {%- endif -%}
+
 <hr>
 {% include toc_heading_custom.html %}
 <ul>
-{% for child in sorted_pages %}
+  {% for nav_child in nav_children %}
   <li>
-    <a href="{{ child.url | relative_url }}">{{ child.title }}</a>{% if child.summary %} - {{ child.summary }}{% endif %}
+    <a href="{{ nav_child.url | relative_url }}">{{ nav_child.title }}</a>{% if nav_child.summary %} - {{ nav_child.summary }}{% endif %}
   </li>
-{% endfor %}
+  {% endfor %}
 </ul>
+
+{%- endif -%}

data/_includes/components/footer.html

@@ -1,7 +1,7 @@
 {% capture footer_custom %}
   {%- include footer_custom.html -%}
 {% endcapture %}
-{% if footer_custom != "" or site.last_edit_timestamp or site.gh_edit_link %}
+{% if footer_custom != "" or site.last_edit_timestamp or site.gh_edit_link or site.back_to_top %}
   <hr>
   <footer>
     {% if site.back_to_top %}

data/_includes/components/nav/children.html

@@ -0,0 +1,48 @@
+{%- comment -%}
+  Include as: {%- include components/nav/children.html node=node ancestors=title_array all=bool -%}
+  Depends on: include.node, include.ancestors, include.all, nav_parenthood, nav_top_node_titles.
+  Includes: components/nav/sorted.html.
+  Assigns to: nav_children.
+  Overwrites:
+    nav_candidates, nav_child, nav_child_ok.
+{%- endcomment -%}
+
+{%- assign nav_children = "" | split: "" -%}
+
+{%- if include.all == true or include.node.has_children != false -%}
+
+  {%- assign nav_candidates = nav_parenthood
+        | where: "name", include.node.title | map: "items" | first -%}
+
+  {%- 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 -%}
+
+    {%- comment -%}
+      The following check rejects nav_child as 3rd-level when include.node is 2nd-level
+      and nav_child can also be 2nd-level. This is for backwards compatibility with
+      existing 3-level sites.
+    {%- endcomment -%}
+    {%- if nav_child.grand_parent == nil and nav_child.ancestor == nil and 
+          nav_top_node_titles contains nav_child.parent and include.ancestors.size >= 1 -%}
+      {%- assign nav_child_ok = false -%}
+    {%- endif -%}
+
+    {%- if nav_child_ok -%}
+      {%- assign nav_children = nav_children | push: nav_child -%}
+    {%- endif -%}
+  {%- endfor -%}
+
+{%- endif -%}
+
+{%- include components/nav/sorted.html pages=nav_children -%}
+{%- assign nav_children = nav_sorted -%}

data/_includes/components/nav/links.html

@@ -0,0 +1,53 @@
+{%- comment -%}
+  Include as: {%- include components/nav/links.html pages=page_array ancestors=title_array all=bool -%}
+  Depends on: include.pages, include.ancestors, include.all.
+  Results in: HTML for the main navigation when all is nil or false;
+    includes links to pages excluded from the main navigation when all is true.
+  Includes: components/nav/sorted.html, components/nav/children.html, components/nav/links.html.
+  Overwrites:
+    node, nav_children, nav_ancestors.
+{%- endcomment -%}
+
+<ul class="nav-list">
+  {%- for node in include.pages -%}
+  {%- if include.all == true or node.nav_exclude != true -%}
+
+  {%- if include.ancestors contains node.title -%}
+  
+    <li class="nav-list-item">
+      <a href="{{ node.url | relative_url }}" class="nav-list-link"> ∞ </a>
+    </li>
+    {%- capture nav_error_report -%}
+      <blockquote class="warning">
+        A page has the same title as its parent page or one of its ancestral pages!<br>
+        This causes an incorrect link in the main navigation panel.<br>
+        Page title: <code>{{ node.title }}</code>, location: <code>{{ node.path }}</code>.
+      </blockquote>
+    {%- endcapture -%}
+
+  {%- else -%}
+  
+    {%- include components/nav/children.html node=node ancestors=include.ancestors all=include.all -%}
+
+    <li class="nav-list-item">
+      {%- if nav_children.size >= 1 -%}
+      <button class="nav-list-expander btn-reset" aria-label="toggle items in {{ node.title }} category" aria-pressed="false">
+        <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg>
+      </button>
+      {%- endif -%}
+      <a href="{{ node.url | relative_url }}" class="nav-list-link">{{ node.title }}</a>
+      {%- if nav_children.size >= 1 -%}
+        {%- if node.child_nav_order == 'desc' or node.child_nav_order == 'reversed' -%}
+          {%- assign nav_children = nav_children | reverse -%}
+        {%- endif -%}
+        {%- assign nav_ancestors = include.ancestors | push: node.title -%}
+        {%- include components/nav/links.html pages=nav_children ancestors=nav_ancestors all=include.all -%}
+      {%- endif -%}
+    </li>
+  
+  {%- endif -%}
+  
+  {%- endif -%}
+  {%- endfor -%}
+</ul>
+{%- comment -%}{%- endcomment -%}

data/_includes/components/nav/pages.html

@@ -0,0 +1,23 @@
+{%- comment -%}
+  Include as: {%- include components/nav/pages.html pages=page_array all=bool -%}
+  Depends on: include.pages.
+  Results in: HTML for the main navigation when all is nil or false;
+    adds links to pages excluded from the main navigation when all is true.
+  Includes: components/nav/links.html
+  Assigns to:
+    nav_parenthood, nav_top_nodes, nav_top_node_titles, nav_ancestors.
+{%- endcomment -%}
+
+{%- assign nav_parenthood = include.pages
+      | where_exp: "item", "item.title != nil" | group_by: "parent" -%}
+
+{%- assign nav_top_nodes = nav_parenthood
+      | where_exp: "item", "item.name == ''" | map: "items" | first -%}
+
+{%- include components/nav/sorted.html pages=nav_top_nodes -%}
+
+{% assign nav_top_node_titles = nav_top_nodes | map: "title" -%}
+
+{%- assign nav_ancestors = "" | split: "" -%}
+
+{%- include components/nav/links.html pages=nav_sorted ancestors=nav_ancestors all=include.all -%}

data/_includes/{sorted_pages.html → components/nav/sorted.html}

@@ -1,7 +1,7 @@
 {%- comment -%}
-  Include as: {%- include sorted_pages.html pages=array_of_pages -%}
+  Include as: {%- include components/nav/sorted.html pages=page_array -%}
   Depends on: include.pages.
-  Assigns to: sorted_pages.
+  Assigns to: nav_sorted.
   Overwrites: 
     nav_order_pages, title_order_pages, double_quote, empty_array,
     nav_number_pages, nav_string_pages, nav_order_groups, group,
@@ -103,7 +103,7 @@
   {%- endif -%}
 {%- endunless -%}
 
-{%- assign sorted_pages = nav_number_pages
+{%- assign nav_sorted = nav_number_pages
       | concat: nav_string_pages
       | concat: title_number_pages
       | concat: title_string_pages -%}

data/_includes/components/site_nav.html

@@ -1,9 +1,10 @@
 {%- comment -%}
-  Include as: {%- include_cached components/site_nav.html -%}
+  Include as: {%- include_cached components/site_nav.html all=bool -%}
   Depends on: site.
-  Results in: HTML for the site-nav.
+  Results in: cached HTML for the main navigation when `all` is nil or false;
+    includes links to pages excluded from the main navigation when `all` is true.
   Includes:
-    components/nav.html
+    components/nav/pages.html
   Overwrites:
     pages_top_size, collections_size, collection_entry,
     collection_key, collection_value, collection.
@@ -16,7 +17,7 @@
         | where_exp:"item", "item.nav_exclude != true"
         | size %}
   {% if pages_top_size > 0 %}
-    {% include components/nav.html pages=site.html_pages %}
+    {% include components/nav/pages.html pages=site.html_pages all=include.all %}
   {% endif %}
   {%- if site.nav_external_links -%}
     <ul class="nav-list">
@@ -51,17 +52,21 @@
                 </button>
                 {%- endif -%}
                 <div class="nav-category">{{ collection_value.name }}</div>
-                {% include components/nav.html pages=collection %}
+                {% include components/nav/pages.html pages=collection all=include.all %}
               </li>
             </ul>
           {% else %}
             <div class="nav-category">{{ collection_value.name }}</div>
-            {% include components/nav.html pages=collection %}
+            {% include components/nav/pages.html pages=collection all=include.all %}
           {% endif %}
         {% else %}
-          {% include components/nav.html pages=collection %}
+          {% include components/nav/pages.html pages=collection all=include.all %}
         {% endif %}
       {% endif %}
     {% endfor %}
   {% endif %}
 </nav>
+
+{% if site.nav_error_report %}
+{{ nav_error_report }}
+{%- endif %}