just-the-docs 0.6.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c362693d611afbf87baeba763bc457fedd9dc2c0e61704c1c843969048f43a6
-  data.tar.gz: f3fa7e6c8ca7c926751d7221670c45457ad12e595dcccae5c2d8f025707b7630
+  metadata.gz: c8593eb0f4214116b46db9b1904d2585e794db893633690a78e5d77ad12c2b4f
+  data.tar.gz: dc7aa12e6092af9eabe4a5fd5509df6270fb197abcadff2bb4c4cb0a23993b25
 SHA512:
-  metadata.gz: 9f751827832c8b1b958bd2c4d7f3b9812c3194a6a7e7bf023131e86cd4f408bad4037d09f99281e4212390265aa8a2dad709bd6f7005941433073e0d28bf545e
-  data.tar.gz: fd30ebd6d9b5b4af76e31b62b1ce1b9621fa2b26dc2b87972072a52d40c30f652003043a63e2b9cc8f13a882a3a8b3c9ac291c321e736dd4b499632f5193fe1b
+  metadata.gz: c7673a1920061a093328ab384a5a23b25f5e7ec0a1759d09280aa89d07fe63e4df66ce343cd27265d7774ebf431cf45bd45b8ef44f91656371a9e121efd22d41
+  data.tar.gz: 39cf8e32b64c2973e9b463c52799c7d56ef57b42d06e46d97d3b92034ccfb131826f6e502e24528051dd067f926cbe5a8373af16a28f1bb0993c960a62e30c7e

data/CHANGELOG.md

@@ -19,6 +19,129 @@ Code changes to `main` that are *not* in the latest release:
 
 - N/A
 
+Docs changes made since the latest release:
+
+- N/A
+
+## Release v0.8.0
+
+Hi folks! This first minor release of 2024 has a short number of changes: a large improvement of build times for large sites, a new keyboard shortcut to focus the search bar, and sidebar navigation bugfixes for "pretty" URLs (with `.html` omitted) and the clickable area on Safari. This release has no explicit breaking changes and should be a straightforward upgrade for most (if not all) users.
+
+### Using Release `v0.8.0`
+
+Users who have not pinned the theme version will be **automatically upgraded to `v0.8.0` the next time they build their site**.
+
+To use this release explicitly as a remote theme:
+
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.8.0
+```
+
+To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
+
+```ruby
+gem "just-the-docs", "0.8.0"
+```
+
+To use and pin a previous version of the theme, replace the `0.8.0` with the desired release tag.
+
+### New Features
+
+- Added: configurable keyboard shortcut to focus search input by [@kcromanpl-bajra] in [#1411]
+
+### Bugfixes
+
+- Fixed: quicker build by [@pdmosses] in [#1397]
+- Fixed: incorrect navigation when `.html` omitted from URL by [@pdmosses] in [#1374]
+- Fixed: incorrect positioning of clickable area for navigation links on Safari by [@mattxwang] in [#1403]
+
+### Documentation
+
+- Add documentation to "Navigation Structure" on grouping pages with collections by [@mitchnemirov] in [#1390]
+
+### New Contributors
+
+- [@mitchnemirov] made their first contribution in [#1390]
+- [@kcromanpl-bajra] made their first contribution in [#1411]
+
+[@mitchnemirov]: https://github.com/mitchnemirov
+[@kcromanpl-bajra]: https://github.com/kcromanpl-bajra
+
+[#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
+
+## Release v0.7.0
+
+Hi folks! This is a minor release that adds a new configuration option for opening external links in a new tab and provides many bugfixes (in both correctness and performance) for Just the Docs users with large sites. We anticipate that for most users, this is a straightforward upgrade. However, it introduces some potentially-breaking *internal* changes to undocumented features of the theme.
+
+### Migrating to `v0.7.0`
+
+**Migration**: users will need to migrate if:
+
+- they overrode `_includes/nav.html`, which has moved to `_includes/components/nav.html`
+- they have an element with the IDs `jtd-nav-activation` or `jtd-head-nav-stylesheet`
+
+For more, refer to the [migration guide](https://just-the-docs.com/MIGRATION/).
+
+### Using Release `v0.7.0`
+
+Users who have not pinned the theme version will be **automatically upgraded to `v0.7.0` the next time they build their site**.
+
+To use this release explicitly as a remote theme:
+
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.7.0
+```
+
+To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
+
+```ruby
+gem "just-the-docs", "0.7.0"
+```
+
+To use and pin a previous version of the theme, replace the `0.7.0` with the desired release tag.
+
+### New Features
+
+- Added: configuration options for opening external links in new tab by [@CarbonNeuron] in [#1360]
+
+### Bugfixes
+
+- Fixed: remove href from the navigation link to the current page by [@pdmosses] in [#1356]
+- Fixed: improve build time by [@pdmosses] in [#1358]
+- Fixed: erroneous parentheses in `site_nav` conditional by [@mattxwang] in [#1366]
+- Fixed: navigation scroll to active link regression by [@pdmosses] in [#1367]
+- Fixed: invalid CSS rules in head elements by [@pdmosses] in [#1368]
+- Fixed: accidental disabling of forward-declared stylesheets by [@mattxwang] in [#1373]
+
+{: .warning }
+[#1358] moved `_includes/nav.html` to the `_includes/components` directory,
+Users who were overriding that file will need to adjust their sites accordingly.
+
+### Documentation:
+
+- Docs: fix typos in `CHANGELOG` and `MIGRATION` by [@thapasusheel] in [#1377]
+
+### New Contributors
+
+- [@CarbonNeuron] made their first contribution in [#1360]
+- [@thapasusheel] made their first contribution in [#1377]
+
+[@CarbonNeuron]: https://github.com/CarbonNeuron
+[@thapasusheel]: https://github.com/thapasusheel
+
+[#1356]: https://github.com/just-the-docs/just-the-docs/pull/1356
+[#1358]: https://github.com/just-the-docs/just-the-docs/pull/1358
+[#1360]: https://github.com/just-the-docs/just-the-docs/pull/1360
+[#1366]: https://github.com/just-the-docs/just-the-docs/pull/1366
+[#1367]: https://github.com/just-the-docs/just-the-docs/pull/1367
+[#1368]: https://github.com/just-the-docs/just-the-docs/pull/1368
+[#1373]: https://github.com/just-the-docs/just-the-docs/pull/1373
+[#1377]: https://github.com/just-the-docs/just-the-docs/pull/1377
+
 ## Release v0.6.2
 
 Hi all, this is a small patch release that includes two changes: adding a missing Windows emoji font fallback, and removing some (now-unused) code introduced in 0.6.
@@ -644,7 +767,7 @@ This RC does not introduce any major user-facing features. It adds more customiz
 
 ### Trying out pre-release `v0.4.0.rc5`
 
-Simlar to the prior release, `v0.4.0.rc5` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` following immediately after. While we don't anticipate many users using this RC, it is still possible to opt-in.
+Similar to the prior release, `v0.4.0.rc5` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` following immediately after. While we don't anticipate many users using this RC, it is still possible to opt-in.
 
 To use this RC explicitly as a remote theme:
 
@@ -745,7 +868,7 @@ Have any questions, thoughts, or concerns? We'd love to hear from you! Please [o
 
 ### Trying out pre-release `v0.4.0.rc4`
 
-Simlar to the prior release, `v0.4.0.rc4` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc4`.
+Similar to the prior release, `v0.4.0.rc4` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc4`.
 
 To use this RC explicitly as a remote theme:
 
@@ -866,7 +989,7 @@ As soon as we get stable test results from major downstream users, we'll push ou
 
 ### Trying out pre-release `v0.4.0.rc3`
 
-Simlar to the prior release, `v0.4.0.rc3` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc3`.
+Similar to the prior release, `v0.4.0.rc3` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc3`.
 
 To use this RC explicitly as a remote theme:
 
@@ -942,7 +1065,7 @@ The intention of this release candidate is to gather even more feedback on a pot
 
 ### Trying out pre-release `v0.4.0.rc2`
 
-Simlar to the prior release, `v0.4.0.rc2` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc2`.
+Similar to the prior release, `v0.4.0.rc2` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc2`.
 
 To use this RC explicitly as a remote theme:
 
@@ -1030,7 +1153,7 @@ We want your feedback! Are these changes helpful? Are our docs easy to understan
 
 ### Trying out pre-release `v0.4.0.rc1`
 
-Due to the massive scope of these changes, we're making `v0.4.0.rc1` avaialble as a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc1`.
+Due to the massive scope of these changes, we're making `v0.4.0.rc1` available as a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc1`.
 
 To use this RC explicitly as a remote theme:
 
@@ -1542,7 +1665,7 @@ fixes #291 #256 #293 #177
 
 ## v0.2.1
 
-This update fixes security vulnerablities in the lodash sub-dependency and bumps other dev dependencies to their latest version.
+This update fixes security vulnerabilities in the lodash sub-dependency and bumps other dev dependencies to their latest version.
 
 ## v0.2.0
 

data/_includes/components/breadcrumbs.html

@@ -3,39 +3,140 @@
   Depends on: page, site.
   Results in: HTML for the breadcrumbs component.
   Overwrites:
-    pages_list, parent_page, grandparent_page.
+    node, 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 -%}
+{%- 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 -%}
+
+  {%- for node in pages_list -%}
+  
+    {%- if node.has_children and page.grand_parent -%}
+
+      {%- if node.title == page.parent and node.parent == page.grand_parent -%}
+        {%- assign parent_page = node -%}
+      {%- endif -%}
+      {%- if node.title ==  page.grand_parent -%}
+        {%- assign grandparent_page = node -%}
+      {%- endif -%}
+      {%- if parent_page and grandparent_page -%}
+        {%- break -%}
+      {%- endif -%}
+
+    {%- elsif node.has_children and node.title == page.parent and node.parent == nil -%}
+
+      {%- assign parent_page = node -%}
+      {%- break -%}
+
+    {%- 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>

data/_includes/{nav.html → components/nav.html}

@@ -1,5 +1,5 @@
 {%- comment -%}
-  Include as: {%- include_cached nav.html pages=pages -%}
+  Include as: {%- include components/nav.html pages=pages -%}
   Depends on: include.pages.
   Results in: HTML for the navigation panel.
   Includes:

data/_includes/components/sidebar.html

@@ -3,10 +3,9 @@
   Depends on: page(?), site.
   Results in: HTML for the side bar.
   Includes:
-    title.html, nav.html, nav_footer_custom.html
-  Overwrites: 
-    pages_top_size, collections_size, collection_entry,
-    collection_key, collection_value, collection, nav_footer_custom.
+    title.html, components/site_nav.html, nav_footer_custom.html
+  Overwrites:
+    nav_footer_custom.
   Should not be cached, because nav_footer_custom.html might depend on page.
 {%- endcomment -%}
 
@@ -17,58 +16,8 @@
       <svg viewBox="0 0 24 24" class="icon" aria-hidden="true"><use xlink:href="#svg-menu"></use></svg>
     </button>
   </div>
-  <nav aria-label="Main" id="site-nav" class="site-nav">
-    {% assign 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 pages_top_size > 0 %}
-      {% include_cached nav.html pages=site.html_pages %}
-    {% endif %}
-    {%- if site.nav_external_links -%}
-      <ul class="nav-list">
-        {%- for node in site.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 -%}
-      </ul>
-    {%- endif -%}
-    {% if site.just_the_docs.collections %}
-      {% assign collections_size = site.just_the_docs.collections | size %}
-      {% for collection_entry in site.just_the_docs.collections %}
-        {% assign collection_key = collection_entry[0] %}
-        {% assign collection_value = collection_entry[1] %}
-        {% assign collection = site[collection_key] %}
-        {% if collection_value.nav_exclude != true %}
-          {% if collections_size > 1 or pages_top_size > 0 %}
-            {% if collection_value.nav_fold == true %}
-              <ul class="nav-list nav-category-list">
-                <li class="nav-list-item{% if page.collection == collection_key %} active{% endif %}">
-                  {%- if collection.size > 0 -%}
-                  <button class="nav-list-expander btn-reset" aria-label="Toggle collection {{ collection_value.name }}" aria-pressed="{% if page.collection == collection_key %}true{% else %}false{% endif %}">
-                    <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg>
-                  </button>
-                  {%- endif -%}
-                  <div class="nav-category">{{ collection_value.name }}</div>
-                  {% include_cached nav.html pages=collection %}
-                </li>
-              </ul>
-            {% else %}
-              <div class="nav-category">{{ collection_value.name }}</div>
-              {% include_cached nav.html pages=collection %}
-            {% endif %}
-          {% else %}
-            {% include_cached nav.html pages=collection %}
-          {% endif %}
-        {% endif %}
-      {% endfor %}
-    {% endif %}
-  </nav>
+
+  {% include_cached components/site_nav.html %}
 
   {% capture nav_footer_custom %}
     {%- include nav_footer_custom.html -%}

data/_includes/components/site_nav.html

@@ -0,0 +1,67 @@
+{%- comment -%}
+  Include as: {%- include_cached components/site_nav.html -%}
+  Depends on: site.
+  Results in: HTML for the site-nav.
+  Includes:
+    components/nav.html
+  Overwrites:
+    pages_top_size, collections_size, collection_entry,
+    collection_key, collection_value, collection.
+{%- endcomment -%}
+
+<nav aria-label="Main" id="site-nav" class="site-nav">
+  {% assign 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 pages_top_size > 0 %}
+    {% include components/nav.html pages=site.html_pages %}
+  {% endif %}
+  {%- if site.nav_external_links -%}
+    <ul class="nav-list">
+      {%- for node in site.nav_external_links -%}
+        <li class="nav-list-item external">
+          <a href="{{ node.url | absolute_url }}" class="nav-list-link external"
+            {% if node.opens_in_new_tab or node.opens_in_new_tab == nil and site.nav_external_links_new_tab %}
+              target="_blank" rel="noopener noreferrer"
+            {% endif %}
+          >
+            {{ 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 -%}
+    </ul>
+  {%- endif -%}
+  {% if site.just_the_docs.collections %}
+    {% assign collections_size = site.just_the_docs.collections | size %}
+    {% for collection_entry in site.just_the_docs.collections %}
+      {% assign collection_key = collection_entry[0] %}
+      {% assign collection_value = collection_entry[1] %}
+      {% assign collection = site[collection_key] %}
+      {% if collection_value.nav_exclude != true %}
+        {% if collections_size > 1 or pages_top_size > 0 %}
+          {% if collection_value.nav_fold == true %}
+            <ul class="nav-list nav-category-list">
+              <li class="nav-list-item">
+                {%- if collection.size > 0 -%}
+                <button class="nav-list-expander btn-reset" aria-label="Toggle collection {{ collection_value.name }}" aria-pressed="false">
+                  <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg>
+                </button>
+                {%- endif -%}
+                <div class="nav-category">{{ collection_value.name }}</div>
+                {% include components/nav.html pages=collection %}
+              </li>
+            </ul>
+          {% else %}
+            <div class="nav-category">{{ collection_value.name }}</div>
+            {% include components/nav.html pages=collection %}
+          {% endif %}
+        {% else %}
+          {% include components/nav.html pages=collection %}
+        {% endif %}
+      {% endif %}
+    {% endfor %}
+  {% endif %}
+</nav>

data/_includes/css/activation.scss.liquid

@@ -1,172 +1,332 @@
 {%- comment -%}
   Include as: {%- include css/activation.scss.liquid -%}
-  Depends on: page, site.
-  Results in: page-dependent SCSS rules for inclusion in a head style element.
-  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_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_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 might halve the build time for such sites.)
 {%- endcomment -%}
 
-{%- unless page.title == nil or page.nav_exclude == true -%}
-
-{%- assign activation_pages = site[page.collection]
-      | default: site.html_pages
-      | where_exp: "item", "item.title != nil"
-      | where_exp: "item", "item.nav_exclude != true" -%}
-
-{%- 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 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 -%}
+{%- comment -%}
+  The CSS rules in activation_no_nav_link are for use on pages excluded from the main navigation.
+  - The first rule ensures that no nav-link has a background image.
+  - The other two rules ensure that all folding collections are expanded.
+{%- endcomment -%}
 
-{%- unless activation_first_level_index == nil -%}
-
-{%- 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 -%}
+{%- capture activation_no_nav_link %}
+.site-nav ul li a {
+  background-image: none;
+}
+
+{%- if site.just_the_docs.collections %}
+.site-nav > ul.nav-category-list > li > button svg {
+  transform: rotate(-90deg);
+}
+.site-nav > ul.nav-category-list > li.nav-list-item > ul.nav-list {
+  display: block;
+}
+{%- endif %}
+{% endcapture -%}
+
+{%- 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 -%}
+<ul class="nav-list
+{%- endcapture -%}
+
+{%- 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 -%}
-  {%- 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 -%}
+  {%- 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 -%}
-  {%- endfor -%}
+
+  {%- endif -%}
+
+{%- endfor -%}
+
+{%- assign nav_levels = nav_levels | where_exp: "item", "item >= 1" -%}
+
 {%- endif -%}
 
-{%- unless activation_second_level_index == nil and activation_third_level_index -%}
+{%- comment -%}
+  The generated CSS depends on the position of the current page in each level in
+  the navigation.
+{%- endcomment -%}
+
+{%- if nav_levels[1] == nil -%}
+
+{{ activation_no_nav_link }}
+
+{%- else -%}
+
+{%- if nav_levels[2] == nil and nav_levels[3] -%}
+
+{{ activation_no_nav_link }}
+
+{%- else -%}
+
+{%- comment -%}
+  The site-nav is:
+  - an optional ul.nav-list with li.nav-list-items for non-collection top-level pages
+  - an optional ul.nav-list with li.nav-list-item.externals
+  - any number of just-the-docs.collections
+  
+  A non-foldable collection is:
+  - a div.nav-category with the collection name, followed by:
+  - a ul.nav-list with li.nav-list-items for its top-level pages
+  
+  A foldable collection is:
+  - a ul.nav-list.nav-category-list with a single li.nav-list-item containing:
+    - an optional button with the expander svg
+    - a div.nav-category with the collection name
+    - a ul.nav-list with li.nav-list-items for its top-level pages
+  
+  The generated CSS uses:
+  - activation_collection_prefix, to select the site-nav > ul.nav-list for the page
+  - activation_other_collection_prefix, to select all the other site-nav > ul.nav-lists
+{%- endcomment -%}
 
 {%- if page.collection == nil -%}
 
   {%- capture activation_collection_prefix -%}
-  .site-nav > .nav-list:nth-child(1):not(.nav-category-list) 
+  .site-nav > ul.nav-list:first-child
+  {%- endcapture -%}
+
+  {%- capture activation_other_collection_prefix -%}
+  .site-nav > ul.nav-list:not(:first-child)
   {%- endcapture -%}
 
 {%- else -%}
 
-  {%- for activation_collection in site.just_the_docs.collections -%}
-    {%- if activation_collection[0] == page.collection -%}
-      {%- assign activation_collection_index = forloop.index -%}
-      {%- break -%}
-    {%- endif -%}
-  {%- endfor -%}
-  {%- assign activation_index = activation_collection_index -%}
-  {%- 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 > .nav-list:nth-of-type({{ activation_index }}){% if site.just_the_docs.collections[page.collection].nav_fold == true %} > .nav-list-item > .nav-list{% endif %}
+  .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({{ nav_levels[0] }}))
+  {%- endcapture -%}
+
 {%- endif -%}
 
-// Styling for the nav-list-link to the current page:
-{{ activation_collection_prefix }} {
-  > .nav-list-item:not(.external):nth-child({{ activation_first_level_index }}){%- if activation_second_level_index %} > .nav-list > .nav-list-item:nth-child({{ activation_second_level_index }}){%- if activation_third_level_index %} > .nav-list > .nav-list-item:nth-child({{ activation_third_level_index }}){% endif %}{% endif %} {
-    > .nav-list-link {
-      display: block;
-      font-weight: 600;
-      text-decoration: none;
-      background-image: linear-gradient(
-        -90deg,
-        rgba($feedback-color, 1) 0%,
-        rgba($feedback-color, 0.8) 80%,
-        rgba($feedback-color, 0) 100%
-      );
-    }
-  }
+{%- comment -%}
+  The required background image of the link to the current page may involve SCSS.
+  To avoid page-dependent SCSS, all nav links initially have that background image.
+  The following rule removes the image from the links to all parents, siblings,
+  and children of the current page.
+{%- endcomment %}
+
+{% 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({{ nav_levels[3] }})) > a {
+  background-image: none;
 }
 
-// Styling for nav-list-expanders at first and second levels:
-{{ activation_collection_prefix }} {
-  > .nav-list-item:nth-child({{ activation_first_level_index }}){%- if activation_second_level_index %},
-  > .nav-list-item:nth-child({{ activation_first_level_index }}) > .nav-list > .nav-list-item:nth-child({{ activation_second_level_index }}){% endif %} {
-    > .nav-list-expander svg {
-      @if $nav-list-expander-right {
-        transform: rotate(-90deg);
-      } @else {
-        transform: rotate(90deg);
-      }
-    }
-
-    > .nav-list {
-      display: block;
-    }
-  }
+{%- elsif nav_levels[2] -%}
+
+{{ activation_collection_prefix }} > li > 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;
 }
 
-// Styling for nav-list-expander for categories:
-.site-nav > .nav-category-list > .nav-list-item {
-  > .nav-list-expander svg {
-    @if $nav-list-expander-right {
-      transform: rotate(-90deg);
-    } @else {
-      transform: rotate(90deg);
-    }
-  }
-
-  > .nav-list {
-    display: block;
-  }
+{%- else -%}
+
+{{ 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;
 }
 
-{%- endunless -%}
-{%- endunless -%}
-{%- endunless -%}
+{%- endif %}
+
+{%- comment -%}
+  The following rule removes the image from the links to pages in other collections.
+{%- endcomment %}
+
+{{ activation_other_collection_prefix }} a,
+.site-nav li.external a {
+  background-image: none;
+}
+
+{%- comment -%}
+  The following rule styles the link to the current page.
+{%- endcomment %}
+
+{{ 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;
+  text-decoration: none;
+}
+
+{%- comment -%}
+  The following rules unfold all collections, and display the links to any children
+  of the current page.
+  
+  To avoid dependence on the SCSS variable nav-list-expander-right, the direction
+  of the rotation of the expander icon is fixed, and corresponds to the appearance
+  when nav-list-expander-right is true. This results in a minor visual difference
+  between the appearance of active expander icons when JS is enabled/disabled and
+  nav-list-expander-right is false, which seems unavoidable.
+{%- endcomment %}
+
+{%- if site.just_the_docs.collections %}
+.site-nav > ul.nav-category-list > li > button svg,
+{% endif -%}
+{{ 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);
+}
+
+{%- 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({{ 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 -%}

data/_includes/fix_linenos.html

@@ -1,29 +1,37 @@
 {%- comment -%}
-This file can be used to fix the HTML produced by Jekyll for highlighted
-code with line numbers.
+This file was previously used to "fix" the HTML produced by Jekyll for
+highlighted code with line numbers. While it often resolves layout issues
+from the missing HTML tags, it still generates invalid HTML (by placing
+a `<table>` element within a `<code>` block). As such, we no longer
+recommend using this workaround. For more information, see the
+"Code snippets with line numbers" docs page:
+https://just-the-docs.com/docs/ui-components/code/line-numbers/
+(or, docs/ui-components/line-nos.md/)
 
-It works with `{% highlight some_language linenos %}...{% endhighlight %}`
-and with the Kramdown option to add line numbers to fenced code.
+The next portion of this file, including the comments and the workaround,
+are preserved for backwards comptability.
 
-The implementation was derived from the workaround provided by 
+ACKNOWLEDGEMENTS
+
+The implementation was derived from the workaround provided by
 Dmitry Hrabrov (DeXP) at
 https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-188144901
 
-EXPLANATION
+EXPLANATION (OLD)
 
-The HTML produced by Rouge highlighting with lie numbers is of the form
-`code table`. Jekyll (<= 4.1.1) always wraps the highlighted HTML
+The HTML produced by Rouge highlighting with line numbers is of the form
+`code table`. Jekyll always wraps the highlighted HTML
 with `pre`. This wrapping is not only unnecessary, but also transforms
 the conforming HTML produced by Rouge to non-conforming HTML, which
-results in HTML validation error reports. 
+results in HTML validation error reports.
 
 The fix removes the outer `pre` tags whenever they contain the pattern
 `<table class="rouge-table">`.
-  
+
 Apart from avoiding HTML validation errors, the fix allows the use of
 the [Jekyll layout for compressing HTML](http://jch.penibelst.de),
 which relies on `pre` tags not being nested, according to
-https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-172069842 
+https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-172069842
 
 USAGE
 
@@ -48,7 +56,7 @@ Some code
 
 CAVEATS
 
-The above does not work when `Some code` happens to contain the matched string 
+The above does not work when `Some code` happens to contain the matched string
 `<table class="rouge-table">`.
 
 The use of this file overwrites the variable `fix_linenos_code` with `nil`.

data/_includes/head.html

@@ -4,8 +4,8 @@
     site.search_enabled, site.static_files, site.favicon_ico.
   Results in: HTML for the head element.
   Includes:
-    head_nav.html, head_custom.html.
-  Overwrites: 
+    css/activation.scss.liquid, head_custom.html.
+  Overwrites:
     ga_tracking_ids, ga_property, file, favicon.
   Should not be cached, because included files depend on page.
 {%- endcomment -%}
@@ -15,8 +15,12 @@
   <meta http-equiv="X-UA-Compatible" content="IE=Edge">
 
   <link rel="stylesheet" href="{{ '/assets/css/just-the-docs-default.css' | relative_url }}">
-  
-  {% include head_nav.html %}
+
+  <link rel="stylesheet" href="{{ '/assets/css/just-the-docs-head-nav.css' | relative_url }}" id="jtd-head-nav-stylesheet">
+
+  <style id="jtd-nav-activation">
+  {% include css/activation.scss.liquid %}
+  </style>
 
   {% if site.ga_tracking != nil %}
     {% assign ga_tracking_ids = site.ga_tracking | split: "," %}

data/assets/css/just-the-docs-head-nav.css

@@ -0,0 +1,24 @@
+---
+---
+{%- if site.color_scheme and site.color_scheme != "nil" -%}
+  {%- assign color_scheme = site.color_scheme -%}
+{%- else -%}
+  {%- assign color_scheme = "light" -%}
+{%- endif -%}
+
+{%- capture newline %}
+{% endcapture -%}
+
+{%- capture scss -%}
+{% include css/just-the-docs.scss.liquid color_scheme=color_scheme %}
+.site-nav ul li a {
+  background-image: linear-gradient(
+    -90deg,
+    rgba($feedback-color, 1) 0%,
+    rgba($feedback-color, 0.8) 80%,
+    rgba($feedback-color, 0) 100%
+  );
+}
+{%- endcapture -%}
+
+{{ scss | scssify | split: newline | slice: -3, 3 | join: newline }}

data/assets/js/just-the-docs.js

@@ -38,8 +38,8 @@ function initNav() {
   const siteNav = document.getElementById('site-nav');
   const mainHeader = document.getElementById('main-header');
   const menuButton = document.getElementById('menu-button');
-  
-  disableHeadStyleSheet();
+
+  disableHeadStyleSheets();
 
   jtd.addEvent(menuButton, 'click', function(e){
     e.preventDefault();
@@ -68,13 +68,23 @@ function initNav() {
   {%- endif %}
 }
 
-// The page-specific <style> in the <head> is needed only when JS is disabled.
-// Moreover, it incorrectly overrides dynamic stylesheets set by setTheme(theme). 
-// The page-specific stylesheet is assumed to have index 1 in the list of stylesheets.
+// The <head> element is assumed to include the following stylesheets:
+// - a <link> to /assets/css/just-the-docs-head-nav.css,
+//             with id 'jtd-head-nav-stylesheet'
+// - a <style> containing the result of _includes/css/activation.scss.liquid.
+// To avoid relying on the order of stylesheets (which can change with HTML
+// compression, user-added JavaScript, and other side effects), stylesheets
+// are only interacted with via ID
+
+function disableHeadStyleSheets() {
+  const headNav = document.getElementById('jtd-head-nav-stylesheet');
+  if (headNav) {
+    headNav.disabled = true;
+  }
 
-function disableHeadStyleSheet() {
-  if (document.styleSheets[1]) {
-    document.styleSheets[1].disabled = true;
+  const activation = document.getElementById('jtd-nav-activation');
+  if (activation) {
+    activation.disabled = true;
   }
 }
 
@@ -135,6 +145,18 @@ function searchLoaded(index, docs) {
   var currentInput;
   var currentSearchIndex = 0;
 
+  {%- if site.search.focus_shortcut_key %}
+  // add event listener on ctrl + <focus_shortcut_key> for showing the search input
+  jtd.addEvent(document, 'keydown', function (e) {
+    if ((e.ctrlKey || e.metaKey) && e.key === '{{ site.search.focus_shortcut_key }}') {
+      e.preventDefault();
+
+      mainHeader.classList.add('nav-open');
+      searchInput.focus();
+    }
+  });
+  {%- endif %}
+
   function showSearch() {
     document.documentElement.classList.add('search-active');
   }
@@ -477,11 +499,28 @@ jtd.setTheme = function(theme) {
 // and not have the slash on GitHub Pages
 
 function navLink() {
-  var href = document.location.pathname;
-  if (href.endsWith('/') && href != '/') {
-    href = href.slice(0, -1);
+  var pathname = document.location.pathname;
+
+  var navLink = document.getElementById('site-nav').querySelector('a[href="' + pathname + '"]');
+  if (navLink) {
+    return navLink;
+  }
+
+  // The `permalink` setting may produce navigation links whose `href` ends with `/` or `.html`.
+  // To find these links when `/` is omitted from or added to pathname, or `.html` is omitted:
+
+  if (pathname.endsWith('/') && pathname != '/') {
+    pathname = pathname.slice(0, -1);
   }
-  return document.getElementById('site-nav').querySelector('a[href="' + href + '"], a[href="' + href + '/"]');
+
+  if (pathname != '/') {
+    navLink = document.getElementById('site-nav').querySelector('a[href="' + pathname + '"], a[href="' + pathname + '/"], a[href="' + pathname + '.html"]');
+    if (navLink) {
+      return navLink;
+    }
+  }
+
+  return null; // avoids `undefined`
 }
 
 // Scroll site-nav to ensure the link to the current page is visible
@@ -489,8 +528,8 @@ function navLink() {
 function scrollNav() {
   const targetLink = navLink();
   if (targetLink) {
-    const rect = targetLink.getBoundingClientRect();
-    document.getElementById('site-nav').scrollBy(0, rect.top - 3*rect.height);
+    targetLink.scrollIntoView({ block: "center" });
+    targetLink.removeAttribute('href');
   }
 }
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: just-the-docs
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.8.0
 platform: ruby
 authors:
 - Patrick Marsceill
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-09-20 00:00:00.000000000 Z
+date: 2024-02-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -100,9 +100,11 @@ files:
 - _includes/components/footer.html
 - _includes/components/header.html
 - _includes/components/mermaid.html
+- _includes/components/nav.html
 - _includes/components/search_footer.html
 - _includes/components/search_header.html
 - _includes/components/sidebar.html
+- _includes/components/site_nav.html
 - _includes/css/activation.scss.liquid
 - _includes/css/callouts.scss.liquid
 - _includes/css/custom.scss.liquid
@@ -112,7 +114,6 @@ files:
 - _includes/footer_custom.html
 - _includes/head.html
 - _includes/head_custom.html
-- _includes/head_nav.html
 - _includes/header_custom.html
 - _includes/icons/code_copy.html
 - _includes/icons/document.html
@@ -126,7 +127,6 @@ files:
 - _includes/lunr/custom-data.json
 - _includes/lunr/custom-index.js
 - _includes/mermaid_config.js
-- _includes/nav.html
 - _includes/nav_footer_custom.html
 - _includes/search_placeholder_custom.html
 - _includes/sorted_pages.html
@@ -179,6 +179,7 @@ files:
 - _sass/vendor/normalize.scss/normalize.scss
 - assets/css/just-the-docs-dark.scss
 - assets/css/just-the-docs-default.scss
+- assets/css/just-the-docs-head-nav.css
 - assets/css/just-the-docs-light.scss
 - assets/js/just-the-docs.js
 - assets/js/vendor/lunr.min.js

data/_includes/head_nav.html

@@ -1,48 +0,0 @@
-{%- comment -%}
-  Include as: {%- include head_nav.html -%}
-  Depends on: site.color_scheme.
-  Results in: HTML for a page-specific style element.
-  Includes:
-    css/activation.scss.liquid.
-  Overwrites: 
-    activation, test_scss, scss, css, index, count.
-  Should not be cached, because css/activation.scss.liquid depends on page.
-{%- endcomment -%}
-
-{% capture activation %}
-  {% include css/activation.scss.liquid %}
-{%- endcapture -%}
-
-{% capture test_scss %}
-  @import "./support/support";
-  @import "./color_schemes/light";
-  {{ activation }}
-{%- endcapture -%}
-
-{%- capture scss -%}
-  @import "./support/support";
-  @import "./custom/setup";
-  {% if site.color_scheme and site.color_scheme != "nil" -%}
-    {%- assign color_scheme = site.color_scheme -%}
-  {%- else -%}
-    {%- assign color_scheme = "light" -%}
-  {%- endif %}
-  @import "./color_schemes/light";
-  {% unless color_scheme == "light" %}
-  @import "./color_schemes/{{ color_scheme }}";
-  {% endunless %}
-  {{ activation }}
-{%- endcapture -%}
-
-{%- comment -%}
-  Convert to CSS, then remove the color_scheme import rules to avoid duplication.
-  The value of count is page-dependent, but independent of custom color schemes.
-{%- endcomment -%}
-{%- assign count = test_scss  | scssify | split: ".site-nav" | size -%}
-{%- unless count == 1 %}
-{%- assign index = 1 | minus: count -%}
-{%- assign css = scss | scssify | split: ".site-nav" | slice: index, count | join: ".site-nav" -%}
-<style type="text/css">
-{{ css | prepend: ".site-nav" }}
-</style>
-{%- endunless %}