Revert "Revert "Optional delay of grandchildren link display""

This reverts commit 89f79138.

_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":

_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>

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