Update documentation for licensing and concurrent API calls on self-hosted, update just the docs template

src/Gemfile.lock

@@ -140,6 +140,7 @@ GEM
       ethon (>= 0.9.0, < 0.16.0)
     unicode-display_width (2.6.0)
     webrick (1.9.2)
+    wdm (0.2.0)
     yell (2.2.2)
     zeitwerk (2.7.4)
 
@@ -155,6 +156,7 @@ DEPENDENCIES
   jekyll-include-cache
   jekyll-redirect-from
   webrick (~> 1.9)
+  wdm (>= 0.2.0)
 
 BUNDLED WITH
    2.3.26

src/_includes/components/aux_nav.html

@@ -1,23 +1,15 @@
 <nav aria-label="Auxiliary" class="aux-nav">
   <ul class="aux-nav-list">
     {% for link in site.aux_links %}
-    <li class="aux-nav-list-item">
-      <a
-        href="{{ link.last }}"
-        class="site-button"
-        {%
-        if
-        site.aux_links_new_tab
-        %}
-        target="_blank"
-        rel="noopener noreferrer"
-        {%
-        endif
-        %}
-      >
-        {{ link.first }}
-      </a>
-    </li>
+      <li class="aux-nav-list-item">
+        <a href="{{ link.last }}" class="site-button"
+          {% if site.aux_links_new_tab %}
+          target="_blank" rel="noopener noreferrer"
+          {% endif %}
+        >
+          {{ link.first }}
+        </a>
+      </li>
     {% endfor %}
   </ul>
 </nav>

src/_includes/components/breadcrumbs.html

@@ -1,30 +1,96 @@
-{%- comment -%} Include as: {%- include components/breadcrumbs.html -%} Depends
-on: page, site. Results in: HTML for the breadcrumbs component. Overwrites:
-pages_list, parent_page, grandparent_page. {%- endcomment -%} {%- if page.url !=
-"/" and page.parent -%} {%- assign pages_list = site[page.collection] | default:
-site.html_pages | where_exp: "item", "item.title != nil" | where_exp: "item",
-"item.has_children != nil" -%} {%- if page.grand_parent -%} {%- assign
-parent_page = pages_list | where: "title", page.parent | where: "parent",
-page.grand_parent | first -%} {%- assign grandparent_page = pages_list | where:
-"title", page.grand_parent | first -%} {%- else -%} {%- assign parent_page =
-pages_list | where: "title", page.parent | where_exp: "item", "item.parent ==
-nil" | first -%} {%- endif -%}
+{%- comment -%}
+  Include as: {%- include components/breadcrumbs.html -%}
+  Depends on: page, site.
+  Includes: components/site_nav.html.
+  Results in: HTML for the breadcrumbs component.
+  Overwrites:
+    nav_list_link, site_nav, nav_list_simple, nav_list_link_class, nav_category,
+    nav_anchor_splits, nav_breadcrumbs, nav_split, nav_split_next, nav_split_test,
+    nav_breadcrumb_link, nav_list_end_less, nav_list_end_count, nav_end_index, nav_breadcrumb.
+{%- endcomment -%}
+
+{%- if page.url != "/" and page.parent and page.title -%}
+
+{%- capture site_nav -%}
+{%- include_cached components/site_nav.html all=true -%}
+{%- endcapture -%}
+
+{%- capture nav_list_link -%}
+<a href="{{ page.url | relative_url }}" class="nav-list-link">
+{%- endcapture -%}
+
+{%- capture nav_list_simple -%}
+<ul class="nav-list">
+{%- endcapture -%}
+
+{%- capture nav_list_link_class %} class="nav-list-link">
+{%- endcapture -%}
+
+{%- capture nav_category -%}
+<div class="nav-category">
+{%- endcapture -%}
+
+{%- assign nav_anchor_splits =
+      site_nav | split: nav_list_link |
+      first | split: nav_category |
+      last | split: "</a>" -%}
+
+{%- comment -%}
+  The ordinary pages (if any) and the collections pages (if any) are separated by
+  occurrences of nav_category.
+
+  Any ancestor nav-links of the page are contained in the last group of pages,
+  immediately preceding nav-lists. After splitting at "</a>", the anchor that
+  was split is a potential ancestor link when the following split starts with
+  a nav-list. 
+
+  The array nav_breadcrumbs is the stack of current potential ancestors of the
+  current page. A split that contains one or more "</ul>"s requires that number
+  of potential ancestors to be popped from the stack.
+
+  The number of occurrences of a string in nav_split_next is computed by removing
+  them all, then dividing the resulting size difference by the length of the string.
+{%- endcomment %}
+
+{%- assign nav_breadcrumbs = "" | split: "" -%}
+
+{%- for nav_split in nav_anchor_splits -%}
+{%- unless forloop.last -%}
+
+{%- assign nav_split_next = nav_anchor_splits[forloop.index] | strip -%}
+
+{%- assign nav_split_test =
+      nav_split_next | remove_first: nav_list_simple | prepend: nav_list_simple -%}
+{%- if nav_split_test == nav_split_next -%}
+  {%- assign nav_breadcrumb_link =
+        nav_split | split: "<a " | last | prepend: "<a " |
+        replace: nav_list_link_class, ">" | append: "</a>" -%}
+  {%- assign nav_breadcrumbs = nav_breadcrumbs | push: nav_breadcrumb_link -%}
+{%- endif -%}
+
+{%- if nav_split_next contains "</ul>" -%}
+  {%- assign nav_list_end_less = nav_split_next | remove: "</ul>" -%}
+  {%- assign nav_list_end_count =
+        nav_split_next.size | minus: nav_list_end_less.size | divided_by: 5 -%}
+  {% for nav_end_index in (1..nav_list_end_count) %}
+    {%- assign nav_breadcrumbs = nav_breadcrumbs | pop -%}
+  {%- endfor -%}
+{%- endif -%}
+
+{%- endunless -%}
+{%- endfor -%}
 
 <nav aria-label="Breadcrumb" class="breadcrumb-nav">
   <ol class="breadcrumb-nav-list">
-    {% if page.parent -%} {%- if page.grand_parent %}
-    <li class="breadcrumb-nav-list-item">
-      <a href="{{ grandparent_page.url | relative_url }}"
-        >{{ page.grand_parent }}</a
-      >
-    </li>
-    {%- endif %}
-    <li class="breadcrumb-nav-list-item">
-      <a href="{{ parent_page.url | relative_url }}">{{ page.parent }}</a>
-    </li>
-    {% endif -%}
+    {%- for nav_breadcrumb in nav_breadcrumbs %}
+    <li class="breadcrumb-nav-list-item">{{ nav_breadcrumb }}</li>
+    {%- endfor %}
     <li class="breadcrumb-nav-list-item"><span>{{ page.title }}</span></li>
   </ol>
 </nav>
 
+{% if site.nav_error_report %}
+{{ nav_error_report }}
+{% endif %}
+
 {%- endif -%}

src/_includes/components/children_nav.html

@@ -1,20 +1,90 @@
-{%- comment -%} Include as: {%- include components/children_nav.html -%} Depends
-on: page, site. Results in: HTML for the children-navigation component.
-Includes: sorted_pages.html toc_heading_custom.html Overwrites: child_pages. {%-
-endcomment -%} {%- if page.has_children == true and page.has_toc != false -%}
-{%- assign child_pages = site[page.collection] | default: site.html_pages |
-where: "parent", page.title | where: "grand_parent", page.parent -%} {%- include
-sorted_pages.html pages = child_pages -%} {%- if page.child_nav_order == 'desc'
-or page.child_nav_order == 'reversed' -%} {%- assign sorted_pages = sorted_pages
-| reverse -%} {%- endif -%} {%- endif -%}
-
-<hr />
+{%- comment -%}
+  Include as: {%- include components/children_nav.html -%}
+  Depends on: page, site, nav_breadcrumbs.
+  Results in: HTML for the children-navigation component.
+  Includes: components/nav/sorted.html, toc_heading_custom.html.
+  Overwrites:
+    nav_ancestor_links, nav_top_node_titles, nav_child_candidates, nav_children,
+    nav_child, nav_child_ok, nav_child_ancestor, nav_sorted.
+{%- endcomment -%}
+
+{%- comment -%}
+  Whether a page has any children is checked efficiently by inspecting the cached
+  site_nav. If the page has no children, nav_children is set to an empty array;
+  otherwise nav_children is left unset. (The site_nav is rendered the first time
+  it is included, and that may overwrite various variables.)
+{%- endcomment -%}
+
+{%- if page.has_children == false -%}
+  {%- assign nav_children = "" | split: "" -%}
+{%- else -%}
+
+  {%- capture site_nav -%}
+  {%- include_cached components/site_nav.html all=true -%}
+  {%- endcapture -%}
+
+  {%- assign nav_children = nil -%}
+
+  {%- capture nav_list_link -%}
+  <a href="{{ page.url | relative_url }}" class="nav-list-link">
+  {%- endcapture -%}
+
+  {%- capture nav_list_simple -%}
+  <ul class="nav-list">
+  {%- endcapture -%}
+
+  {%- assign nav_child_start = site_nav
+        | split: nav_list_link | last
+        | split: "</a>" | slice: 1 | first -%}
+
+  {%- assign nav_child_test = nav_child_start 
+        | remove_first: nav_list_simple | prepend: nav_list_simple -%}
+
+  {%- if nav_child_start != nav_child_test -%}
+    {%- assign nav_children = "" | split: "" -%}
+  {%- endif -%}
+
+{%- endif -%}
+
+{%- unless nav_children -%}
+
+  {%- comment -%}
+    The layout is assumed to include components/breadcrumbs.html before this file,
+    otherwise it needs to be included here.
+  {%- endcomment -%}
+
+  {%- assign nav_ancestors = "" | split: "" -%}
+  {%- for nav_link in nav_breadcrumbs -%}
+    {%- assign nav_title = nav_link | split: ">" | slice: 1 | first | append: ">" | remove: "</a>" -%}
+    {%- assign nav_ancestors = nav_ancestors | push: nav_title -%}
+  {%- endfor -%}
+
+  {%- assign nav_parenthood = site[page.collection] | default: site.html_pages
+    | where_exp: "item", "item.title != nil" | group_by: "parent" -%}
+
+  {%- assign nav_top_nodes = nav_parenthood
+      | where_exp: "item", "item.name == ''" | map: "items" | first -%}
+
+  {% assign nav_top_node_titles = nav_top_nodes | map: "title" -%}
+
+  {%- include components/nav/children.html node=page ancestors=nav_ancestors all=true -%}
+
+{%- endunless -%}
+
+{%- if nav_children.size >= 1 -%}
+
+  {%- if page.child_nav_order == 'desc' or page.child_nav_order == 'reversed' -%}
+    {%- assign nav_children = nav_children | reverse -%}
+  {%- endif -%}
+
+<hr>
 {% include toc_heading_custom.html %}
 <ul>
-  {% for child in sorted_pages %}
+  {% for nav_child in nav_children %}
   <li>
-    <a href="{{ child.url | relative_url }}">{{ child.title }}</a>{% if
-    child.summary %} - {{ child.summary }}{% endif %}
+    <a href="{{ nav_child.url | relative_url }}">{{ nav_child.title }}</a>{% if nav_child.summary %} - {{ nav_child.summary }}{% endif %}
   </li>
   {% endfor %}
 </ul>
+
+{%- endif -%}

src/_includes/components/footer.html

@@ -1,31 +1,34 @@
-{% capture footer_custom %} {%- include footer_custom.html -%} {% endcapture %}
-{% if footer_custom != "" or site.last_edit_timestamp or site.gh_edit_link %}
-<div id="footer">
-  {% if site.back_to_top %}
-  <p><a href="#top" id="back-to-top">{{ site.back_to_top_text }}</a></p>
-  {% endif %} {{ footer_custom }} {% if site.last_edit_timestamp or
-  site.gh_edit_link %}
-  <div class="d-flex mt-2">
-    {% if site.last_edit_timestamp and site.last_edit_time_format and
-    page.last_modified_date %}
-    <p class="text-small text-grey-dk-000 mb-0 mr-2">
-      Page last modified:
-      <span class="d-inline-block"
-        >{{ page.last_modified_date | date: site.last_edit_time_format }}</span
-      >.
-    </p>
-    {% endif %} {% if site.gh_edit_link and site.gh_edit_link_text and
-    site.gh_edit_repository and site.gh_edit_branch and site.gh_edit_view_mode
-    %}
-    <p class="text-small text-grey-dk-000 mb-0">
-      <a
-        href="{{ site.gh_edit_repository }}/{{ site.gh_edit_view_mode }}/{{ site.gh_edit_branch }}{% if site.gh_edit_source %}/{{ site.gh_edit_source }}{% endif %}{% if page.collection and site.collections_dir %}/{{ site.collections_dir }}{% endif %}/{{ page.path }}"
-        id="edit-this-page"
-        >{{ site.gh_edit_link_text }}</a
-      >
-    </p>
+{% capture footer_custom %}
+  {%- include footer_custom.html -%}
+{% endcapture %}
+{% if footer_custom != "" or site.last_edit_timestamp or site.gh_edit_link or site.back_to_top %}
+  <hr>
+  <footer>
+    {% if site.back_to_top %}
+      <p><a href="#top" id="back-to-top">{{ site.back_to_top_text }}</a></p>
     {% endif %}
-  </div>
-  {% endif %}
-</div>
+
+    {{ footer_custom }}
+
+    {% if site.last_edit_timestamp or site.gh_edit_link %}
+      <div class="d-flex mt-2">
+        {% if site.last_edit_timestamp and site.last_edit_time_format and page.last_modified_date %}
+          <p class="text-small text-grey-dk-000 mb-0 mr-2">
+            Page last modified: <span class="d-inline-block">{{ page.last_modified_date | date: site.last_edit_time_format }}</span>.
+          </p>
+        {% endif %}
+        {% if
+          site.gh_edit_link and
+          site.gh_edit_link_text and
+          site.gh_edit_repository and
+          site.gh_edit_branch and
+          site.gh_edit_view_mode
+        %}
+          <p class="text-small text-grey-dk-000 mb-0">
+            <a href="{{ site.gh_edit_repository }}/{{ site.gh_edit_view_mode }}/{{ site.gh_edit_branch }}{% if site.gh_edit_source %}/{{ site.gh_edit_source }}{% endif %}{% if page.collection and site.collections_dir %}/{{ site.collections_dir }}{% endif %}/{{ page.path }}" id="edit-this-page">{{ site.gh_edit_link_text }}</a>
+          </p>
+        {% endif %}
+      </div>
+    {% endif %}
+  </footer>
 {% endif %}

src/_includes/components/header.html

@@ -1,7 +1,11 @@
 <div id="main-header" class="main-header">
-  {% if site.search_enabled != false %} {% include components/search_header.html
-  %} {% else %}
-  <div></div>
-  {% endif %} {% include header_custom.html %} {% if site.aux_links %} {%
-  include components/aux_nav.html %} {% endif %}
+  {% if site.search_enabled != false %}
+    {% include components/search_header.html %}
+  {% else %}
+    <div></div>
+  {% endif %}
+  {% include header_custom.html %}
+  {% if site.aux_links %}
+    {% include components/aux_nav.html %}
+  {% endif %}
 </div>

src/_includes/components/mermaid.html

@@ -1,12 +1,18 @@
-{% comment %} The complexity of this file comes from a breaking change in
-Mermaid v10; mermaid.init has been deprecated (and supposedly, didn't work
-earlier?). So, we check whether the user's Mermaid version is >= 10; if not, we
-fall back to the previous init syntax. If a user is using a custom mermaid file
-and doesn't specify a version, we default to the < v10 behaviour. Users who use
-version v10 or above should specify this in the version key. {% endcomment %} {%
-if site.mermaid.version %} {% assign mermaid_major_version =
-site.mermaid.version | split: "." | first | plus: 0 %} {% else %} {% assign
-mermaid_major_version = 9 %} {% endif %} {% if mermaid_major_version > 9 %}
+{% comment %}
+The complexity of this file comes from a breaking change in Mermaid v10; mermaid.init has been deprecated (and supposedly, didn't work earlier?).
+
+So, we check whether the user's Mermaid version is >= 10; if not, we fall back to the previous init syntax.
+
+If a user is using a custom mermaid file and doesn't specify a version, we default to the < v10 behaviour. Users who use version v10 or above should specify this in the version key.
+{% endcomment %}
+
+{% if site.mermaid.version %}
+  {% assign mermaid_major_version = site.mermaid.version | split: "." | first | plus: 0 %}
+{% else %}
+  {% assign mermaid_major_version = 9 %}
+{% endif %}
+
+{% if mermaid_major_version > 9 %}
 
 <script type="module">
   {% if site.mermaid.path %}
@@ -22,10 +28,12 @@
   });
 </script>
 
-{% else %} {% if site.mermaid.path %}
-<script src="{{ site.mermaid.path | relative_url }}"></script>
 {% else %}
-<script src="https://cdn.jsdelivr.net/npm/mermaid@{{ site.mermaid.version }}/dist/mermaid.min.js"></script>
+
+{% if site.mermaid.path %}
+  <script src="{{ site.mermaid.path | relative_url }}"></script>
+{% else %}
+  <script src="https://cdn.jsdelivr.net/npm/mermaid@{{ site.mermaid.version }}/dist/mermaid.min.js"></script>
 {% endif %}
 
 <script>