add `reversed`, deprecate `desc` for nav `child_nav_order` (#1061)

* Add 'reversed' as the preferred keyword, with 'desc' as a deprecated alternate

* Doc updates

* Add the test for 'reversed' to the toc_list

Add also a comment about this.

Co-authored-by: Peter Mosses <18308236+pdmosses@users.noreply.github.com>

_includes/nav.html

@@ -169,7 +169,7 @@
         {%- if node.has_children -%}
           {%- assign children_list = second_level_pages
                 | where: "parent", node.title -%}
-          {%- if node.child_nav_order == 'desc' -%}
+          {%- if node.child_nav_order == 'desc' or child.child_nav_order == 'reversed' -%}
             {%- assign children_list = children_list | reverse -%}
           {%- endif -%}
           <ul class="nav-list ">
@@ -186,7 +186,7 @@
                 {%- assign grand_children_list = third_level_pages
                       | where: "parent", child.title
                       | where: "grand_parent", node.title -%}
-                {%- if child.child_nav_order == 'desc' -%}
+                {%- if child.child_nav_order == 'desc' or child.child_nav_order == 'reversed' -%}
                   {%- assign grand_children_list = grand_children_list | reverse -%}
                 {%- endif -%}
                 <ul class="nav-list">
@@ -218,7 +218,8 @@
   the page's top-level breadcrumb (if any), and `second_level_url` to that used
   in the page's second-level breadcrumb (if any).
   
-  For pages with children, the code also sets `toc_list` to the list of child pages.
+  For pages with children, the code also sets `toc_list` to the list of child pages,
+  reversing the order if needed.
 {%- endcomment -%}
 
 {%- if page.collection == include.key -%}
@@ -241,7 +242,7 @@
     {%- assign toc_list = pages_list
           | where: "parent", page.title
           | where_exp: "item", "item.grand_parent == page.parent" -%}
-    {%- if page.child_nav_order == "desc" -%}
+    {%- if page.child_nav_order == 'desc' or page.child_nav_order == 'reversed' -%}
       {%- assign toc_list = toc_list | reverse -%}
     {%- endif -%}
   {%- endif -%}

docs/navigation-structure.md

@@ -146,17 +146,17 @@ The Buttons page appears as a child of UI Components and appears second in the U
 
 ### 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:
+You can optionally add the following to the YAML front matter to reverse the default sort order of child pages:
 
-- `child_nav_order: desc`
+- `child_nav_order: reversed`
 
 #### Example
 {: .no_toc }
 ```yaml
 ---
 layout: default
-title: Descending Child Pages
-child_nav_order: desc
+title: Reversed Child Pages
+child_nav_order: reversed
 ---
 ```