recursive navigation

_includes/active.html

@@ -0,0 +1,8 @@
+{%- if page.url == include.node.url -%}
+  {%- assign active = true -%}
+{%- else -%}
+  {%- assign activityChildren = hierarchy | where_exp:"item", "item.name == include.node.title" | map: "items" | first -%}
+  {%- for activityNode in activityChildren -%}
+    {%- include active.html node=activityNode -%}
+  {%- endfor -%}
+{%- endif -%}

_includes/crumbs.html

@@ -0,0 +1,15 @@
+{%- for crumbsNode in include.nodes -%}
+  {%- include active.html node=crumbsNode -%}
+  {%- if active -%}
+    {%- assign active = false -%}
+    <li class="breadcrumb-nav-list-item">
+      {%- if crumbsNode.title == page.title -%}
+        {{ crumbsNode.title }}
+      {%- else -%}
+        <a href="{{ crumbsNode.url | absolute_url }}">{{ crumbsNode.title }}</a>
+      {%- endif -%}
+    </li>
+    {%- assign crumbsChildren = hierarchy | where_exp:"item", "item.name == crumbsNode.title" | map: "items" | first -%}
+    {%- include crumbs.html nodes=crumbsChildren -%}
+  {%- endif -%}
+{%- endfor -%}

_includes/nav.html

@@ -1,40 +1,23 @@
-<nav role="navigation" aria-label="Main navigation">
-  <ul class="navigation-list">
-    {%- assign pages_list = site.html_pages | sort:"nav_order" -%}
-    {%- for node in pages_list -%}
-      {%- unless node.nav_exclude -%}
-        {%- if node.parent == nil -%}
-          <li class="navigation-list-item{% if page.url == node.url or page.parent == node.title or page.grand_parent == node.title %} active{% endif %}">
-            {%- if page.parent == node.title or page.grand_parent == node.title -%}
-              {%- assign first_level_url = node.url | absolute_url -%}
+{%- assign groups = include.nodes | group_by:"category" | sort:"name" -%}
+{%- if groups.size > 0 -%}
+  <ul class="navigation-list{{ include.class }}">
+    {%- for group in groups -%}
+      {%- if group.name != "" -%}
+        <h4>{{ group.name }}</h4>
+      {%- endif -%}
+      {%- for node in group.items -%}
+        {%- include active.html node=node -%}
+        <li class="navigation-list-item{% if active %} active{% endif %}">
+          <a href="{{ node.url | absolute_url }}" class="navigation-list-link{% if active %} active{% endif %}">{{ node.title }}</a>
+          {%- if active -%}
+            {%- assign active = false -%}
+            {%- assign children = hierarchy | where_exp:"item", "item.name == node.title" | map: "items" | first -%}
+            {%- if children -%}
+              {%- include nav.html class="-child-list" nodes=children -%}
             {%- endif -%}
-            <a href="{{ node.url | absolute_url }}" class="navigation-list-link{% if page.url == node.url %} active{% endif %}">{{ node.title }}</a>
-            {%- if node.has_children -%}
-              {%- assign children_list = site.html_pages | where: "parent", node.title | sort:"nav_order" -%}
-              <ul class="navigation-list-child-list ">
-                {%- for child in children_list -%}
-                  <li class="navigation-list-item {% if page.url == child.url or page.parent == child.title %} active{% endif %}">
-                    {%- if page.url == child.url or page.parent == child.title -%}
-                      {%- assign second_level_url = child.url | absolute_url -%}
-                    {%- endif -%}
-                    <a href="{{ child.url | absolute_url }}" class="navigation-list-link{% if page.url == child.url %} active{% endif %}">{{ child.title }}</a>
-                    {%- if child.has_children -%}
-                        {%- assign grand_children_list = site.html_pages | where: "parent", child.title | sort:"nav_order" -%}
-                        <ul class="navigation-list-child-list">
-                        {%- for grand_child in grand_children_list -%}
-                          <li class="navigation-list-item {% if page.url == grand_child.url %} active{% endif %}">
-                            <a href="{{ grand_child.url | absolute_url }}" class="navigation-list-link{% if page.url == grand_child.url %} active{% endif %}">{{ grand_child.title }}</a>
-                          </li>
-                        {%- endfor -%}
-                      </ul>
-                    {%- endif -%}
-                  </li>
-                {%- endfor -%}
-              </ul>
-            {%- endif -%}
-          </li>
-        {%- endif -%}
-      {%- endunless -%}
+          {%- endif -%}
+        </li>
+      {%- endfor -%}
     {%- endfor -%}
   </ul>
-</nav>
+{%- endif -%}

_includes/toc.html

@@ -0,0 +1,16 @@
+{%- assign tocNodes = hierarchy | where_exp:"item", "item.name == page.title" | map: "items" | first -%}
+{%- if tocNodes.size > 0 -%}
+  <hr>
+  <h2 class="text-delta">Table of contents</h2>
+  <ul>
+    {%- for tocNode in tocNodes -%}
+      <li>
+        <a href="{{ tocNode.url | absolute_url }}">{{ tocNode.title }}</a>
+        {%- if tocNode.summary -%}
+          -
+          {{ tocNode.summary }}
+        {%- endif -%}
+      </li>
+    {%- endfor -%}
+  </ul>
+{%- endif -%}

_layouts/default.html

@@ -2,6 +2,9 @@
 layout: table_wrappers
 ---
 
+{%- assign hierarchy = site.html_pages | where_exp:"item", "item.nav_exclude != true" | sort:"title" | sort:"nav_order" | group_by:"parent" -%}
+{%- assign top_nodes = hierarchy | where_exp:"item", "item.name == ''" | map: "items" | first -%}
+
 <!DOCTYPE html>
 
 <html lang="{{ site.lang | default: "en-US" }}">
@@ -22,7 +25,9 @@
       </div>
 
       <div class="navigation main-nav js-main-nav">
-        {% include nav.html %}
+        <nav aria-label="Main navigation" role="navigation">
+          {%- include nav.html nodes=top_nodes -%}
+        </nav>
       </div>
       <footer class="site-footer">
         <p class="text-small text-grey-dk-000 mb-4">This site uses <a href="https://github.com/pmarsceill/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll.</p>
@@ -53,13 +58,7 @@
             {% if page.parent %}
               <nav class="breadcrumb-nav">
                 <ol class="breadcrumb-nav-list">
-                  {% if page.grand_parent %}
-                    <li class="breadcrumb-nav-list-item"><a href="{{ first_level_url }}">{{ page.grand_parent }}</a></li>
-                    <li class="breadcrumb-nav-list-item"><a href="{{ second_level_url }}">{{ page.parent }}</a></li>
-                  {% else %}
-                    <li class="breadcrumb-nav-list-item"><a href="{{ first_level_url }}">{{ page.parent }}</a></li>
-                  {% endif %}
-                  <li class="breadcrumb-nav-list-item"><span>{{ page.title }}</span></li>
+                  {%- include crumbs.html nodes=top_nodes -%}
                 </ol>
               </nav>
             {% endif %}
@@ -71,20 +70,9 @@
               {{ content }}
             {% endif %}
 
-          {% if page.has_children == true and page.has_toc != false %}
-            <hr>
-            <h2 class="text-delta">Table of contents</h2>
-            {% assign children_list = site.pages | sort:"nav_order" %}
-            <ul>
-              {% for child in children_list %}
-                {% if child.parent == page.title and child.title != page.title %}
-                <li>
-                  <a href="{{ child.url | absolute_url }}">{{ child.title }}</a>{% if child.summary %} - {{ child.summary }}{% endif %}
-                </li>
-                {% endif %}
-              {% endfor %}
-            </ul>
-          {% endif %}
+            {%- if page.has_toc != false -%}
+              {%- include toc.html -%}
+            {%- endif -%}
 
           {% if site.footer_content != nil %}
             <hr>

_sass/navigation.scss

@@ -42,16 +42,6 @@
   @include mq(md) {
     @include fs-3;
   }
-
-  .navigation-list-child-list {
-    display: none;
-  }
-
-  &.active {
-    .navigation-list-child-list {
-      display: block;
-    }
-  }
 }
 
 .navigation-list-link {

assets/js/just-the-docs.js

@@ -27,6 +27,11 @@ function initNav() {
   const mainNav = document.querySelector('.js-main-nav');
   const pageHeader = document.querySelector('.js-page-header');
   const navTrigger = document.querySelector('.js-main-nav-trigger');
+  const activeItem = mainNav.querySelector('.active');
+
+  if (activeItem) {
+    activeItem.scrollIntoView();
+  }
 
   jtd.addEvent(navTrigger, 'click', function(e){
     e.preventDefault();

docs/navigation-structure.md

@@ -17,7 +17,7 @@ nav_order: 5
 
 ## Main navigation
 
-The main navigation for your Just the Docs site is on the left side of the page at large screens and on the top (behind a tap) on small screens. The main navigation can be structured to accommodate a multi-level menu system (pages with children and grandchildren).
+The main navigation for your Just the Docs site is on the left side of the page at large screens and on the top (behind a tap) on small screens. The main navigation can be structured to accommodate a multi-level menu system (pages with children).
 
 By default, all pages will appear as top level pages in the main nav unless a parent page is defined (see [Pages with Children](#pages-with-children)).
 
@@ -88,9 +88,6 @@ Sometimes you will want to create a page with many children (a section). First,
 +-- ..
 ```
 
-On the parent pages, add this YAML front matter parameter:
--  `has_children: true` (tells us that this is a parent page)
-
 #### Example
 {: .no_toc }
 
@@ -99,7 +96,6 @@ On the parent pages, add this YAML front matter parameter:
 layout: default
 title: UI Components
 nav_order: 2
-has_children: true
 ---
 ```
 
@@ -136,18 +132,14 @@ By default, all pages with children will automatically append a Table of Content
 layout: default
 title: UI Components
 nav_order: 2
-has_children: true
 has_toc: false
 ---
 ```
 
 ### Children with children
 {: .text-gamma }
 
-Child pages can also have children (grandchildren). This is achieved by using a similar pattern on the child and grandchild pages.
-
-1. Add the `has_children` attribute to the child
-1. Add the `parent` and `grand_parent` attribute to the grandchild
+Child pages can also have children.
 
 #### Example
 {: .no_toc }
@@ -158,7 +150,6 @@ layout: default
 title: Buttons
 parent: UI Components
 nav_order: 2
-has_children: true
 ---
 ```
 
@@ -167,7 +158,6 @@ has_children: true
 layout: default
 title: Buttons Child Page
 parent: Buttons
-grand_parent: UI Components
 nav_order: 1
 ---
 ```
@@ -188,6 +178,52 @@ This would create the following navigation structure:
 +-- ..
 ```
 
+### Categories
+
+Items in the main menu can be grouped into categories, with a `category:` YAML
+front matter option.
+
+A category is not a page/link itself, it simply renders an `h4` tag above a
+group of links, and is entirely optional.
+
+#### Example
+{: .no_toc }
+
+```yaml
+---
+layout: default
+category: Category 1
+title: Page 1
+---
+```
+
+```yaml
+---
+layout: default
+category: Category 2
+title: Page 2
+---
+```
+
+```yaml
+---
+layout: default
+category: Category 1
+title: Page 3
+---
+```
+
+This will result in the following menu structure:
+
+```
+CATEGORY 1
+Page 1
+Page 3
+
+CATEGORY 2
+Page 2
+```
+
 ---
 
 ## Auxiliary Navigation

docs/ui-components/ui-components.md

@@ -2,7 +2,6 @@
 layout: default
 title: UI Components
 nav_order: 3
-has_children: true
 permalink: /docs/ui-components
 ---
 

docs/utilities/utilities.md

@@ -2,7 +2,6 @@
 layout: default
 title: Utilities
 nav_order: 4
-has_children: true
 permalink: docs/utilities
 ---