From 6660f442b078ab9dc668c010b1e4378297f32b22 Mon Sep 17 00:00:00 2001
From: Peter Mosses <p.d.mosses@me.com>
Date: Fri, 11 Oct 2019 21:40:34 +0100
Subject: [PATCH 1/5] Alphabetic navigation order

When `nav_order` is omitted, the order of nodes at each menu level (and in the auto-generated TOC) is alphabetical by `title`, instead of random.
Any nodes with a specified `nav_order` precede all nodes at that level where it is omitted.
Note that `nav_order` fields must have a uniform site-ide type: integers and strings cannot be mixed, otherwise Jekyll reports errors.
The implementation filters the ordered and unordered pages from `site.html_pages`, sorts them separately, and concatenates the resulting arrays.
---
 _includes/nav.html    | 8 +++++---
 _layouts/default.html | 3 +--
 2 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/_includes/nav.html b/_includes/nav.html
index d561a42..a691f4f 100644
--- a/_includes/nav.html
+++ b/_includes/nav.html
@@ -1,6 +1,8 @@
 <nav role="navigation" aria-label="Main navigation">
   <ul class="navigation-list">
-    {%- assign pages_list = site.html_pages | sort:"nav_order" -%}
+    {%- assign ordered_pages_list = site.html_pages | where_exp:"item", "item.nav_order != nil" | sort:"nav_order" -%}
+    {%- assign unordered_pages_list = site.html_pages | where_exp:"item", "item.nav_order == nil" | sort:"title" -%}
+    {%- assign pages_list = ordered_pages_list | concat: unordered_pages_list -%}
     {%- for node in pages_list -%}
       {%- unless node.nav_exclude -%}
         {%- if node.parent == nil -%}
@@ -10,7 +12,7 @@
             {%- endif -%}
             <a href="{{ node.url | absolute_url }}" class="navigation-list-link{% if page.url == node.url %} active{% endif %}">{{ node.title }}</a>
             {%- if node.has_children -%}
-              {%- assign children_list = site.html_pages | where: "parent", node.title | sort:"nav_order" -%}
+              {%- assign children_list = pages_list | where: "parent", node.title -%}
               <ul class="navigation-list-child-list ">
                 {%- for child in children_list -%}
                   <li class="navigation-list-item {% if page.url == child.url or page.parent == child.title %} active{% endif %}">
@@ -19,7 +21,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 -%}
-                        {%- assign grand_children_list = site.html_pages | where: "parent", child.title | sort:"nav_order" -%}
+                        {%- assign grand_children_list = pages_list | where: "parent", child.title -%}
                         <ul class="navigation-list-child-list">
                         {%- for grand_child in grand_children_list -%}
                           <li class="navigation-list-item {% if page.url == grand_child.url %} active{% endif %}">
diff --git a/_layouts/default.html b/_layouts/default.html
index b1d3c72..1aa6ae1 100644
--- a/_layouts/default.html
+++ b/_layouts/default.html
@@ -74,9 +74,8 @@ layout: table_wrappers
           {% if page.has_children == true and page.has_toc != false %}
             <hr>
             <h2 class="text-delta">Table of contents</h2>
-            {% assign children_list = site.pages | sort:"nav_order" %}
             <ul>
-              {% for child in children_list %}
+              {% for child in pages_list %}
                 {% if child.parent == page.title and child.title != page.title %}
                 <li>
                   <a href="{{ child.url | absolute_url }}">{{ child.title }}</a>{% if child.summary %} - {{ child.summary }}{% endif %}

From 210e060f182916411ba55199523bc4fdd377fc08 Mon Sep 17 00:00:00 2001
From: Peter Mosses <p.d.mosses@me.com>
Date: Fri, 11 Oct 2019 21:43:07 +0100
Subject: [PATCH 2/5] Testing default nav order

The `nav_order` fields are removed from the children of the Utilities node, which results in alphabetic order.
---
 docs/utilities/color.md                | 1 -
 docs/utilities/layout.md               | 1 -
 docs/utilities/responsive-modifiers.md | 1 -
 docs/utilities/typography.md           | 1 -
 4 files changed, 4 deletions(-)

diff --git a/docs/utilities/color.md b/docs/utilities/color.md
index ba90b3b..0f37597 100644
--- a/docs/utilities/color.md
+++ b/docs/utilities/color.md
@@ -2,7 +2,6 @@
 layout: default
 title: Color
 parent: Utilities
-nav_order: 3
 ---
 
 # Color Utilities
diff --git a/docs/utilities/layout.md b/docs/utilities/layout.md
index 38ec1b2..4410459 100644
--- a/docs/utilities/layout.md
+++ b/docs/utilities/layout.md
@@ -2,7 +2,6 @@
 layout: default
 title: Layout
 parent: Utilities
-nav_order: 2
 ---
 
 # Layout Utilities
diff --git a/docs/utilities/responsive-modifiers.md b/docs/utilities/responsive-modifiers.md
index bc5e2cb..c732530 100644
--- a/docs/utilities/responsive-modifiers.md
+++ b/docs/utilities/responsive-modifiers.md
@@ -2,7 +2,6 @@
 layout: default
 title: Responsive Modifiers
 parent: Utilities
-nav_order: 1
 ---
 
 # Responsive modifiers
diff --git a/docs/utilities/typography.md b/docs/utilities/typography.md
index 786b65a..6b952a9 100644
--- a/docs/utilities/typography.md
+++ b/docs/utilities/typography.md
@@ -2,7 +2,6 @@
 layout: default
 title: Typography
 parent: Utilities
-nav_order: 4
 ---
 
 # Typography Utilities

From 06853e895ae38cf8b0ffcf57e40f038f759e1cde Mon Sep 17 00:00:00 2001
From: Peter Mosses <p.d.mosses@me.com>
Date: Fri, 11 Oct 2019 23:02:19 +0100
Subject: [PATCH 3/5] Update navigation-structure.md

Added documentation of default nav order.
---
 docs/navigation-structure.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/navigation-structure.md b/docs/navigation-structure.md
index a4fef75..d6d5844 100644
--- a/docs/navigation-structure.md
+++ b/docs/navigation-structure.md
@@ -38,6 +38,10 @@ nav_order: 4
 ---
 ```
 
+The specified `nav_order` parameters on a site should be all integers or all strings.
+Pages without a `nav_order` parameter are ordered alphabetically by their `title`,
+and appear after the explicitly-ordered pages at each level.
+
 ---
 
 ## Excluding pages

From 7e959f4b69355fc04ac0d8ee7e4a289626b98ea5 Mon Sep 17 00:00:00 2001
From: PLanCompS <62553846+plancomps-admin@users.noreply.github.com>
Date: Sat, 25 Apr 2020 13:54:36 +0200
Subject: [PATCH 4/5] Update .gitignore

Added `.jekyll-cache`
---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index b447a12..a802a86 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,6 @@
 *.gem
 .bundle
+.jekyll-cache
 .sass-cache
 _site
 Gemfile.lock

From c46ccd3484faed63b9a04e0bf9cb7a0f3d9334f0 Mon Sep 17 00:00:00 2001
From: PLanCompS <62553846+plancomps-admin@users.noreply.github.com>
Date: Sat, 25 Apr 2020 14:53:45 +0200
Subject: [PATCH 5/5] Made case-insenstive sorting the default

Added a configuration option to determine whether the sort order is case-sensitive.
The default is case-insensitive.

To test:
- open `/just-the-docs/docs/utilities/` in the browser,
  and check that the navigation links in `Utilities` are sorted alphabetically;
- in `docs/utilities/layout.md', change the preamble to `title: layout`,
  and check that the  links in `Utilities` are still sorted alphabetically;
- add `nav_sort: case_sensitive` in the configuration file,
  and check that the link to `layout` is now listed last under `Utilities`.
---
 _config.yml                  |  4 ++++
 _includes/nav.html           | 13 ++++++++++---
 docs/navigation-structure.md |  2 ++
 3 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/_config.yml b/_config.yml
index a090670..92ab71e 100644
--- a/_config.yml
+++ b/_config.yml
@@ -38,6 +38,10 @@ aux_links:
   "Just the Docs on GitHub":
     - "//github.com/pmarsceill/just-the-docs"
 
+# Sort order for navigation links
+nav_sort: case_insensitive # default, equivalent to nil
+# nav_sort: case_sensitive # Capital letters sorted before lowercase
+
 # Footer content appears at the bottom of every page's main content
 footer_content: "Copyright &copy; 2017-2019 Patrick Marsceill. Distributed by an <a href=\"https://github.com/pmarsceill/just-the-docs/tree/master/LICENSE.txt\">MIT license.</a>"
 
diff --git a/_includes/nav.html b/_includes/nav.html
index a691f4f..ec6c786 100644
--- a/_includes/nav.html
+++ b/_includes/nav.html
@@ -1,8 +1,15 @@
 <nav role="navigation" aria-label="Main navigation">
   <ul class="navigation-list">
-    {%- assign ordered_pages_list = site.html_pages | where_exp:"item", "item.nav_order != nil" | sort:"nav_order" -%}
-    {%- assign unordered_pages_list = site.html_pages | where_exp:"item", "item.nav_order == nil" | sort:"title" -%}
-    {%- assign pages_list = ordered_pages_list | concat: unordered_pages_list -%}
+    {%- assign ordered_pages_list = site.html_pages | where_exp:"item", "item.nav_order != nil" -%}
+    {%- assign unordered_pages_list = site.html_pages | where_exp:"item", "item.nav_order == nil" -%}
+    {%- if site.nav_sort == 'case_sensitive' -%}
+      {%- assign sorted_ordered_pages_list = ordered_pages_list | sort:"nav_order" -%}
+      {%- assign sorted_unordered_pages_list = unordered_pages_list | sort:"title" -%}
+    {%- else -%}
+      {%- assign sorted_ordered_pages_list = ordered_pages_list | sort_natural:"nav_order" -%}
+      {%- assign sorted_unordered_pages_list = unordered_pages_list | sort_natural:"title" -%}
+    {%- endif -%}
+    {%- assign pages_list = sorted_ordered_pages_list | concat: sorted_unordered_pages_list -%}
     {%- for node in pages_list -%}
       {%- unless node.nav_exclude -%}
         {%- if node.parent == nil -%}
diff --git a/docs/navigation-structure.md b/docs/navigation-structure.md
index d6d5844..e5f29ad 100644
--- a/docs/navigation-structure.md
+++ b/docs/navigation-structure.md
@@ -41,6 +41,8 @@ nav_order: 4
 The specified `nav_order` parameters on a site should be all integers or all strings.
 Pages without a `nav_order` parameter are ordered alphabetically by their `title`,
 and appear after the explicitly-ordered pages at each level.
+To sort all Capital letters before lowercase letters,
+add `nav_sort: case_sensitive` in the configuration file.
 
 ---