From 6287d8a6da59b09df4bca317eaca414abda9e349 Mon Sep 17 00:00:00 2001
From: John Mertic <jmertic@linuxfoundation.org>
Date: Mon, 4 Jul 2022 15:27:20 -0400
Subject: [PATCH] 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           | 10 +++++++++-
 docs/navigation-structure.md | 15 +++++++++++++++
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/_includes/nav.html b/_includes/nav.html
index accfd89..a2aa2d6 100644
--- a/_includes/nav.html
+++ b/_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 -%}
-          {%- assign children_list = pages_list | where: "parent", node.title -%}
+          {%- 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 -%}
diff --git a/docs/navigation-structure.md b/docs/navigation-structure.md
index 1ca74a1..9d481bd 100644
--- a/docs/navigation-structure.md
+++ b/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.