From 8ac545a5eb5da8e2ebe7dda1a8bffa9d94e88cc2 Mon Sep 17 00:00:00 2001
From: Peter Mosses <p.d.mosses@me.com>
Date: Wed, 21 Aug 2019 13:49:07 +0200
Subject: [PATCH] Optional delay of grandchildren link display

The current default is that when a grandparent is selected, the links to its
children *and all its grandchildren* are displayed in the navigation menu.
Setting `grandchildren_branch: true` in `_config.yml` delays the display of links
to grandchildren until their parent is selected.
---
 _config.yml                  |  3 +++
 _includes/nav.html           |  2 ++
 docs/navigation-structure.md | 14 ++++++++++++++
 3 files changed, 19 insertions(+)

diff --git a/_config.yml b/_config.yml
index d12d439..1d5164b 100644
--- a/_config.yml
+++ b/_config.yml
@@ -27,6 +27,9 @@ search_enabled: true
 # Enable or disable heading anchors
 heading_anchors: true
 
+# Restrict display of grandchildren to selected parent when true:
+grandchildren_branch: false
+
 # Aux links for the upper right navigation
 aux_links:
   "Just the Docs on GitHub":
diff --git a/_includes/nav.html b/_includes/nav.html
index 1c1dd2b..6ab2dbc 100644
--- a/_includes/nav.html
+++ b/_includes/nav.html
@@ -20,6 +20,7 @@
                     {%- 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 -%}
+                    {%- if page.url == child.url or page.parent == child.title or site.grandchildren_branch != true -%}
                         {%- 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 -%}
@@ -29,6 +30,7 @@
                         {%- endfor -%}
                       </ul>
                     {%- endif -%}
+                    {%- endif -%}
                   </li>
                 {%- endfor -%}
               </ul>
diff --git a/docs/navigation-structure.md b/docs/navigation-structure.md
index 98107cf..cce9def 100644
--- a/docs/navigation-structure.md
+++ b/docs/navigation-structure.md
@@ -191,6 +191,20 @@ This would create the following navigation structure:
 +-- ..
 ```
 
+The current default is that when a grandparent is selected, the links to its
+children *and all its grandchildren* are displayed in the navigation menu.
+So in the above example, selecting `UI Components` displays the link to
+`Button Child Page` as well as the link to `Buttons`.
+
+Setting the following global option in `_config.yml` delays the display of links
+to grandchildren until their parent is selected. So selecting `UI Components`
+displays only the link to `Buttons`, and the link to `Button Child Page` is
+displayed when `Buttons` is selected.
+
+```
+grandchildren_branch: true
+```
+
 ---
 
 ## Auxiliary Navigation