Merge pull request #236 from pdmosses/default-nav-order

Default nav order

.gitignore

@@ -1,5 +1,6 @@
 *.gem
 .bundle
+.jekyll-cache
 .sass-cache
 _site
 Gemfile.lock

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

_includes/nav.html

@@ -1,6 +1,15 @@
 <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" -%}
+    {%- 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 -%}
@@ -10,29 +19,27 @@
             {%- 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 -%}
-                  {%- unless child.nav_exclude -%}
+                {%- unless child.nav_exclude -%}
-                    <li class="navigation-list-item {% if page.url == child.url or page.parent == child.title %} active{% endif %}">
+                  <li class="navigation-list-item {% if page.url == child.url or page.parent == child.title %} active{% endif %}">
-                      {%- if page.url == child.url or page.parent == child.title -%}
+                    {%- if page.url == child.url or page.parent == child.title -%}
-                        {%- assign second_level_url = child.url | absolute_url -%}
+                      {%- assign second_level_url = child.url | absolute_url -%}
-                      {%- endif -%}
+                    {%- endif -%}
-                      <a href="{{ child.url | absolute_url }}" class="navigation-list-link{% if page.url == child.url %} active{% endif %}">{{ child.title }}</a>
+                    <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 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">
+                        <ul class="navigation-list-child-list">
-                          {%- for grand_child in grand_children_list -%}
+                        {%- for grand_child in grand_children_list -%}
-                            {%- unless grand_child.nav_exclude -%}
+                          <li class="navigation-list-item {% if page.url == grand_child.url %} active{% endif %}">
-                              <li class="navigation-list-item {% if page.url == grand_child.url %} active{% endif %}">
+                            <a href="{{ grand_child.url | absolute_url }}" class="navigation-list-link{% if page.url == grand_child.url %} active{% endif %}">{{ grand_child.title }}</a>
-                                <a href="{{ grand_child.url | absolute_url }}" class="navigation-list-link{% if page.url == grand_child.url %} active{% endif %}">{{ grand_child.title }}</a>
+                          </li>
-                              </li>
+                        {%- endfor -%}
-                            {%- endunless -%}
+                      </ul>
-                          {%- endfor -%}
+                    {%- endif -%}
-                        </ul>
+                  </li>
-                      {%- endif -%}
+                {%- endunless -%}
-                    </li>
-                  {%- endunless -%}
                 {%- endfor -%}
               </ul>
             {%- endif -%}

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

docs/navigation-structure.md

@@ -38,6 +38,12 @@ 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.
+
 ---
 
 ## Excluding pages

docs/utilities/color.md

@@ -2,7 +2,6 @@
 layout: default
 title: Color
 parent: Utilities
-nav_order: 3
 ---
 
 # Color Utilities

docs/utilities/layout.md

@@ -2,7 +2,6 @@
 layout: default
 title: Layout
 parent: Utilities
-nav_order: 2
 ---
 
 # Layout Utilities

docs/utilities/responsive-modifiers.md

@@ -2,7 +2,6 @@
 layout: default
 title: Responsive Modifiers
 parent: Utilities
-nav_order: 1
 ---
 
 # Responsive modifiers

docs/utilities/typography.md

@@ -2,7 +2,6 @@
 layout: default
 title: Typography
 parent: Utilities
-nav_order: 4
 ---
 
 # Typography Utilities