just-the-docs 0.4.0.rc2 → 0.4.0.rc4

data/_includes/nav.html

@@ -1,74 +1,167 @@
 {%- comment -%}
-  Pages with no `title` are implicitly excluded from the navigation.
+  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 values of `title` and `nav_order` can be numbers or strings.
-  Jekyll gives build failures when sorting on mixtures of different types,
-  so numbers and strings need to be sorted separately.
+  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 -%}
 
-  Here, numbers are sorted by their values, and come before all strings.
-  An omitted `nav_order` value is equivalent to the page's `title` value
-  (except that a numerical `title` value is treated as a string).
+{%- assign title_pages = include.pages
+      | where_exp: "item", "item.title != nil" -%}
 
-  The case-sensitivity of string sorting is determined by `site.nav_sort`.
+{%- comment -%}
+  A page with `nav_exclude: true` does not appear in the main navigation.
+  If it has a `parent`, it may appear in the parent's table of contents.
+  If it specifies `has_children: true`, it should appear in the breadcrumbs
+  of the child pages, but its order in relation to other pages is irrelevant.
+  Pages that never appear can be removed from the pages that need to be sorted.
+  This optimisation can be significant on a site with many pages.
+  
+  In Jekyll 4, the pages to be sorted can be filtered by:
+  
+  {%- assign title_pages = title_pages
+        | where_exp: "item", "item.nav_exclude != true or item.parent != nil" -%}
+  
+  That filter is not allowed in Jekyll 3. The following iterative code gives the
+  same effect, but it is activated only when it will filter more than 50% of the
+  pages.
 {%- endcomment -%}
 
-{%- assign titled_pages = include.pages
-      | where_exp: "item", "item.title != nil" -%}
+{%- unless title_pages == empty -%}
+  {%- assign unsorted_pages = title_pages
+        | where_exp: "item", "item.parent == nil" 
+        | where_exp: "item", "item.nav_exclude == true" -%}
+  {%- assign title_pages_size = title_pages.size -%}
+  {%- assign unsorted_pages_percent = unsorted_pages.size
+        | times: 100 | divided_by: title_pages_size -%}
+  {%- if unsorted_pages_percent > 50 -%}
+    {%- assign sorted_pages = "" | split: "" -%}
+    {%- for item in title_pages -%}
+      {%- if item.nav_exclude != true or item.parent -%}
+        {%- assign sorted_pages = sorted_pages | push: item -%}
+      {%- endif -%}
+    {%- endfor -%}
+    {%- assign title_pages = sorted_pages -%}
+  {%- endif -%}
+{%- endunless -%}
 
-{%- assign string_ordered_pages = titled_pages
+{%- assign nav_order_pages = title_pages
+      | where_exp: "item", "item.nav_order != nil"  -%}
+{%- assign title_order_pages = title_pages
       | where_exp: "item", "item.nav_order == nil" -%}
-{%- assign nav_ordered_pages = titled_pages
-      | where_exp: "item", "item.nav_order != nil" -%}
 
 {%- comment -%}
-  Add the nav-ordered pages to the number-ordered pages or the string-ordered pages,
-  depending on their `nav_order` value.
+  Divide the arrays of `nav_order_pages` and `title_order_pages` according to
+  the type of value.
   
-  The first character of the `jsonify` result is `"` only for strings.
+  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_ordered_groups = nav_ordered_pages
+{%- 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 -%}
 
-{%- assign number_ordered_pages = "" | split: "" -%}
-{%- for group in nav_ordered_groups -%}
+{%- 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 string_ordered_pages = string_ordered_pages | concat: group.items -%}
+    {%- assign title_string_pages = group.items -%}
   {%- else -%}
-    {%- assign number_ordered_pages = number_ordered_pages | concat: group.items -%}
+    {%- assign title_number_pages = title_number_pages | concat: group.items -%}
   {%- endif -%}
 {%- endfor -%}
 
-{%- assign sorted_number_ordered_groups = number_ordered_pages
-      | sort: "nav_order" | group_by: "nav_order" -%}
+{%- unless title_number_pages == empty -%}
+  {%- assign title_number_pages = title_number_pages | sort: "title" -%}
+{%- endunless -%}
 
-{%- comment -%}
-  Group the string-ordered pages by `nav_order`, if non-nil, and otherwise `title`
-  (but appending the empty string to a numeric title to convert it to a string).
-  
-  Then sort the groups according to the site setting for case (in)sensitivity.
-{%- endcomment -%}
+{%- 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 string_ordered_groups = string_ordered_pages
-      | group_by_exp:"item", "item.nav_order | default: item.title | append: '' " -%}
+{%- assign pages_list = nav_number_pages | concat: nav_string_pages
+      | concat: title_number_pages | concat: title_string_pages -%}
 
-{%- if site.nav_sort == 'case_insensitive' -%}
-  {%- assign sorted_string_ordered_groups = string_ordered_groups
-        | sort_natural: "name" -%}
-{%- else -%}
-  {%- assign sorted_string_ordered_groups = string_ordered_groups
-        | sort:"name" -%}
-{%- endif -%}
+{%- assign first_level_pages = pages_list
+      | where_exp: "item", "item.parent == nil" -%}
+{%- assign second_level_pages = pages_list
+      | where_exp: "item", "item.parent != nil"
+      | where_exp: "item", "item.grand_parent == nil" -%}
+{%- assign third_level_pages = pages_list
+      | where_exp: "item", "item.grand_parent != nil" -%}
 
-{%- assign groups_list = sorted_number_ordered_groups
-      | concat: sorted_string_ordered_groups -%}
+{%- comment -%}
+  The order of sibling pages in `pages_list` determines the order of display of
+  links to them in lists of navigation links and in auto-generated TOCs.
+  
+  Note that Liquid evaluates conditions from right to left (and it does not allow
+  the use of parentheses). Some conditions are not so easy to express clearly...
+  
+  For example, consider the following condition:
+  
+    C: page.collection = = include.key and 
+       page.url = = node.url or 
+       page.grand_parent = = node.title or 
+       page.parent = = node.title and 
+       page.grand_parent = = nil
+ 
+  Here, `node` is a first-level page. The last part of the condition
+  -- namely: `page.parent = = node.title and page.grand_parent = = nil` --
+  is evaluated first; it holds if and only if `page` is a child of `node`.
+  
+  The condition `page.grand_parent = = node.title or ...` holds when 
+  `page` is a grandchild of node, OR `...` holds.
+  
+  The condition `page.url = = node.url or ...` holds when 
+  `page` is `node`, OR `...` holds.
+  
+  The condition C: `page.collection = = include.key and ...` holds when we are 
+  generating the nav links for a collection that includes `page`, AND `...` holds.
+{%- endcomment -%}
 
 <ul class="nav-list">
-  {%- for node_group in groups_list -%} 
-  {%- for node in node_group.items -%}
-    {%- if node.parent == nil -%}
-      {%- unless node.nav_exclude -%}
-      <li class="nav-list-item{% if page.collection == include.key and page.url == node.url or page.parent == node.title or page.grand_parent == node.title %} active{% endif %}">
+{%- for node in first_level_pages -%}
+    {%- unless node.nav_exclude -%}
+      <li class="nav-list-item{% if page.collection == include.key and page.url == node.url or page.grand_parent == node.title or page.parent == node.title and page.grand_parent == nil %} active{% endif %}">
         {%- if node.has_children -%}
           <a href="#" class="nav-list-expander" aria-label="toggle links in {{ node.title }} category">
             <svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg>
@@ -76,14 +169,9 @@
         {%- 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 = "" | split: "" -%}
-          {%- for parent_group in groups_list -%}
-            {%- assign children_list = children_list 
-                  | concat: parent_group.items
-                  | where: "parent", node.title
-                  | where_exp:"item", "item.grand_parent == nil" -%}
-          {%- endfor -%}
-          {%- if node.child_nav_order == 'desc' -%}
+          {%- assign children_list = second_level_pages
+                | where: "parent", node.title -%}
+          {%- if node.child_nav_order == 'desc' or node.child_nav_order == 'reversed' -%}
             {%- assign children_list = children_list | reverse -%}
           {%- endif -%}
           <ul class="nav-list ">
@@ -97,21 +185,17 @@
               {%- 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 -%}
-                {%- assign grandchildren_list = "" | split: "" -%}
-                {%- for grandparent_group in groups_list -%}
-                  {%- assign grandchildren_list = grandchildren_list
-                        | concat: grandparent_group.items
-                        | where: "parent", child.title
-                        | where: "grand_parent", node.title -%}
-                {%- endfor -%}
-                {%- if node.child_nav_order == 'desc' -%}
-                  {%- assign grandchildren_list = grandchildren_list | reverse -%}
+                {%- assign grand_children_list = third_level_pages
+                      | where: "parent", child.title
+                      | where: "grand_parent", node.title -%}
+                {%- 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">
-                {%- for grandchild in grandchildren_list -%}
-                  {%- unless grandchild.nav_exclude -%}
-                  <li class="nav-list-item {% if page.url == grandchild.url %} active{% endif %}">
-                    <a href="{{ grandchild.url | relative_url }}" class="nav-list-link{% if page.url == grand_child.url %} active{% endif %}">{{ grandchild.title }}</a>
+                {%- for grand_child in grand_children_list -%}
+                  {%- unless grand_child.nav_exclude -%}
+                  <li class="nav-list-item {% if page.url == grand_child.url %} active{% endif %}">
+                    <a href="{{ grand_child.url | relative_url }}" class="nav-list-link{% if page.url == grand_child.url %} active{% endif %}">{{ grand_child.title }}</a>
                   </li>
                   {%- endunless -%}
                 {%- endfor -%}
@@ -123,65 +207,45 @@
           </ul>
         {%- endif -%}
       </li>
-      {%- endunless -%}
-    {%- endif -%}
-  {%- endfor -%}
-  {%- endfor -%}
-  {%- assign nav_external_links = site.nav_external_links -%}
-  {%- for node in nav_external_links -%}
-    <li class="nav-list-item external">
-      <a href="{{ node.url | absolute_url }}" class="nav-list-link external">
-        {{ node.title }}
-        {% unless node.hide_icon %}<svg viewBox="0 0 24 24" aria-labelledby="svg-external-link-title"><use xlink:href="#svg-external-link"></use></svg>{% endunless %}
-      </a>
-    </li>
-  {%- endfor -%}
+    {%- endunless -%}
+{%- endfor -%}
 </ul>
 
-{%- if page.collection == include.key -%}
+{%- comment -%}
+  `page.collection` is the name of the Jekyll collection that contains the page,
+  if any, and otherwise nil. Similarly for `include.key`.
+  
+  If the current page is in the collection (if any) whose navigation is currently
+  being generated, the following code sets `first_level_url` to the URL used in
+  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,
+  reversing the order if needed.
+{%- endcomment -%}
 
-  {%- for node_group in groups_list -%}
-  {%- for node in node_group.items -%}
-    {%- if node.parent == nil -%}
-      {%- if page.grand_parent == node.title 
-              or page.parent == node.title
-              and page.grand_parent == nil -%}
+{%- if page.collection == include.key -%}
+  {%- for node in first_level_pages -%}
+      {%- if page.grand_parent == node.title or page.parent == node.title and page.grand_parent == nil -%}
         {%- assign first_level_url = node.url | relative_url -%}
       {%- endif -%}
       {%- if node.has_children -%}
-        {%- assign children_list = "" | split: "" -%}
-        {%- for parent_group in groups_list -%}
-          {%- assign children_list = children_list | concat: 
-                parent_group.items | where: "parent", node.title -%}
-        {%- endfor -%}
-        {%- if node.child_nav_order == 'desc' -%}
-          {%- assign children_list = children_list | reverse -%}
-        {%- endif -%}
+        {%- assign children_list = second_level_pages | where: "parent", node.title -%}
         {%- for child in children_list -%}
           {%- if child.has_children -%}
-            {%- if page.url == child.url
-                    or page.parent == child.title
-                    and page.grand_parent == child.parent -%}
+            {%- if page.url == child.url or page.parent == child.title and page.grand_parent == child.parent -%}
               {%- assign second_level_url = child.url | relative_url -%}
             {%- endif -%}
           {%- endif -%}
         {%- endfor -%}
       {%- endif -%}
-    {%- endif -%}
-  {%- endfor -%}
   {%- endfor -%}
-
-  {% if page.has_children == true and page.has_toc != false %}
-    {%- assign toc_list = "" | split: "" -%}
-    {%- for parent_group in groups_list -%}
-      {%- assign toc_list = toc_list
-            | concat: parent_group.items
-            | where: "parent", page.title
-            | where: "grand_parent", page.parent -%}
-    {%- endfor -%}
-    {%- if node.child_nav_order == 'desc' -%}
+  {%- if page.has_children == true and page.has_toc != false -%}
+    {%- assign toc_list = pages_list
+          | where: "parent", page.title
+          | where_exp: "item", "item.grand_parent == page.parent" -%}
+    {%- if page.child_nav_order == 'desc' or page.child_nav_order == 'reversed' -%}
       {%- assign toc_list = toc_list | reverse -%}
     {%- endif -%}
   {%- endif -%}
-
 {%- endif -%}

data/_includes/toc_heading_custom.html

@@ -0,0 +1 @@
+<h2 class="text-delta">Table of contents</h2>

data/_includes/vendor/anchor_headings.html

@@ -24,7 +24,7 @@
     OTHER DEALINGS IN THE SOFTWARE.
   {% endcomment %}
   {% comment %}
-    Version 1.0.7
+    Version 1.0.12
       https://github.com/allejo/jekyll-anchor-headings
 
     "Be the pull request you wish to see in the world." ~Ben Balter
@@ -37,6 +37,8 @@
 
     Optional Parameters:
       * beforeHeading (bool)   : false  - Set to true if the anchor should be placed _before_ the heading's content
+      * headerAttrs   (string) :  ''    - Any custom HTML attributes that will be added to the heading tag; you may NOT use `id`;
+                                          the `%heading%` and `%html_id%` placeholders are available
       * anchorAttrs   (string) :  ''    - Any custom HTML attributes that will be added to the `<a>` tag; you may NOT use `href`, `class` or `title`;
                                           the `%heading%` and `%html_id%` placeholders are available
       * anchorBody    (string) :  ''    - The content that will be placed inside the anchor; the `%heading%` placeholder is available
@@ -46,6 +48,7 @@
       * h_max         (int)    :  6     - The maximum header level to build an anchor for; any header greater than this value will be ignored
       * bodyPrefix    (string) :  ''    - Anything that should be inserted inside of the heading tag _before_ its anchor and content
       * bodySuffix    (string) :  ''    - Anything that should be inserted inside of the heading tag _after_ its anchor and content
+      * generateId    (true)   :  false - Set to true if a header without id should generate an id to use.
 
     Output:
       The original HTML with the addition of anchors inside of all of the h1-h6 headings.
@@ -54,6 +57,7 @@
   {% assign minHeader = include.h_min | default: 1 %}
   {% assign maxHeader = include.h_max | default: 6 %}
   {% assign beforeHeading = include.beforeHeading %}
+  {% assign headerAttrs = include.headerAttrs %}
   {% assign nodes = include.html | split: '<h' %}
 
   {% capture edited_headings %}{% endcapture %}
@@ -84,17 +88,41 @@
 
     {% capture _closingTag %}</h{{ headerLevel }}>{% endcapture %}
     {% assign _workspace = node | split: _closingTag %}
-    {% assign _idWorkspace = _workspace[0] | split: 'id="' %}
-    {% assign _idWorkspace = _idWorkspace[1] | split: '"' %}
-    {% assign html_id = _idWorkspace[0] %}
-
     {% capture _hAttrToStrip %}{{ _workspace[0] | split: '>' | first }}>{% endcapture %}
     {% assign header = _workspace[0] | replace: _hAttrToStrip, '' %}
+    {% assign escaped_header = header | strip_html | strip %}
+
+    {% assign _classWorkspace = _workspace[0] | split: 'class="' %}
+    {% assign _classWorkspace = _classWorkspace[1] | split: '"' %}
+    {% assign _html_class = _classWorkspace[0] %}
+
+    {% if _html_class contains "no_anchor" %}
+      {% assign skip_anchor = true %}
+    {% else %}
+      {% assign skip_anchor = false %}
+    {% endif %}
+
+    {% assign _idWorkspace = _workspace[0] | split: 'id="' %}
+    {% if _idWorkspace[1] %}
+      {% assign _idWorkspace = _idWorkspace[1] | split: '"' %}
+      {% assign html_id = _idWorkspace[0] %}
+    {% elsif include.generateId %}
+      <!-- If the header did not have an id we create one. -->
+      {% assign html_id = escaped_header | slugify %}
+      {% if html_id == "" %}
+        {% assign html_id = false %}
+      {% endif %}
+      {% capture headerAttrs %}{{ headerAttrs }} id="%html_id%"{% endcapture %}
+    {% endif %}
 
     <!-- Build the anchor to inject for our heading -->
     {% capture anchor %}{% endcapture %}
 
-    {% if html_id and headerLevel >= minHeader and headerLevel <= maxHeader %}
+    {% if skip_anchor == false and html_id and headerLevel >= minHeader and headerLevel <= maxHeader %}
+      {% if headerAttrs %}
+        {% capture _hAttrToStrip %}{{ _hAttrToStrip | split: '>' | first }} {{ headerAttrs | replace: '%heading%', escaped_header | replace: '%html_id%', html_id }}>{% endcapture %}
+      {% endif %}
+
       {% capture anchor %}href="#{{ html_id }}"{% endcapture %}
 
       {% if include.anchorClass %}
@@ -102,14 +130,14 @@
       {% endif %}
 
       {% if include.anchorTitle %}
-        {% capture anchor %}{{ anchor }} title="{{ include.anchorTitle | replace: '%heading%', header }}"{% endcapture %}
+        {% capture anchor %}{{ anchor }} title="{{ include.anchorTitle | replace: '%heading%', escaped_header }}"{% endcapture %}
       {% endif %}
 
       {% if include.anchorAttrs %}
-        {% capture anchor %}{{ anchor }} {{ include.anchorAttrs | replace: '%heading%', header | replace: '%html_id%', html_id }}{% endcapture %}
+        {% capture anchor %}{{ anchor }} {{ include.anchorAttrs | replace: '%heading%', escaped_header | replace: '%html_id%', html_id }}{% endcapture %}
       {% endif %}
 
-      {% capture anchor %}<a {{ anchor }}>{{ include.anchorBody | replace: '%heading%', header | default: '' }}</a>{% endcapture %}
+      {% capture anchor %}<a {{ anchor }}>{{ include.anchorBody | replace: '%heading%', escaped_header | default: '' }}</a>{% endcapture %}
 
       <!-- In order to prevent adding extra space after a heading, we'll let the 'anchor' value contain it -->
       {% if beforeHeading %}
@@ -120,15 +148,15 @@
     {% endif %}
 
     {% capture new_heading %}
-      <h{{ _hAttrToStrip }}
-        {{ include.bodyPrefix }}
-        {% if beforeHeading %}
-          {{ anchor }}{{ header }}
-        {% else %}
-          {{ header }}{{ anchor }}
-        {% endif %}
-        {{ include.bodySuffix }}
-      </h{{ headerLevel }}>
+<h{{ _hAttrToStrip }}
+  {{ include.bodyPrefix }}
+  {% if beforeHeading %}
+    {{ anchor }}{{ header }}
+  {% else %}
+    {{ header }}{{ anchor }}
+  {% endif %}
+  {{ include.bodySuffix }}
+</h{{ headerLevel }}>
     {% endcapture %}
 
     <!--