just-the-docs/_includes/sorted_pages.html

{%- comment -%}
  Include as: {%- include sorted_pages.html pages = pages -%}
  Depends on: include.pages.
  Assigns to: sorted_pages.
  Overwrites: 
    nav_order_pages, title_order_pages, 
    nav_number_pages, nav_string_pages, nav_order_groups, group,
    title_number_pages, title_string_pages, title_order_groups.
{%- endcomment -%}

{%- comment -%}
  The `nav_order` values of pages affect the order in which they are shown in
  the navigation panel and in the automatically generated tables of contents.
  Sibling pages with the same `nav_order` value may be shown in any order.
  Sibling pages with no `nav_order` value are shown after all pages that have
  explicit `nav_order` values, ordered by their `title` values.
  
  The `nav_order` and `title` values can be numbers or strings. To avoid build
  failures, we sort numbers and strings separately. We sort numbers by their
  values, and strings lexicographically. The case-sensitivity of string sorting
  is determined by the configuration setting of `nav_sort`. Pages with no `title`
  value are excluded from the navigation.

  Note: Numbers used as `title` or `nav_order` values should not be in quotes,
  unless you intend them to be lexicographically ordered. Numbers are written
  without spaces or thousands-separators. Negative numbers are preceded by `-`.
  Floats are written with the integral and fractional parts separated by `.`.
  (Bounds on the magnitude and precision are presumably the same as in Liquid.)
{%- endcomment -%}

{%- assign nav_order_pages = include.pages
    | where_exp: "item", "item.nav_order != nil" -%}
{%- assign title_order_pages = include.pages
    | where_exp: "item", "item.nav_order == nil" -%}

{%- comment -%}
  Divide the arrays of `nav_order_pages` and `title_order_pages` according to
  the type of value.
  
  The first character of the result of `jsonify` is `"` only for strings.
  Grouping by a single character also ensures the number of groups is small.
{%- endcomment -%}

{%- assign nav_number_pages = "" | split: "" -%}
{%- assign nav_string_pages = "" | split: "" -%}
{%- assign nav_order_groups = nav_order_pages
  | group_by_exp: "item", "item.nav_order | jsonify | slice: 0" -%}
{%- for group in nav_order_groups -%}
  {%- if group.name == '"' -%}
    {%- assign nav_string_pages = group.items -%}
  {%- else -%}
    {%- assign nav_number_pages = nav_number_pages | concat: group.items -%}
  {%- endif -%}
{%- endfor -%}

{%- unless nav_number_pages == empty -%}
  {%- assign nav_number_pages = nav_number_pages | sort: "nav_order" -%}
{%- endunless -%}

{%- unless nav_string_pages == empty -%}
  {%- if site.nav_sort == 'case_insensitive' -%}
    {%- assign nav_string_pages = nav_string_pages | sort_natural: "nav_order" -%}
  {%- else -%}
    {%- assign nav_string_pages = nav_string_pages | sort: "nav_order" -%}
  {%- endif -%}
{%- endunless -%}

{%- assign title_number_pages = "" | split: "" -%}
{%- assign title_string_pages = "" | split: "" -%}
{%- assign title_order_groups = title_order_pages
    | group_by_exp: "item", "item.title | jsonify | slice: 0" -%}
{%- for group in title_order_groups -%}
  {%- if group.name == '"' -%}
    {%- assign title_string_pages = group.items -%}
  {%- else -%}
    {%- assign title_number_pages = title_number_pages | concat: group.items -%}
  {%- endif -%}
{%- endfor -%}

{%- unless title_number_pages == empty -%}
  {%- assign title_number_pages = title_number_pages | sort: "title" -%}
{%- endunless -%}

{%- unless title_string_pages == empty -%}
  {%- if site.nav_sort == 'case_insensitive' -%}
    {%- assign title_string_pages = title_string_pages | sort_natural: "title" -%}
  {%- else -%}
    {%- assign title_string_pages = title_string_pages | sort: "title" -%}
  {%- endif -%}
{%- endunless -%}

{%- assign sorted_pages = nav_number_pages
    | concat: nav_string_pages
    | concat: title_number_pages
    | concat: title_string_pages -%}