Add 'child_nav_order' front matter to be able to sort navigation pages in reverse (#726)

Set `child_nav_order` to `desc` to reverse the sort order for a child section.

Co-authored-by: Matt Wang <matt@matthewwang.me>

_includes/nav.html

@@ -66,7 +66,11 @@
         {%- endif -%}
         <a href="{{ node.url | relative_url }}" class="nav-list-link{% if page.url == node.url %} active{% endif %}">{{ node.title }}</a>
         {%- if node.has_children -%}
+          {%- if node.child_nav_order == 'desc' -%}
+            {%- assign children_list = pages_list | where: "parent", node.title | reverse -%}
+          {%- else -%}
             {%- assign children_list = pages_list | where: "parent", node.title -%}
+          {%- endif -%}
           <ul class="nav-list ">
           {%- for child in children_list -%}
             {%- unless child.nav_exclude -%}
@@ -76,7 +80,11 @@
               {%- endif -%}
               <a href="{{ child.url | relative_url }}" class="nav-list-link{% if page.url == child.url %} active{% endif %}">{{ child.title }}</a>
               {%- if child.has_children -%}
+                {%- if node.child_nav_order == 'desc' -%}
+                {%- assign grand_children_list = pages_list | where: "parent", child.title | where: "grand_parent", node.title | reverse -%}
+                {%- else -%}
                 {%- assign grand_children_list = pages_list | where: "parent", child.title | where: "grand_parent", node.title -%}
+                {%- endif -%}
                 <ul class="nav-list">
                 {%- for grand_child in grand_children_list -%}
                   {%- unless grand_child.nav_exclude -%}

docs/navigation-structure.md

@@ -145,6 +145,21 @@ nav_order: 2
 
 The Buttons page appears as a child of UI Components and appears second in the UI Components section.
 
+### Ordering child pages
+
+You can optionally add the following to the YAML front matter to change the default sort order of child pages from ascending to descending order:
+
+- `child_nav_order: desc`
+
+#### Example
+{: .no_toc }
+```yaml
+---
+layout: default
+title: Descending Child Pages
+child_nav_order: desc
+---
+
 ### Auto-generating Table of Contents
 
 By default, all pages with children will automatically append a Table of Contents which lists the child pages after the parent page's content. To disable this auto Table of Contents, set `has_toc: false` in the parent page's YAML front matter.