Quicker build (#1397)

This PR uses the cached site-nav to determine the position of each page in the navigation hierarchy. [Profiling](https://just-the-docs.github.io/just-the-docs-tests/tests/profiles/index/) shows that it significantly reduces the v0.7.0 build time for larger sites – especially with Jekyll 3. The improvement is due mainly to the elimination of loops and filters that depended on the entire site. For example: - [endoflife.date](https://just-the-docs.github.io/just-the-docs-tests/tests/profiles/endoflife.date/index/) drops from 32s to 11s - [machinetranslate.org](https://just-the-docs.github.io/just-the-docs-tests/tests/profiles/machinetranslate.org/index/) drops from 267s to ~~73s~~ 56s ### Testing [Just the Docs Tests](https://just-the-docs.github.io/just-the-docs-tests/) is currently built using this PR branch. With JS disabled, the highlighting and unfolding of the navigation panel should be as with v0.7.0. A diff of the tests site built with this PR branch compared to v0.7.0 should report no significant changes. For more rigorous testing, diffs of variants of the tests site should also be inspected.
2025-04-08 04:51:23 -06:00 · 2024-02-23 06:56:52 +01:00 · 2024-02-23 06:56:52 +01:00 · 820d256bcd
commit 820d256bcd
parent b8f6f2b75c
3 changed files with 269 additions and 123 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -19,6 +19,7 @@ Code changes to `main` that are *not* in the latest release:

 - Added: configurable keyboard shortcut to focus search input by [@kcromanpl-bajra] in [#1411]
 - Fixed: incorrect navigation when `.html` omitted from URL by [@pdmosses] in [#1374]
+- Fixed: quicker build by [@pdmosses] in [#1397]
 - Fixed: incorrect positioning of clickable area for navigation links on Safari by [@mattxwang] in [#1403]

 Docs changes made since the latest release:
@ -34,6 +35,7 @@ Docs changes made since the latest release:

 [#1374]: https://github.com/just-the-docs/just-the-docs/pull/1374
 [#1390]: https://github.com/just-the-docs/just-the-docs/pull/1390
+[#1397]: https://github.com/just-the-docs/just-the-docs/pull/1397
 [#1403]: https://github.com/just-the-docs/just-the-docs/pull/1403
 [#1411]: https://github.com/just-the-docs/just-the-docs/pull/1411

--- a/_includes/components/breadcrumbs.html
+++ b/_includes/components/breadcrumbs.html
@ -8,8 +8,91 @@

 {%- if page.url != "/" and page.parent -%}

-  {%- assign pages_list = site[page.collection] | default: site.html_pages -%}
+{%- capture nav_list_link -%}
+<a href="{{ page.url | relative_url }}" class="nav-list-link">
+{%- endcapture -%}

+{%- capture site_nav -%}
+{%- include_cached components/site_nav.html -%}
+{%- endcapture -%}
+
+{%- if site_nav contains nav_list_link -%}
+
+  {%- 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] | trim -%}
+
+  {%- 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 -%}
+
+  {%- assign nav_parent_link = nav_breadcrumbs[-1] -%}
+  {%- assign nav_grandparent_link = nav_breadcrumbs[-2] -%}
+
+{%- else -%}
+
+  {%- comment -%}
+    Pages whose links are excluded from the main navigation may still have
+    breadcrumbs. Determining them appears to require inspecting the front matter
+    of all the pages in the same group. For sites with 100s of pages, this is too
+    inefficient in Jekyll 3 (also when the for-loop is replaced by where-filters).
+  {%- endcomment -%}
+
+  {%- assign pages_list = site[page.collection] | default: site.html_pages -%}
+  
  {%- assign parent_page = nil -%}
  {%- assign grandparent_page = nil -%}

@ -35,15 +118,25 @@
    {%- endif -%}

  {%- endfor -%}
+  
+  {%- capture nav_parent_link -%}
+    <a href="{{ parent_page.url | relative_url }}">{{ page.parent }}</a>
+  {%- endcapture -%}
+
+  {%- if page.grand_parent %}
+    {%- capture nav_grandparent_link -%}
+      <a href="{{ grandparent_page.url | relative_url }}">{{ page.grand_parent }}</a>
+    {%- endcapture -%}
+  {%- endif -%}
+
+{%- endif -%}

 <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>
+  {%- if nav_grandparent_link %}
+    <li class="breadcrumb-nav-list-item">{{ nav_grandparent_link }}</li>
  {%- endif %}
-    <li class="breadcrumb-nav-list-item"><a href="{{ parent_page.url | relative_url }}">{{ page.parent }}</a></li>
-  {% endif -%}
+    <li class="breadcrumb-nav-list-item">{{ nav_parent_link }}</li>
    <li class="breadcrumb-nav-list-item"><span>{{ page.title }}</span></li>
  </ol>
 </nav>
--- a/_includes/css/activation.scss.liquid
+++ b/_includes/css/activation.scss.liquid
@ -1,19 +1,17 @@
 {%- comment -%}
  Include as: {%- include css/activation.scss.liquid -%}
-  Depends on: page, site.
-  Results in: page-dependent (non-nested) CSS rules for inclusion in a head style element,
-    which needs to be suppressed when JS is enabled.
-  Includes:
-    sorted_pages.html.
+  Depends on: page.
+  Results in: page-dependent CSS rules for inclusion in a style element,
+    which needs to be disabled when JS is enabled.
+  Includes: components/site_nav.html.
  Overwrites: 
-    activation_no_nav_link, activation_pages, activation_pages_top_size, activation_page, activation_title,
-    activation_first_level, activation_second_level, activation_third_level,
-    activation_first_level_reversed, activation_second_level_reversed,
-    activation_first_level_index, activation_second_level_index, activation_third_level_index,
-    activation_index, activation_collection_prefix, activation_other_collection_prefix.
+    activation_no_nav_link, nav_list_link, site_nav,
+    nav_list, nav_list_end, nav_list_item, nav_category_list,
+    nav_list_link_prefix, nav_splits, nav_split, nav_levels,
+    nav_list_less, nav_list_count, nav_end_less, nav_end_count,
+    nav_index, nav_slice_size,
+    activation_collection_prefix, activation_other_collection_prefix.
  Should not be cached, because it depends on page.
-  (For a site with only top-level pages, the rendering of this file is always empty.
-  This property could be detected, and used to reduce the build time for such sites.)
 {%- endcomment -%}

 {%- comment -%}
@ -37,89 +35,163 @@
 {%- endif %}
 {% endcapture -%}

-{%- if page.title == nil or page.nav_exclude == true -%}
+{%- capture nav_list_link -%}
+<a href="{{ page.url | relative_url }}" class="nav-list-link">
+{%- endcapture -%}

-{{ activation_no_nav_link }}
+{%- capture site_nav -%}
+{%- include_cached components/site_nav.html -%}
+{%- endcapture -%}

-{%- else -%}
+{%- if site_nav contains nav_list_link -%}

-{%- assign activation_pages = site[page.collection]
-      | default: site.html_pages
-      | where_exp: "item", "item.title != nil"
-      | where_exp: "item", "item.nav_exclude != true" -%}
+{%- capture nav_list -%}
+<ul class="nav-list
+{%- endcapture -%}

-{%- assign activation_first_level_index = nil -%}
-{%- assign activation_second_level_index = nil -%}
-{%- assign activation_third_level_index = nil -%}
-{%- assign activation_first_level_reversed = nil -%}
-{%- assign activation_second_level_reversed = nil -%}
+{%- assign nav_list_end = "</ul>" -%}
+
+{%- capture nav_list_item -%}
+<li class="nav-list-item
+{%- endcapture -%}
+
+{%- capture nav_category_list -%}
+<ul class="nav-list nav-category-list">
+{%- endcapture -%}
+
+{%- assign nav_list_link_prefix =
+      site_nav | split: nav_list_link | first | append: nav_list_link -%}
+
+{%- assign nav_splits =
+      nav_list_link_prefix | split: nav_list_item | pop -%}
+
+{%- assign nav_levels = "" | split: "" | push: 1 -%}
+
+{%- comment -%}
+  The pattern of occurrences of list and list-item tags in the site_nav string
+  is included in the language defined by the following context-free grammar:
+  
+    site_nav = PAGES? EXTERNALS? COLLECTION*
+
+    PAGES = nav_list (nav_list_item PAGES?)+ nav_list_end
+
+    EXTERNALS = nav_list nav_list_item+ nav_list_end
+
+    COLLECTION = nav_list (nav_list_item PAGES?)* nav_list_end
+               | nav_category_list 
+                   nav_list_item nav_list (nav_list_item PAGES?)* nav_list_end
+                 nav_list_end
+  
+  To determine the path in the site_nav to the nav_list_link for the current page,
+  the prefix of nav_list_link in site_nav is split at each nav_list_item to give
+  an array of nav_splits.
+  
+  In site_nav, occurrences of nav_list must be separated by at least one
+  nav_list_item or nav_list_end. Moreover, when a nav_list_end is followed by a
+  nav_list without an intervening nav_list_item, that nav_list must start either
+  a list of external links or a collection. And when a nav_list is followed by a
+  nav_list_end without an intervening nav_list_item, they form an empty collection.
+  
+  nav_levels is the path determined by the previously inspected nav_splits.
+  How many times nav_list and nav_list_end occur in the current nav_split 
+  determines how to update the path.
+  
+  A nav_split can contain any number of empty non-foldable collections.
+  The path element produced by the outer nav_list of a foldable collection is
+  irrelevant; it is set to zero and subsequently removed.
+    
+  The number of occurrences of a string in a nav_split is computed by removing
+  them all, then dividing the resulting size difference by the length of the string.
+  
+  Case analysis on (nav_list_count, nav_list_end_count):
+  
+  - when (0, 0), the nav_split was between two nav_list_items at the same level;
+  
+  - when (0, N+1), all the nav_list_ends in the nav_split are in PAGES or in one
+    COLLECTION;
+    
+  - when (M+1, 0), M must be 0 (because two nav_lists in the same nav_split must
+    be separated by at least one nav_list_end);
+    
+  - when (M+1, N+1), the nav_split must contain either:
+    - the end of PAGES followed by the start of EXTERNALS, or
+    - the end of PAGES followed by the start of a COLLECTION, or
+    - the end of EXTERNALS followed by the start of a COLLECTION, or
+    - the end of one COLLECTION followed by the start of another, or
+    - (in the first nav_split) one or more empty non-foldable COLLECTIONS
+      followed by the start of a COLLECTION.
+    In general, nav_levels[0] here needs to be incremented by nav_list_count.
+    However, a nav_split that contains the end of an empty foldable collection
+    followed by the just the start of a collection has two occurrences of nav_list,
+    and the increment needs to be one less; similarly when the first nav_split
+    starts with an empty non-foldable collection.
+{%- endcomment %}
+
+{%- for nav_split in nav_splits -%}
+
+  {%- assign nav_list_less = nav_split | remove: nav_list -%}
+  {%- assign nav_list_count =
+        nav_split.size | minus: nav_list_less.size | 
+        divided_by: nav_list.size -%}
+
+  {%- assign nav_list_end_less = nav_split | remove: nav_list_end -%}
+  {%- assign nav_list_end_count =
+        nav_split.size | minus: nav_list_end_less.size | 
+        divided_by: nav_list_end.size -%}
+
+  {%- if nav_list_count == 0 and nav_list_end_count == 0 -%}
+
+    {%- assign nav_index = nav_levels[-1] | plus: 1 -%}
+    {%- assign nav_levels = nav_levels | pop | push: nav_index -%}
+
+  {%- elsif nav_list_count == 0 and nav_list_end_count >= 1 -%}
+
+    {%- assign nav_slice_size = nav_levels.size | minus: nav_list_end_count -%}
+    {%- assign nav_levels = nav_levels | slice: 0, nav_slice_size -%}
+    {%- assign nav_index = nav_levels[-1] | plus: 1 -%}
+    {%- assign nav_levels = nav_levels | pop | push: nav_index -%}
+
+  {%- elsif nav_list_count == 1 and nav_list_end_count == 0 -%}
+
+    {%- if nav_split contains nav_category_list -%}
+      {%- assign nav_levels = nav_levels | push: 0 -%}
+    {%- else -%}
+      {%- assign nav_levels = nav_levels | push: 1 -%}
+    {%- endif -%}
+
+  {%- elsif nav_list_count >= 1 and nav_list_end_count >= 1 -%}
+
+    {%- assign nav_index = nav_levels[0] | plus: nav_list_count -%}
+    {%- if nav_levels[-1] == 0 or forloop.first -%}
+      {%- assign nav_index = nav_index | minus: 1 -%}
+    {%- endif -%}
+    {%- assign nav_levels = nav_levels | slice: 0, 0 | push: nav_index -%}
+    {%- if nav_split contains nav_category_list -%}
+      {%- assign nav_levels = nav_levels | push: 0 -%}
+    {%- else -%}
+      {%- assign nav_levels = nav_levels | push: 1 -%}
+    {%- endif -%}
+
+  {%- endif -%}
+
+{%- endfor -%}
+
+{%- assign nav_levels = nav_levels | where_exp: "item", "item >= 1" -%}
+
+{%- endif -%}

 {%- comment -%}
  The generated CSS depends on the position of the current page in each level in
  the navigation.
 {%- endcomment -%}

-{%- assign activation_title = page.grand_parent | default: page.parent | default: page.title -%}
-{%- assign activation_first_level = activation_pages
-      | where_exp: "item", "item.parent == nil" -%}
-{%- include sorted_pages.html pages = activation_first_level -%}
-{%- for activation_page in sorted_pages -%}
-  {%- if activation_page.title == activation_title -%}
-    {%- assign activation_first_level_index = forloop.index -%}
-    {%- assign activation_first_level_reversed = activation_page.child_nav_order -%}
-    {%- break -%}
-  {%- endif -%}
-{%- endfor -%}
-
-{%- if activation_first_level_index == nil -%}
+{%- if nav_levels[1] == nil -%}

 {{ activation_no_nav_link }}

 {%- else -%}

-{%- if page.grand_parent -%}
-  {%- assign activation_title = page.parent -%}
-  {%- assign activation_second_level = activation_pages
-        | where_exp: "item", "item.grand_parent == nil"
-        | where_exp: "item", "item.parent == page.grand_parent" -%}
-{%- elsif page.parent -%}
-  {%- assign activation_title = page.title -%}
-  {%- assign activation_second_level = activation_pages
-        | where_exp: "item", "item.grand_parent == nil"
-        | where_exp: "item", "item.parent == page.parent" -%}
-{%- endif -%}
-{%- if page.parent -%}
-  {%- include sorted_pages.html pages = activation_second_level -%}
-  {%- for activation_page in sorted_pages -%}
-    {%- if activation_page.title == activation_title -%}
-      {%- assign activation_second_level_index = forloop.index -%}
-      {%- assign activation_second_level_reversed = activation_page.child_nav_order -%}
-      {%- if activation_first_level_reversed -%}
-        {%- assign activation_second_level_index = sorted_pages | size | plus: 1 | minus: activation_second_level_index -%}
-      {%- endif -%}
-      {%- break -%}
-    {%- endif -%}
-  {%- endfor -%}
-{%- endif -%}
-
-{%- if page.grand_parent -%}
-  {%- assign activation_third_level = activation_pages
-        | where_exp: "item", "item.parent == page.parent"
-        | where_exp: "item", "item.grand_parent == page.grand_parent" -%}
-  {%- include sorted_pages.html pages = activation_third_level -%}
-  {%- assign activation_third_level = sorted_pages -%}
-  {%- for activation_page in sorted_pages -%}
-    {%- if activation_page.title == page.title -%}
-      {%- assign activation_third_level_index = forloop.index -%}
-      {%- if activation_second_level_reversed -%}
-        {%- assign activation_third_level_index = sorted_pages | size | plus: 1 | minus: activation_third_level_index -%}
-      {%- endif -%}
-      {%- break -%}
-    {%- endif -%}
-  {%- endfor -%}
-{%- endif -%}
-
-{%- if activation_second_level_index == nil and activation_third_level_index -%}
+{%- if nav_levels[2] == nil and nav_levels[3] -%}

 {{ activation_no_nav_link }}

@ -158,34 +230,14 @@

 {%- else -%}

-  {%- for activation_collection in site.just_the_docs.collections -%}
-    {%- if activation_collection[0] == page.collection -%}
-      {%- assign activation_index = forloop.index -%}
-      {%- break -%}
-    {%- endif -%}
-  {%- endfor -%}
-
-  {%- assign activation_pages_top_size = site.html_pages
-          | where_exp:"item", "item.title != nil"
-          | where_exp:"item", "item.parent == nil"
-          | where_exp:"item", "item.nav_exclude != true"
-          | size -%}
-  {%- if activation_pages_top_size > 0 -%}
-    {%- assign activation_index = activation_index | plus: 1 -%}
-  {%- endif -%}
-
-  {%- if site.nav_external_links -%}
-    {%- assign activation_index = activation_index | plus: 1 -%}
-  {%- endif -%}
-
  {%- capture activation_collection_prefix -%}
-  .site-nav > ul:nth-of-type({{ activation_index }})
+  .site-nav > ul:nth-of-type({{ nav_levels[0] }})
  {%- if site.just_the_docs.collections[page.collection].nav_fold %} > li > ul
  {%- endif -%}
  {%- endcapture -%}

  {%- capture activation_other_collection_prefix -%}
-  .site-nav > ul:not(:nth-of-type({{ activation_index }}))
+  .site-nav > ul:not(:nth-of-type({{ nav_levels[0] }}))
  {%- endcapture -%}

 {%- endif -%}
@ -197,25 +249,25 @@
  and children of the current page.
 {%- endcomment %}

-{% if activation_third_level_index -%}
+{% if nav_levels[3] -%}

 {{ activation_collection_prefix }} > li > a,
 {{ activation_collection_prefix }} > li > ul > li > a,
-{{ activation_collection_prefix }} > li > ul > li > ul > li:not(:nth-child({{ activation_third_level_index }})) > a {
+{{ activation_collection_prefix }} > li > ul > li > ul > li:not(:nth-child({{ nav_levels[3] }})) > a {
  background-image: none;
 }

-{%- elsif activation_second_level_index -%}
+{%- elsif nav_levels[2] -%}

 {{ activation_collection_prefix }} > li > a,
-{{ activation_collection_prefix }} > li > ul > li:not(:nth-child({{ activation_second_level_index }})) > a,
+{{ activation_collection_prefix }} > li > ul > li:not(:nth-child({{ nav_levels[2] }})) > a,
 {{ activation_collection_prefix }} > li > ul > li > ul > li > a {
  background-image: none;
 }

 {%- else -%}

-{{ activation_collection_prefix }} > li:not(:nth-child({{ activation_first_level_index }})) > a,
+{{ activation_collection_prefix }} > li:not(:nth-child({{ nav_levels[1] }})) > a,
 {{ activation_collection_prefix }} > li > ul > li > a,
 {{ activation_collection_prefix }} > li > ul > li > ul > li > a {
  background-image: none;
@ -236,9 +288,9 @@
  The following rule styles the link to the current page.
 {%- endcomment %}

-{{ activation_collection_prefix }} > li:nth-child({{ activation_first_level_index }})
-{%- if activation_second_level_index %} > ul > li:nth-child({{ activation_second_level_index }})
-{%- if activation_third_level_index %} > ul > li:nth-child({{ activation_third_level_index }})
+{{ activation_collection_prefix }} > li:nth-child({{ nav_levels[1] }})
+{%- if nav_levels[2] %} > ul > li:nth-child({{ nav_levels[2] }})
+{%- if nav_levels[3] %} > ul > li:nth-child({{ nav_levels[3] }})
 {%- endif -%}
 {%- endif %} > a {
  font-weight: 600;
@ -259,9 +311,9 @@
 {%- if site.just_the_docs.collections %}
 .site-nav > ul.nav-category-list > li > button svg,
 {% endif -%}
-{{ activation_collection_prefix }} > li:nth-child({{ activation_first_level_index }}) > button svg
-{%- if activation_second_level_index -%},
-{{ activation_collection_prefix }} > li:nth-child({{ activation_first_level_index }}) > ul > li:nth-child({{ activation_second_level_index }}) > button svg
+{{ activation_collection_prefix }} > li:nth-child({{ nav_levels[1] }}) > button svg
+{%- if nav_levels[2] -%},
+{{ activation_collection_prefix }} > li:nth-child({{ nav_levels[1] }}) > ul > li:nth-child({{ nav_levels[2] }}) > button svg
 {%- endif %} {
  transform: rotate(-90deg);
 }
@ -269,13 +321,12 @@
 {%- if site.just_the_docs.collections %}
 .site-nav > ul.nav-category-list > li.nav-list-item > ul.nav-list,
 {% endif -%}
-{{ activation_collection_prefix }} > li.nav-list-item:nth-child({{ activation_first_level_index }}) > ul.nav-list
-{%- if activation_second_level_index %},
-{{ activation_collection_prefix }} > li.nav-list-item:nth-child({{ activation_first_level_index }}) > ul.nav-list > li.nav-list-item:nth-child({{ activation_second_level_index }}) > ul.nav-list
+{{ activation_collection_prefix }} > li.nav-list-item:nth-child({{ nav_levels[1] }}) > ul.nav-list
+{%- if nav_levels[2] %},
+{{ activation_collection_prefix }} > li.nav-list-item:nth-child({{ nav_levels[1] }}) > ul.nav-list > li.nav-list-item:nth-child({{ nav_levels[2] }}) > ul.nav-list
 {%- endif %} {
  display: block;
 }

 {%- endif -%}
 {%- endif -%}
-{%- endif -%}