0.8.1

Ref: https://github.com/just-the-docs/just-the-docs/pull/1434#issuecomment-1981666074

.github/workflows/ci.yml

@@ -19,7 +19,7 @@ jobs:
         ruby-version: ["3.0", "3.1", "3.2"]
     runs-on: ${{ matrix.os }}
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Setup Ruby ${{ matrix.ruby-version }}
       uses: ruby/setup-ruby@v1
       with:
@@ -42,7 +42,7 @@ jobs:
     name: Build (github-pages gem)
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Setup Ruby
       uses: ruby/setup-ruby@v1
       with:
@@ -66,7 +66,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Setup Ruby ${{ matrix.ruby-version }}
         uses: ruby/setup-ruby@v1
         with:
@@ -75,17 +75,16 @@ jobs:
           cache-version: 0 # Increment this number if you need to re-download cached gems
       - name: Cache HTMLProofer
         id: cache-htmlproofer
-        uses: actions/cache@v2
+        uses: actions/cache@v3
         with:
           path: tmp/.htmlproofer
           key: ${{ runner.os }}-htmlproofer
       - name: Build Site
         run: bundle exec jekyll build
       - name: Test with Nu Validator
-        uses: Cyb3r-Jak3/html5validator-action@c7bb77a0fe3b0458583de50fd0f4dd819569b8a9
+        uses: Cyb3r-Jak3/html5validator-action@2a593a9f2c10593cbac84791a6fc4c47e9a106c8
         with:
-          root: _site
+          config: fixtures/html5validator-config.yml
-          blacklist: line-numbers
       - name: Test with html-proofer
         run: bundle exec htmlproofer _site --ignore-urls "/github.com/,/web.archive.org/"
         env:
@@ -100,9 +99,9 @@ jobs:
         node-version: [18.x]
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v1
+      uses: actions/setup-node@v3
       with:
         node-version: ${{ matrix.node-version }}
     - run: npm install

.github/workflows/deploy.yml

@@ -30,7 +30,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
@@ -39,7 +39,7 @@ jobs:
           cache-version: 0 # Increment this number if you need to re-download cached gems
       - name: Setup Pages
         id: pages
-        uses: actions/configure-pages@v2
+        uses: actions/configure-pages@v3
       - name: Build with Jekyll
         # Outputs to the './_site' directory by default
         run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
@@ -47,7 +47,7 @@ jobs:
           JEKYLL_ENV: production
       - name: Upload artifact
         # Automatically uploads an artifact from the './_site' directory by default
-        uses: actions/upload-pages-artifact@v1
+        uses: actions/upload-pages-artifact@v2
 
   # Deployment job
   deploy:
@@ -59,4 +59,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v1
+        uses: actions/deploy-pages@v2

.github/workflows/publish-gem.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Setup Ruby 3.2
       uses: ruby/setup-ruby@v1
       with:

CHANGELOG.md

@@ -19,6 +19,150 @@ 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.1
+
+Hi folks! This patch release fixes a bug introduced in `0.8.0` that affects users who build their sites in strict mode. It is a straightforward upgrade that should require no manual migration changes. Thank you to [@Zarthus] for quickly catching and fixing this bug!
+
+### Bugfixes
+
+- Fixed: Liquid filter typo in breadcrumb component (`strip` instead of `trim`) by [@Zarthus] in [#1434]
+
+### Documentation
+
+- Build docs site using strict mode and `strict_filters` by [@Zarthus] in [#1435]
+
+### New Contributors
+
+- [@Zarthus] made their first contribution in [#1434]
+
+[@Zarthus]: https://github.com/Zarthus
+
+[#1434]: https://github.com/just-the-docs/just-the-docs/pull/1434
+[#1435]: https://github.com/just-the-docs/just-the-docs/pull/1435
+
+## 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 +788,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 +889,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 +1010,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 +1086,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 +1174,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 +1686,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
 

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    just-the-docs (0.6.1)
+    just-the-docs (0.8.1)
       jekyll (>= 3.8.5)
       jekyll-include-cache
       jekyll-seo-tag (>= 2.0)
@@ -11,7 +11,7 @@ GEM
   remote: https://rubygems.org/
   specs:
     Ascii85 (1.1.0)
-    addressable (2.8.4)
+    addressable (2.8.6)
       public_suffix (>= 2.0.2, < 6.0)
     afm (0.2.2)
     async (2.6.3)
@@ -19,6 +19,7 @@ GEM
       fiber-annotation
       io-event (~> 1.1)
       timers (~> 4.1)
+    base64 (0.2.0)
     colorator (1.1.0)
     concurrent-ruby (1.2.2)
     console (1.23.2)
@@ -30,16 +31,17 @@ GEM
     ethon (0.16.0)
       ffi (>= 1.15.0)
     eventmachine (1.2.7)
-    faraday (2.7.10)
+    faraday (2.8.1)
+      base64
       faraday-net_http (>= 2.0, < 3.1)
       ruby2_keywords (>= 0.0.4)
     faraday-net_http (3.0.2)
-    ffi (1.15.5)
+    ffi (1.16.3)
     fiber-annotation (0.2.0)
     fiber-local (1.0.0)
     forwardable-extended (2.6.0)
-    google-protobuf (3.23.4-arm64-darwin)
+    google-protobuf (3.25.1-arm64-darwin)
-    google-protobuf (3.23.4-x86_64-linux)
+    google-protobuf (3.25.1-x86_64-linux)
     hashery (2.1.2)
     html-proofer (5.0.8)
       addressable (~> 2.3)
@@ -54,7 +56,7 @@ GEM
     i18n (1.14.1)
       concurrent-ruby (~> 1.0)
     io-event (1.2.3)
-    jekyll (4.3.2)
+    jekyll (4.3.3)
       addressable (~> 2.4)
       colorator (~> 1.0)
       em-websocket (~> 0.5)
@@ -70,7 +72,7 @@ GEM
       safe_yaml (~> 1.0)
       terminal-table (>= 1.8, < 4.0)
       webrick (~> 1.7)
-    jekyll-github-metadata (2.16.0)
+    jekyll-github-metadata (2.16.1)
       jekyll (>= 3.4, < 5.0)
       octokit (>= 4, < 7, != 4.4.0)
     jekyll-include-cache (0.2.1)
@@ -90,9 +92,9 @@ GEM
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     mercenary (0.4.0)
-    nokogiri (1.15.4-arm64-darwin)
+    nokogiri (1.16.2-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.15.4-x86_64-linux)
+    nokogiri (1.16.2-x86_64-linux)
       racc (~> 1.4)
     octokit (6.1.1)
       faraday (>= 1, < 3)
@@ -105,22 +107,22 @@ GEM
       hashery (~> 2.0)
       ruby-rc4
       ttfunk
-    public_suffix (5.0.3)
+    public_suffix (5.0.4)
-    racc (1.7.1)
+    racc (1.7.3)
     rainbow (3.1.1)
-    rake (13.0.6)
+    rake (13.1.0)
     rb-fsevent (0.11.2)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
     rexml (3.2.6)
-    rouge (4.1.2)
+    rouge (4.2.0)
     ruby-rc4 (0.1.5)
     ruby2_keywords (0.0.5)
     safe_yaml (1.0.5)
-    sass-embedded (1.64.1-arm64-darwin)
+    sass-embedded (1.69.6-arm64-darwin)
-      google-protobuf (~> 3.23)
+      google-protobuf (~> 3.25)
-    sass-embedded (1.64.1-x86_64-linux-gnu)
+    sass-embedded (1.69.6-x86_64-linux-gnu)
-      google-protobuf (~> 3.23)
+      google-protobuf (~> 3.25)
     sawyer (0.9.2)
       addressable (>= 2.3.5)
       faraday (>= 0.17.3, < 3)
@@ -130,7 +132,7 @@ GEM
     ttfunk (1.7.0)
     typhoeus (1.4.0)
       ethon (>= 0.9.0)
-    unicode-display_width (2.4.2)
+    unicode-display_width (2.5.0)
     webrick (1.8.1)
     yell (2.2.2)
     zeitwerk (2.6.11)

MIGRATION.md

@@ -43,6 +43,34 @@ This document contains instructions on how to migrate and upgrade Just the Docs
 
 [CHANGELOG]: {{ site.baseurl }}{% link CHANGELOG.md %}
 
+## v0.6.x - v0.7.0
+
+### POTENTIALLY-BREAKING CHANGES in v0.7.0
+
+There are some *very minor* potentially-breaking changes for users in version `v0.7.0`. **They do not affect the vast majority of users**; however, this may affect users of (undocumented) internal theme structure. They concern:
+
+1. the movement of `_includes/nav.html`, which has moved to `_includes/components/nav.html`
+  - **explicit migration only necessary if users have overridden `_includes/nav.html`**
+2. the addition of `<script>` tags with `id`s `jtd-nav-activation` and `jtd-head-nav-stylesheet`
+  - **explicit migration only necessary if users have existing elements with those IDs**
+
+#### Moved Include
+
+Version `v0.7.0` has moved (and changed the contents of) `_includes/nav.html`; it is now in `_includes/components/nav.html`. This means that user overrides for the component will *no longer be loaded*, reverting to the Just the Docs default.
+
+Users who have overridden this `_includes` should:
+
+1. copy in the new upstream `_includes/components/nav.html` into their site
+2. port over any changes from their custom `_includes/nav.html`
+
+No other changes are necessary.
+
+#### New Script IDs
+
+Version `v0.7.0` adds the `id`s `jtd-nav-activation` and `jtd-head-nav-stylesheet` to some existing script tags. This will cause errors for users that have their own custom components with those IDs.
+
+Users who have elements with those `id`s should rename their elements to avoid a collision.
+
 ## v0.5.x - v0.6.0
 
 ### POTENTIALLY-BREAKING CHANGES in v0.6.0
@@ -119,7 +147,7 @@ However, some users may load different favicons for each page (and/or dynamicall
 
 ### POTENTIALLY-BREAKING CHANGES in v0.5.0
 
-There is one potentially-breaking change for users migrating from `v0.4.2` to `v0.5.0` concering `setup.scss`. To provide context:
+There is one potentially-breaking change for users migrating from `v0.4.2` to `v0.5.0` concerning `setup.scss`. To provide context:
 
 1. `setup.scss` was introduced in `v0.4.0`
 2. in `v0.4.0` and `v0.4.1`, `setup.scss` was imported *before* color scheme SCSS code

_config.yml

@@ -78,6 +78,8 @@ search:
   # Enable or disable the search button that appears in the bottom right corner of every page
   # Supports true or false (default)
   button: false
+  # Focus the search input by pressing `ctrl + focus_shortcut_key` (or `cmd + focus_shortcut_key` on macOS)
+  focus_shortcut_key: 'k'
 
 # For copy button on code
 enable_copy_code_button: true
@@ -116,6 +118,10 @@ nav_external_links:
   - title: Just the Docs on GitHub
     url: https://github.com/just-the-docs/just-the-docs
 
+liquid:
+   error_mode: strict
+   strict_filters: true
+   
 # Footer content
 # appears at the bottom of every page's main content
 

_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]
+{%- capture nav_list_link -%}
-      | default: site.html_pages
+<a href="{{ page.url | relative_url }}" class="nav-list-link">
-      | where_exp: "item", "item.title != nil"
+{%- endcapture -%}
-      | where_exp: "item", "item.has_children != nil" -%}
 
-  {%- if page.grand_parent -%}
+{%- capture site_nav -%}
-    {%- assign parent_page = pages_list
+{%- include_cached components/site_nav.html -%}
-        | where: "title", page.parent
+{%- endcapture -%}
-        | where: "parent", page.grand_parent
+
-        | first -%}
+{%- if site_nav contains nav_list_link -%}
-    {%- assign grandparent_page = pages_list
+
-        | where: "title", page.grand_parent
+  {%- capture nav_list_simple -%}
-        | first -%}
+  <ul class="nav-list">
-  {%- else -%}
+  {%- endcapture -%}
-    {%- assign parent_page = pages_list
+
-        | where: "title", page.parent
+  {%- capture nav_list_link_class %} class="nav-list-link">
-        | where_exp: "item", "item.parent == nil"
+  {%- endcapture -%}
-        | first -%}
+
+  {%- 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 -%}
+
+  {%- 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 nav_grandparent_link %}
-  {%- if page.grand_parent %}
+    <li class="breadcrumb-nav-list-item">{{ nav_grandparent_link }}</li>
-    <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>
+    <li class="breadcrumb-nav-list-item">{{ nav_parent_link }}</li>
-  {% endif -%}
     <li class="breadcrumb-nav-list-item"><span>{{ page.title }}</span></li>
   </ol>
 </nav>

_includes/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:

_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
+    title.html, components/site_nav.html, nav_footer_custom.html
-  Overwrites: 
+  Overwrites:
-    pages_top_size, collections_size, collection_entry,
+    nav_footer_custom.
-    collection_key, collection_value, collection, 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
+  {% include_cached components/site_nav.html %}
-          | 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>
 
   {% capture nav_footer_custom %}
     {%- include nav_footer_custom.html -%}

_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>

_includes/css/activation.scss.liquid

@@ -1,172 +1,332 @@
 {%- comment -%}
   Include as: {%- include css/activation.scss.liquid -%}
-  Depends on: page, site.
+  Depends on: page.
-  Results in: page-dependent SCSS rules for inclusion in a head style element.
+  Results in: page-dependent CSS rules for inclusion in a style element,
-  Includes:
+    which needs to be disabled when JS is enabled.
-    sorted_pages.html.
+  Includes: components/site_nav.html.
   Overwrites: 
-    activation_pages, activation_pages_top_size, activation_page, activation_title,
+    activation_no_nav_link, nav_list_link, site_nav,
-    activation_first_level, activation_second_level, activation_third_level,
+    nav_list, nav_list_end, nav_list_item, nav_category_list,
-    activation_first_level_reversed, activation_second_level_reversed,
+    nav_list_link_prefix, nav_splits, nav_split, nav_levels,
-    activation_first_level_index, activation_second_level_index, activation_third_level_index.
+    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 -%}
+{%- 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 -%}
 
-{%- assign activation_pages = site[page.collection]
+{%- capture activation_no_nav_link %}
-      | default: site.html_pages
+.site-nav ul li a {
-      | where_exp: "item", "item.title != nil"
+  background-image: none;
-      | where_exp: "item", "item.nav_exclude != true" -%}
+}
 
-{%- assign activation_first_level_index = nil -%}
+{%- if site.just_the_docs.collections %}
-{%- assign activation_second_level_index = nil -%}
+.site-nav > ul.nav-category-list > li > button svg {
-{%- assign activation_third_level_index = nil -%}
+  transform: rotate(-90deg);
-{%- assign activation_first_level_reversed = nil -%}
+}
-{%- assign activation_second_level_reversed = nil -%}
+.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 -%}
+
+  {%- 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 -%}
 
-{%- 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 -%}
 
-{%- unless activation_first_level_index == nil -%}
+{%- assign nav_levels = nav_levels | where_exp: "item", "item >= 1" -%}
 
-{%- 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 -%}
+{%- comment -%}
-  {%- assign activation_third_level = activation_pages
+  The generated CSS depends on the position of the current page in each level in
-        | where_exp: "item", "item.parent == page.parent"
+  the navigation.
-        | where_exp: "item", "item.grand_parent == page.grand_parent" -%}
+{%- endcomment -%}
-  {%- 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 -%}
 
-{%- unless activation_second_level_index == nil and activation_third_level_index -%}
+{%- 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:
+{%- comment -%}
-{{ activation_collection_prefix }} {
+  The required background image of the link to the current page may involve SCSS.
-  > .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 %} {
+  To avoid page-dependent SCSS, all nav links initially have that background image.
-    > .nav-list-link {
+  The following rule removes the image from the links to all parents, siblings,
-      display: block;
+  and children of the current page.
-      font-weight: 600;
+{%- endcomment %}
-      text-decoration: none;
+
-      background-image: linear-gradient(
+{% if nav_levels[3] -%}
-        -90deg,
+
-        rgba($feedback-color, 1) 0%,
+{{ activation_collection_prefix }} > li > a,
-        rgba($feedback-color, 0.8) 80%,
+{{ activation_collection_prefix }} > li > ul > li > a,
-        rgba($feedback-color, 0) 100%
+{{ 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:
+{%- elsif nav_levels[2] -%}
-{{ 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 {
+{{ activation_collection_prefix }} > li > a,
-      display: block;
+{{ 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:
+{%- else -%}
-.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 {
+{{ activation_collection_prefix }} > li:not(:nth-child({{ nav_levels[1] }})) > a,
-    display: block;
+{{ activation_collection_prefix }} > li > ul > li > a,
-  }
+{{ activation_collection_prefix }} > li > ul > li > ul > li > a {
+  background-image: none;
 }
 
-{%- endunless -%}
+{%- endif %}
-{%- endunless -%}
+
-{%- endunless -%}
+{%- 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 -%}

_includes/fix_linenos.html

@@ -1,29 +1,37 @@
 {%- comment -%}
-This file can be used to fix the HTML produced by Jekyll for highlighted
+This file was previously used to "fix" the HTML produced by Jekyll for
-code with line numbers.
+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 %}`
+The next portion of this file, including the comments and the workaround,
-and with the Kramdown option to add line numbers to fenced code.
+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
+The HTML produced by Rouge highlighting with line numbers is of the form
-`code table`. Jekyll (<= 4.1.1) always wraps the highlighted HTML
+`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`.

_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.
+    css/activation.scss.liquid, head_custom.html.
-  Overwrites: 
+  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: "," %}

_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 %}

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 }}

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.
+// The <head> element is assumed to include the following stylesheets:
-// Moreover, it incorrectly overrides dynamic stylesheets set by setTheme(theme). 
+// - a <link> to /assets/css/just-the-docs-head-nav.css,
-// The page-specific stylesheet is assumed to have index 1 in the list of stylesheets.
+//             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 disableHeadStyleSheet() {
+function disableHeadStyleSheets() {
-  if (document.styleSheets[1]) {
+  const headNav = document.getElementById('jtd-head-nav-stylesheet');
-    document.styleSheets[1].disabled = true;
+  if (headNav) {
+    headNav.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;
+  var pathname = document.location.pathname;
-  if (href.endsWith('/') && href != '/') {
+
-    href = href.slice(0, -1);
+  var navLink = document.getElementById('site-nav').querySelector('a[href="' + pathname + '"]');
+  if (navLink) {
+    return navLink;
   }
-  return document.getElementById('site-nav').querySelector('a[href="' + href + '"], a[href="' + href + '/"]');
+
+  // 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);
+  }
+
+  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();
+    targetLink.scrollIntoView({ block: "center" });
-    document.getElementById('site-nav').scrollBy(0, rect.top - 3*rect.height);
+    targetLink.removeAttribute('href');
   }
 }
 

docs/configuration.md

@@ -66,6 +66,8 @@ search:
   # Enable or disable the search button that appears in the bottom right corner of every page
   # Supports true or false (default)
   button: false
+  # Focus the search input by pressing `ctrl + focus_shortcut_key` (or `cmd + focus_shortcut_key` on macOS)
+  focus_shortcut_key: 'k'
 ```
 
 ## Mermaid Diagrams

docs/navigation-structure.md

@@ -30,7 +30,7 @@ By default, all pages will appear as top level pages in the main nav unless a pa
 
 To specify a page order, you can use the `nav_order` parameter in your pages' YAML front matter.
 
-#### Example
+### Example (ordering pages)
 {: .no_toc }
 
 ```yaml
@@ -55,7 +55,7 @@ By default, all Capital letters come before all lowercase letters; you can add `
 
 For specific pages that you do not wish to include in the main navigation, e.g. a 404 page or a landing page, use the `nav_exclude: true` parameter in the YAML front matter for that page.
 
-#### Example
+### Example (excluding pages)
 {: .no_toc }
 
 ```yaml
@@ -108,7 +108,7 @@ On the parent pages, add this YAML front matter parameter:
 
 - `has_children: true` (tells us that this is a parent page)
 
-#### Example
+### Example (parent pages)
 {: .no_toc }
 
 ```yaml
@@ -129,7 +129,7 @@ Here we're setting up the UI Components landing page that is available at `/docs
 
 On child pages, simply set the `parent:` YAML front matter to whatever the parent's page title is and set a nav order (this number is now scoped within the section).
 
-#### Example
+#### Example (child pages)
 {: .no_toc }
 
 ```yaml
@@ -154,7 +154,7 @@ You can optionally add the following to the YAML front matter to reverse the def
 
 - `child_nav_order: reversed`
 
-#### Example
+#### Example (ordering child pages)
 {: .no_toc }
 ```yaml
 ---
@@ -168,7 +168,7 @@ child_nav_order: reversed
 
 By default, all pages with children will automatically append a Table of Contents which lists the child pages after the parent page's content. To disable this auto Table of Contents, set `has_toc: false` in the parent page's YAML front matter.
 
-#### Example
+#### Example (auto-generating Table of Contents)
 {: .no_toc }
 
 ```yaml
@@ -191,7 +191,7 @@ Child pages can also have children (grandchildren). This is achieved by using a
 1. Add the `has_children` attribute to the child
 1. Add the `parent` and `grand_parent` attribute to the grandchild
 
-#### Example
+##### Example (children within children)
 {: .no_toc }
 
 ```yaml
@@ -237,11 +237,45 @@ Currently, the navigation structure is limited to 3 levels: grandchild pages can
 
 ---
 
+## Grouping pages with collections
+
+Pages can also be grouped together by using Jekyll's and Just the Docs's [collections]({% link docs/configuration.md %}#document-collections) feature. In contrast to using [pages with children](#pages-with-children), pages grouped by collection are grouped by a shared header (the name of the collection) instead of a page.
+
+The `nav_fold` configuration option works for collection-grouped pages. For more information, please refer to the [collections documentation]({% link docs/configuration.md %}#document-collections).
+
+### Example (grouping by collection)
+{: .no_toc }
+
+The following example sets up two collections, `collection-one` and `collection-two`:
+
+- any document placed within `_collection-1/` will be grouped under the `Collection One` header by default. Since `nav_fold` is set to `true`, the pages will be folded by default.
+- any document placed within `_collection-2/` will be grouped under the `Collection Two` header by default. Since `nav_fold` is set to `false`, the pages will be expanded by default.
+
+```yaml
+_config.yml:
+  collections:
+    collection-one:
+      permalink: "/:collection/:path/"
+      output: true
+    collection-two:
+      permalink: "/:collection/:path/"
+      output: true
+  just_the_docs:
+    collections:
+      collection-one:
+        name: Collection One
+        nav_fold: true
+      collection-two:
+        name: Collection Two
+        nav_fold: false
+```
+---
+
 ## Auxiliary Links
 
 To add auxiliary links to your site (in the upper right on all pages), add it to the `aux_links` [configuration option]({% link docs/configuration.md %}#aux-links) in your site's `_config.yml` file.
 
-#### Example
+### Example (auxiliary links)
 {: .no_toc }
 
 ```yaml
@@ -262,7 +296,7 @@ New (v0.4.0)
 To add external links to the navigation, add them to the `nav_external_links` [configuration]({% link docs/configuration.md %}) option in your site's `_config.yml` file.
 External links will appear in the navigation after the links to ordinary pages, but before any collections.
 
-#### Example
+### Example (external navigation links)
 {: .no_toc }
 
 ```yaml
@@ -271,18 +305,32 @@ nav_external_links:
   - title: Just the Docs on GitHub
     url: https://github.com/just-the-docs/just-the-docs
     hide_icon: false # set to true to hide the external link icon - defaults to false
+    opens_in_new_tab: false # set to true to open this link in a new tab - defaults to false
 ```
 
+### Opening external links in a new tab
+{: .d-inline-block }
+
+New (unreleased)
+{: .label .label-green }
+
 The external links are decorated by an icon, which distinguishes them from internal links.
 You can suppress the icon by setting `hide_icon: true`.
 
+By default, external links are not opened in a new tab. However, this can be enabled by:
+
+1. setting `opens_in_new_tab: true` in the link's configuration object
+2. setting the configuration option `nav_external_links_new_tab: true` in `_config.yml`
+
+When they conflict, `opens_in_new_tab` takes precedence.
+
 ---
 
 ## In-page navigation with Table of Contents
 
 To generate a Table of Contents on your docs pages, you can use the `{:toc}` method from Kramdown, immediately after an `<ol>` in Markdown. This will automatically generate an ordered list of anchor links to various sections of the page based on headings and heading levels. There may be occasions where you're using a heading and you don't want it to show up in the TOC, so to skip a particular heading use the `{: .no_toc }` CSS class.
 
-#### Example
+### Example (in-page navigation with Table of Contents)
 {: .no_toc }
 
 ```markdown

docs/search.md

@@ -94,6 +94,21 @@ The search button displays in the bottom right corner of the screen and triggers
 search.button: true
 ```
 
+### Focus search bar with a keyboard shortcut
+
+Just the Docs supports focusing the search bar input with a keyboard shortcut. After setting the `search.focus_shortcut_key` config item key, users who press <kbd>Ctrl</kbd> + `search.focus_shortcut_key` (or on macOS, <kbd>Command</kbd> + `search.focus_shortcut_key`) will focus the search bar.
+
+Note that this feature is **disabled by default**. `search.focus_shortcut_key` should be a [valid value from `KeyboardEvent.key`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key); this involves all ASCII alphanumeric values, as well as modifier keys.
+
+For example,
+
+```yaml
+search:
+    focus_shortcut_key: 'k'
+```
+
+Will make <kbd>Ctrl</kbd> + <kbd>K</kbd> focus the search bar for Windows users (and <kbd>Command</kbd> + <kbd>K</kbd> on macOS).
+
 ## Hiding pages from search
 
 Sometimes you might have a page that you don't want to be indexed for the search nor to show up in search results, e.g., a 404 page.

docs/ui-components/code.md

@@ -58,6 +58,8 @@ var fun = function lang(l) {
 ```
 {% endhighlight %}
 
+Syntax highlighting, line numbers, and HTML compression do not work together; **the combination of these features generates invalid HTML that renders incorrectly**. To learn more, see ["Code with line numbers"]({% link docs/ui-components/line-nos.md %}).
+
 ---
 
 ## Code blocks with rendered examples

docs/ui-components/line-nos.md

@@ -8,8 +8,12 @@ permalink: /docs/ui-components/code/line-numbers/
 
 # Code snippets with line numbers
 
+{: .warning }
+
+In prior versions of the docs, we provided "workarounds" to rendering issues arising from code snippets with line numbers. While these seemed to resolve visual layout issues, they did not resolve core issues with Jekyll generating invalid HTML. See [the detailed explanation](#detailed-error-explanation) for more information.
+
 The default settings for HTML compression are incompatible with the HTML
-produced by Jekyll (4.1.1 or earlier) for line numbers from highlighted code
+produced by Jekyll for line numbers from highlighted code
 -- both when using Kramdown code fences and when using Liquid highlight tags.
 
 To avoid non-conforming HTML and unsatisfactory layout, HTML compression
@@ -40,90 +44,62 @@ Some code
 {% endhighlight %}{% endraw %}
 {% endhighlight %}
 
-## Workarounds
+## Detailed Error Explanation
 
-To use HTML compression together with line numbers, all highlighted code
+Consider this following code snippet, intended to highlight a simple Ruby program:
-needs to be wrapped using one of the following workarounds.
-(The variable name `some_var` can be changed to avoid clashes; it can also
-be replaced by `code` -- but note that `code=code` cannot be removed).
 
-### Code fences (three backticks)
-
-{% highlight default %}
-{% raw %}{% capture some_var %}
-```some_language
-Some code
 ```
-{% endcapture %}
+{% raw %}{% highlight ruby linenos %}
-{% assign some_var = some_var | markdownify %}
-{% include fix_linenos.html code=some_var %}{% endraw %}
-{% endhighlight %}
-
-### Liquid highlighting
-
-{% highlight default %}
-{% raw %}{% capture some_var %}
-{% highlight some_language linenos %}
-Some code
-{% endhighlight %}
-{% endcapture %}
-{% include fix_linenos.html code=some_var %}{% endraw %}
-{% endhighlight %}
-
-_Credit:_ The original version of the above workaround was suggested by
-Dmitry Hrabrov at
-<https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-188144901>.
-
-## Examples
-
-✅ Using code fences + workaround (will only show line numbers if enabled globally in `_config.yml`):
-
-{% capture code_fence %}
-```js
-// Javascript code with syntax highlighting in fences
-var fun = function lang(l) {
-  dateformat.i18n = require('./lang/' + l)
-  return true;
-}
-```
-{% endcapture %}
-{% assign code_fence = code_fence | markdownify %}
-{% include fix_linenos.html code=code_fence %}
-
-✅ Using liquid highlighting + workaround:
-
-{% capture code %}
-{% highlight ruby linenos %}
-# Ruby code with syntax highlighting and fixed line numbers using Liquid
-GitHubPages::Dependencies.gems.each do |gem, version|
-  s.add_dependency(gem, "= #{version}")
-end
-{% endhighlight %}
-{% endcapture %}
-{% include fix_linenos.html code=code %}
-{% assign code = nil %}
-
-Narrow code stays close to the line numbers:
-
-{% capture code %}
-{% highlight ruby linenos %}
 def foo
   puts 'foo'
 end
-{% endhighlight %}
+{% endhighlight %}{% endraw %}
-{% endcapture %}
+```
-{% include fix_linenos.html code=code %}
-{% assign code = nil %}
 
-{: .warning }
+If this is directly placed within a file processed by Jekyll (via Just the Docs, with HTML compression enabled), the following markup will be generated:
-The following generates **incorrect** and **invalid** HTML. It should not be used as a positive example; the improper layout (with the broken HTML tags) is intentional.
 
-❌ With the compression options used for the theme docs, the following example illustrates
+```html
-the **incorrect** formatting arising from the incompatibility of HTML compression
+<figure class="highlight">><code class="language-ruby" data-lang="ruby"><div class="table-wrapper"><table class="rouge-table"><tbody><tr><td class="gutter gl"><pre class="lineno">1
-and the non-conforming HTML produced by Jekyll for line numbers:
+2
+3
+</pre><td class="code"><pre><span class="k">def</span> <span class="nf">foo</span>
+  <span class="nb">puts</span> <span class="s1">'foo'</span>
+<span class="k">end</span>
+</pre></figure>
+```
 
-{% highlight ruby linenos %}
+This HTML is invalid; in particular, there are two issues:
-def foo
+
-  puts 'foo'
+1. there are many missing closing tags, and a superfluous `>`, which produce visually garbled output
-end
+2. a `<table>` is placed within a `<code>` element, which is syntactically invalid HTML (but is often allowed by browsers)
-{% endhighlight %}
+
+To emphasize this first difference, here is the same markup output, indented by tag:
+
+```html
+<figure class="highlight">
+  >
+  <code class="language-ruby" data-lang="ruby">
+    <div class="table-wrapper">
+      <table class="rouge-table">
+        <tbody>
+          <tr>
+            <td class="gutter gl">
+              <pre class="lineno">
+1
+2
+3
+              </pre>
+              <td class="code">
+                <pre>
+<span class="k">def</span>
+<span class="nf">foo</span>
+<span class="nb">puts</span>
+<span class="s1">'foo'</span>
+<span class="k">end</span>
+                </pre>
+</figure>
+```
+
+In order, there are missing `</td>`, `</td>`, `</tr>`, `</tbody>`, `</table>`, `</div>`, and `</code>` tags. As a result, the following elements of the page - including the site footer - become visually garbled as browsers attempt to recover gracefully.
+
+Prior workarounds we suggested (such as [Dmitry Hrabrov's in `jekyll-compress-html`#71](https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-188144901)) resolve the missing tag problem. However, they still place a `<table>` within a `<code>` element. The HTML spec normatively states that `<code>` elements should only contain "[phrasing content](https://html.spec.whatwg.org/multipage/dom.html#phrasing-content-2)", which does not include `<table>` ([spec ref](https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-code-element)). To avoid incorrectly rendered HTML, the previously-suggested workaround using the current version of `_includes/fix_linenos.html` should _not_ be used!

fixtures/html5validator-config.yml

@@ -0,0 +1 @@
+root: _site

just-the-docs.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name          = "just-the-docs"
-  spec.version       = "0.6.2"
+  spec.version       = "0.8.1"
   spec.authors       = ["Patrick Marsceill", "Matthew Wang"]
   spec.email         = ["patrick.marsceill@gmail.com", "matt@matthewwang.me"]
 

package-lock.json

@@ -10,9 +10,9 @@
       "license": "MIT",
       "devDependencies": {
         "npm-run-all": "^4.1.5",
-        "prettier": "^3.0.3",
+        "prettier": "^3.2.5",
-        "stylelint": "^15.10.3",
+        "stylelint": "^15.11.0",
-        "stylelint-config-standard-scss": "^11.0.0"
+        "stylelint-config-standard-scss": "^11.1.0"
       }
     },
     "node_modules/@babel/code-frame": {
@@ -436,12 +436,12 @@
       }
     },
     "node_modules/css-functions-list": {
-      "version": "3.2.0",
+      "version": "3.2.1",
-      "resolved": "https://registry.npmjs.org/css-functions-list/-/css-functions-list-3.2.0.tgz",
+      "resolved": "https://registry.npmjs.org/css-functions-list/-/css-functions-list-3.2.1.tgz",
-      "integrity": "sha512-d/jBMPyYybkkLVypgtGv12R+pIFw4/f/IHtCTxWpZc8ofTYOPigIgmA6vu5rMHartZC+WuXhBUHfnyNUIQSYrg==",
+      "integrity": "sha512-Nj5YcaGgBtuUmn1D7oHqPW0c9iui7xsTsj5lIX8ZgevdfhmjFfKB3r8moHJtNJnctnYXJyYX5I1pp90HM4TPgQ==",
       "dev": true,
       "engines": {
-        "node": ">=12.22"
+        "node": ">=12 || >=16"
       }
     },
     "node_modules/css-tree": {
@@ -703,15 +703,15 @@
       }
     },
     "node_modules/file-entry-cache": {
-      "version": "6.0.1",
+      "version": "7.0.1",
-      "resolved": "https://registry.npmjs.org/file-entry-cache/-/file-entry-cache-6.0.1.tgz",
+      "resolved": "https://registry.npmjs.org/file-entry-cache/-/file-entry-cache-7.0.1.tgz",
-      "integrity": "sha512-7Gps/XWymbLk2QLYK4NzpMOrYjMhdIxXuIvy2QBsLE6ljuodKvdkWs/cpyJJ3CVIVpH0Oi1Hvg1ovbMzLdFBBg==",
+      "integrity": "sha512-uLfFktPmRetVCbHe5UPuekWrQ6hENufnA46qEGbfACkK5drjTTdQYUragRgMjHldcbYG+nslUerqMPjbBSHXjQ==",
       "dev": true,
       "dependencies": {
-        "flat-cache": "^3.0.4"
+        "flat-cache": "^3.1.1"
       },
       "engines": {
-        "node": "^10.12.0 || >=12.0.0"
+        "node": ">=12.0.0"
       }
     },
     "node_modules/fill-range": {
@@ -743,22 +743,23 @@
       }
     },
     "node_modules/flat-cache": {
-      "version": "3.0.4",
+      "version": "3.1.1",
-      "resolved": "https://registry.npmjs.org/flat-cache/-/flat-cache-3.0.4.tgz",
+      "resolved": "https://registry.npmjs.org/flat-cache/-/flat-cache-3.1.1.tgz",
-      "integrity": "sha512-dm9s5Pw7Jc0GvMYbshN6zchCA9RgQlzzEZX3vylR9IqFfS8XciblUXOKfW6SiuJ0e13eDYZoZV5wdrev7P3Nwg==",
+      "integrity": "sha512-/qM2b3LUIaIgviBQovTLvijfyOQXPtSRnRK26ksj2J7rzPIecePUIpJsZ4T02Qg+xiAEKIs5K8dsHEd+VaKa/Q==",
       "dev": true,
       "dependencies": {
-        "flatted": "^3.1.0",
+        "flatted": "^3.2.9",
+        "keyv": "^4.5.3",
         "rimraf": "^3.0.2"
       },
       "engines": {
-        "node": "^10.12.0 || >=12.0.0"
+        "node": ">=12.0.0"
       }
     },
     "node_modules/flatted": {
-      "version": "3.2.5",
+      "version": "3.2.9",
-      "resolved": "https://registry.npmjs.org/flatted/-/flatted-3.2.5.tgz",
+      "resolved": "https://registry.npmjs.org/flatted/-/flatted-3.2.9.tgz",
-      "integrity": "sha512-WIWGi2L3DyTUvUrwRKgGi9TwxQMUEqPOPQBVi71R96jZXJdFskXEmf54BoZaS1kknGODoIGASGEzBUYdyMCBJg==",
+      "integrity": "sha512-36yxDn5H7OFZQla0/jFJmbIKTdZAQHngCedGxiMmpNfEZM0sdEeT+WczLQrjK6D7o2aiyLYDnkw0R3JK0Qv1RQ==",
       "dev": true
     },
     "node_modules/for-each": {
@@ -773,7 +774,7 @@
     "node_modules/fs.realpath": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz",
-      "integrity": "sha1-FQStJSMVjKpA20onh8sBQRmU6k8=",
+      "integrity": "sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==",
       "dev": true
     },
     "node_modules/function-bind": {
@@ -840,15 +841,15 @@
       }
     },
     "node_modules/glob": {
-      "version": "7.2.0",
+      "version": "7.2.3",
-      "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.0.tgz",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz",
-      "integrity": "sha512-lmLf6gtyrPq8tTjSmrO94wBeQbFR3HbLHbuyD69wuyQkImp2hWqMGB47OX65FBkPffO641IP9jWa1z4ivqG26Q==",
+      "integrity": "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==",
       "dev": true,
       "dependencies": {
         "fs.realpath": "^1.0.0",
         "inflight": "^1.0.4",
         "inherits": "2",
-        "minimatch": "^3.0.4",
+        "minimatch": "^3.1.1",
         "once": "^1.3.0",
         "path-is-absolute": "^1.0.0"
       },
@@ -1137,7 +1138,7 @@
     "node_modules/inflight": {
       "version": "1.0.6",
       "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz",
-      "integrity": "sha1-Sb1jMdfQLQwJvJEKEHW6gWW1bfk=",
+      "integrity": "sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA==",
       "dev": true,
       "dependencies": {
         "once": "^1.3.0",
@@ -1454,6 +1455,12 @@
         "js-yaml": "bin/js-yaml.js"
       }
     },
+    "node_modules/json-buffer": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/json-buffer/-/json-buffer-3.0.1.tgz",
+      "integrity": "sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ==",
+      "dev": true
+    },
     "node_modules/json-parse-better-errors": {
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/json-parse-better-errors/-/json-parse-better-errors-1.0.2.tgz",
@@ -1472,6 +1479,15 @@
       "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
       "dev": true
     },
+    "node_modules/keyv": {
+      "version": "4.5.4",
+      "resolved": "https://registry.npmjs.org/keyv/-/keyv-4.5.4.tgz",
+      "integrity": "sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw==",
+      "dev": true,
+      "dependencies": {
+        "json-buffer": "3.0.1"
+      }
+    },
     "node_modules/kind-of": {
       "version": "6.0.3",
       "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.3.tgz",
@@ -1482,9 +1498,9 @@
       }
     },
     "node_modules/known-css-properties": {
-      "version": "0.28.0",
+      "version": "0.29.0",
-      "resolved": "https://registry.npmjs.org/known-css-properties/-/known-css-properties-0.28.0.tgz",
+      "resolved": "https://registry.npmjs.org/known-css-properties/-/known-css-properties-0.29.0.tgz",
-      "integrity": "sha512-9pSL5XB4J+ifHP0e0jmmC98OGC1nL8/JjS+fi6mnTlIf//yt/MfVLtKg7S6nCtj/8KTcWX7nRlY0XywoYY1ISQ==",
+      "integrity": "sha512-Ne7wqW7/9Cz54PDt4I3tcV+hAyat8ypyOGzYRJQfdxnnjeWsTxt1cy8pjvvKeI5kfXuyvULyeeAvwvvtAX3ayQ==",
       "dev": true
     },
     "node_modules/lines-and-columns": {
@@ -1845,7 +1861,7 @@
     "node_modules/once": {
       "version": "1.4.0",
       "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
-      "integrity": "sha1-WDsap3WWHUsROsF9nFC6753Xa9E=",
+      "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==",
       "dev": true,
       "dependencies": {
         "wrappy": "1"
@@ -1923,7 +1939,7 @@
     "node_modules/path-is-absolute": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz",
-      "integrity": "sha1-F0uSaHNVNP+8es5r9TpanhtcX18=",
+      "integrity": "sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg==",
       "dev": true,
       "engines": {
         "node": ">=0.10.0"
@@ -1993,9 +2009,9 @@
       }
     },
     "node_modules/postcss": {
-      "version": "8.4.28",
+      "version": "8.4.31",
-      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.4.28.tgz",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.4.31.tgz",
-      "integrity": "sha512-Z7V5j0cq8oEKyejIKfpD8b4eBy9cwW2JWPk0+fB1HOAMsfHbnAXLLS+PfVWlzMSLQaWttKDt607I0XHmpE67Vw==",
+      "integrity": "sha512-PS08Iboia9mts/2ygV3eLpY5ghnUcfLV/EXTOW1E2qYxJKGGBUtNjN76FYHnMs36RmARn41bC0AZmn+rR0OVpQ==",
       "dev": true,
       "funding": [
         {
@@ -2049,9 +2065,9 @@
       }
     },
     "node_modules/postcss-scss": {
-      "version": "4.0.7",
+      "version": "4.0.9",
-      "resolved": "https://registry.npmjs.org/postcss-scss/-/postcss-scss-4.0.7.tgz",
+      "resolved": "https://registry.npmjs.org/postcss-scss/-/postcss-scss-4.0.9.tgz",
-      "integrity": "sha512-xPv2GseoyXPa58Nro7M73ZntttusuCmZdeOojUFR5PZDz2BR62vfYx1w9TyOnp1+nYFowgOMipsCBhxzVkAEPw==",
+      "integrity": "sha512-AjKOeiwAitL/MXxQW2DliT28EKukvvbEWx3LBmJIRN8KfBGZbRTxNYW0kSqi1COiTZ57nZ9NW06S6ux//N1c9A==",
       "dev": true,
       "funding": [
         {
@@ -2071,7 +2087,7 @@
         "node": ">=12.0"
       },
       "peerDependencies": {
-        "postcss": "^8.4.19"
+        "postcss": "^8.4.29"
       }
     },
     "node_modules/postcss-selector-parser": {
@@ -2094,9 +2110,9 @@
       "dev": true
     },
     "node_modules/prettier": {
-      "version": "3.0.3",
+      "version": "3.2.5",
-      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.0.3.tgz",
+      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.2.5.tgz",
-      "integrity": "sha512-L/4pUDMxcNa8R/EthV08Zt42WBO4h1rarVtK0K+QJG0X187OLo7l699jWw0GKuwzkPQ//jMFA/8Xm6Fh3J/DAg==",
+      "integrity": "sha512-3/GWa9aOC0YeD7LUfvOG2NiDyhOWRvt1k+rcKhOuYnMY24iiCphgneUfJDyFXd6rZCAnuLBv6UeAULtrhT/F4A==",
       "dev": true,
       "bin": {
         "prettier": "bin/prettier.cjs"
@@ -2587,9 +2603,9 @@
       "dev": true
     },
     "node_modules/stylelint": {
-      "version": "15.10.3",
+      "version": "15.11.0",
-      "resolved": "https://registry.npmjs.org/stylelint/-/stylelint-15.10.3.tgz",
+      "resolved": "https://registry.npmjs.org/stylelint/-/stylelint-15.11.0.tgz",
-      "integrity": "sha512-aBQMMxYvFzJJwkmg+BUUg3YfPyeuCuKo2f+LOw7yYbU8AZMblibwzp9OV4srHVeQldxvSFdz0/Xu8blq2AesiA==",
+      "integrity": "sha512-78O4c6IswZ9TzpcIiQJIN49K3qNoXTM8zEJzhaTE/xRTCZswaovSEVIa/uwbOltZrk16X4jAxjaOhzz/hTm1Kw==",
       "dev": true,
       "dependencies": {
         "@csstools/css-parser-algorithms": "^2.3.1",
@@ -2599,12 +2615,12 @@
         "balanced-match": "^2.0.0",
         "colord": "^2.9.3",
         "cosmiconfig": "^8.2.0",
-        "css-functions-list": "^3.2.0",
+        "css-functions-list": "^3.2.1",
         "css-tree": "^2.3.1",
         "debug": "^4.3.4",
         "fast-glob": "^3.3.1",
         "fastest-levenshtein": "^1.0.16",
-        "file-entry-cache": "^6.0.1",
+        "file-entry-cache": "^7.0.0",
         "global-modules": "^2.0.0",
         "globby": "^11.1.0",
         "globjoin": "^0.1.4",
@@ -2613,13 +2629,13 @@
         "import-lazy": "^4.0.0",
         "imurmurhash": "^0.1.4",
         "is-plain-object": "^5.0.0",
-        "known-css-properties": "^0.28.0",
+        "known-css-properties": "^0.29.0",
         "mathml-tag-names": "^2.1.3",
         "meow": "^10.1.5",
         "micromatch": "^4.0.5",
         "normalize-path": "^3.0.0",
         "picocolors": "^1.0.0",
-        "postcss": "^8.4.27",
+        "postcss": "^8.4.28",
         "postcss-resolve-nested-selector": "^0.1.1",
         "postcss-safe-parser": "^6.0.0",
         "postcss-selector-parser": "^6.0.13",
@@ -2657,14 +2673,14 @@
       }
     },
     "node_modules/stylelint-config-recommended-scss": {
-      "version": "13.0.0",
+      "version": "13.1.0",
-      "resolved": "https://registry.npmjs.org/stylelint-config-recommended-scss/-/stylelint-config-recommended-scss-13.0.0.tgz",
+      "resolved": "https://registry.npmjs.org/stylelint-config-recommended-scss/-/stylelint-config-recommended-scss-13.1.0.tgz",
-      "integrity": "sha512-7AmMIsHTsuwUQm7I+DD5BGeIgCvqYZ4BpeYJJpb1cUXQwrJAKjA+GBotFZgUEGP8lAM+wmd91ovzOi8xfAyWEw==",
+      "integrity": "sha512-8L5nDfd+YH6AOoBGKmhH8pLWF1dpfY816JtGMePcBqqSsLU+Ysawx44fQSlMOJ2xTfI9yTGpup5JU77c17w1Ww==",
       "dev": true,
       "dependencies": {
-        "postcss-scss": "^4.0.7",
+        "postcss-scss": "^4.0.9",
         "stylelint-config-recommended": "^13.0.0",
-        "stylelint-scss": "^5.1.0"
+        "stylelint-scss": "^5.3.0"
       },
       "peerDependencies": {
         "postcss": "^8.3.3",
@@ -2692,12 +2708,12 @@
       }
     },
     "node_modules/stylelint-config-standard-scss": {
-      "version": "11.0.0",
+      "version": "11.1.0",
-      "resolved": "https://registry.npmjs.org/stylelint-config-standard-scss/-/stylelint-config-standard-scss-11.0.0.tgz",
+      "resolved": "https://registry.npmjs.org/stylelint-config-standard-scss/-/stylelint-config-standard-scss-11.1.0.tgz",
-      "integrity": "sha512-fGE79NBOLg09a9afqGH/guJulRULCaQWWv4cv1v2bMX92B+fGb0y56WqIguwvFcliPmmUXiAhKrrnXilIeXoHA==",
+      "integrity": "sha512-5gnBgeNTgRVdchMwiFQPuBOtj9QefYtfXiddrOMJA2pI22zxt6ddI2s+e5Oh7/6QYl7QLJujGnaUR5YyGq72ow==",
       "dev": true,
       "dependencies": {
-        "stylelint-config-recommended-scss": "^13.0.0",
+        "stylelint-config-recommended-scss": "^13.1.0",
         "stylelint-config-standard": "^34.0.0"
       },
       "peerDependencies": {
@@ -2711,11 +2727,12 @@
       }
     },
     "node_modules/stylelint-scss": {
-      "version": "5.1.0",
+      "version": "5.3.0",
-      "resolved": "https://registry.npmjs.org/stylelint-scss/-/stylelint-scss-5.1.0.tgz",
+      "resolved": "https://registry.npmjs.org/stylelint-scss/-/stylelint-scss-5.3.0.tgz",
-      "integrity": "sha512-E+KlQFXv1Euha43qw3q+wKBSli557wxbbo6/39DWhRNXlUa9Cz+FYrcgz+PT6ag0l6UisCYjAGCNhoSl4FcwlA==",
+      "integrity": "sha512-Sc7S1uWqStMc99NREsHNxpxHHFRvjo2pWILNl/UCwWO8PxhODK8qbJH0GHWIALxl6BD5rwJL4cSm4jk36hi6fg==",
       "dev": true,
       "dependencies": {
+        "known-css-properties": "^0.28.0",
         "postcss-media-query-parser": "^0.2.3",
         "postcss-resolve-nested-selector": "^0.1.1",
         "postcss-selector-parser": "^6.0.13",
@@ -2725,6 +2742,12 @@
         "stylelint": "^14.5.1 || ^15.0.0"
       }
     },
+    "node_modules/stylelint-scss/node_modules/known-css-properties": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/known-css-properties/-/known-css-properties-0.28.0.tgz",
+      "integrity": "sha512-9pSL5XB4J+ifHP0e0jmmC98OGC1nL8/JjS+fi6mnTlIf//yt/MfVLtKg7S6nCtj/8KTcWX7nRlY0XywoYY1ISQ==",
+      "dev": true
+    },
     "node_modules/supports-color": {
       "version": "5.5.0",
       "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz",
@@ -2946,7 +2969,7 @@
     "node_modules/wrappy": {
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
-      "integrity": "sha1-tSQ9jz7BqjXxNkYFvA0QNuMKtp8=",
+      "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
       "dev": true
     },
     "node_modules/write-file-atomic": {
@@ -3278,9 +3301,9 @@
       }
     },
     "css-functions-list": {
-      "version": "3.2.0",
+      "version": "3.2.1",
-      "resolved": "https://registry.npmjs.org/css-functions-list/-/css-functions-list-3.2.0.tgz",
+      "resolved": "https://registry.npmjs.org/css-functions-list/-/css-functions-list-3.2.1.tgz",
-      "integrity": "sha512-d/jBMPyYybkkLVypgtGv12R+pIFw4/f/IHtCTxWpZc8ofTYOPigIgmA6vu5rMHartZC+WuXhBUHfnyNUIQSYrg==",
+      "integrity": "sha512-Nj5YcaGgBtuUmn1D7oHqPW0c9iui7xsTsj5lIX8ZgevdfhmjFfKB3r8moHJtNJnctnYXJyYX5I1pp90HM4TPgQ==",
       "dev": true
     },
     "css-tree": {
@@ -3476,12 +3499,12 @@
       }
     },
     "file-entry-cache": {
-      "version": "6.0.1",
+      "version": "7.0.1",
-      "resolved": "https://registry.npmjs.org/file-entry-cache/-/file-entry-cache-6.0.1.tgz",
+      "resolved": "https://registry.npmjs.org/file-entry-cache/-/file-entry-cache-7.0.1.tgz",
-      "integrity": "sha512-7Gps/XWymbLk2QLYK4NzpMOrYjMhdIxXuIvy2QBsLE6ljuodKvdkWs/cpyJJ3CVIVpH0Oi1Hvg1ovbMzLdFBBg==",
+      "integrity": "sha512-uLfFktPmRetVCbHe5UPuekWrQ6hENufnA46qEGbfACkK5drjTTdQYUragRgMjHldcbYG+nslUerqMPjbBSHXjQ==",
       "dev": true,
       "requires": {
-        "flat-cache": "^3.0.4"
+        "flat-cache": "^3.1.1"
       }
     },
     "fill-range": {
@@ -3504,19 +3527,20 @@
       }
     },
     "flat-cache": {
-      "version": "3.0.4",
+      "version": "3.1.1",
-      "resolved": "https://registry.npmjs.org/flat-cache/-/flat-cache-3.0.4.tgz",
+      "resolved": "https://registry.npmjs.org/flat-cache/-/flat-cache-3.1.1.tgz",
-      "integrity": "sha512-dm9s5Pw7Jc0GvMYbshN6zchCA9RgQlzzEZX3vylR9IqFfS8XciblUXOKfW6SiuJ0e13eDYZoZV5wdrev7P3Nwg==",
+      "integrity": "sha512-/qM2b3LUIaIgviBQovTLvijfyOQXPtSRnRK26ksj2J7rzPIecePUIpJsZ4T02Qg+xiAEKIs5K8dsHEd+VaKa/Q==",
       "dev": true,
       "requires": {
-        "flatted": "^3.1.0",
+        "flatted": "^3.2.9",
+        "keyv": "^4.5.3",
         "rimraf": "^3.0.2"
       }
     },
     "flatted": {
-      "version": "3.2.5",
+      "version": "3.2.9",
-      "resolved": "https://registry.npmjs.org/flatted/-/flatted-3.2.5.tgz",
+      "resolved": "https://registry.npmjs.org/flatted/-/flatted-3.2.9.tgz",
-      "integrity": "sha512-WIWGi2L3DyTUvUrwRKgGi9TwxQMUEqPOPQBVi71R96jZXJdFskXEmf54BoZaS1kknGODoIGASGEzBUYdyMCBJg==",
+      "integrity": "sha512-36yxDn5H7OFZQla0/jFJmbIKTdZAQHngCedGxiMmpNfEZM0sdEeT+WczLQrjK6D7o2aiyLYDnkw0R3JK0Qv1RQ==",
       "dev": true
     },
     "for-each": {
@@ -3531,7 +3555,7 @@
     "fs.realpath": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz",
-      "integrity": "sha1-FQStJSMVjKpA20onh8sBQRmU6k8=",
+      "integrity": "sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==",
       "dev": true
     },
     "function-bind": {
@@ -3580,15 +3604,15 @@
       }
     },
     "glob": {
-      "version": "7.2.0",
+      "version": "7.2.3",
-      "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.0.tgz",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz",
-      "integrity": "sha512-lmLf6gtyrPq8tTjSmrO94wBeQbFR3HbLHbuyD69wuyQkImp2hWqMGB47OX65FBkPffO641IP9jWa1z4ivqG26Q==",
+      "integrity": "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==",
       "dev": true,
       "requires": {
         "fs.realpath": "^1.0.0",
         "inflight": "^1.0.4",
         "inherits": "2",
-        "minimatch": "^3.0.4",
+        "minimatch": "^3.1.1",
         "once": "^1.3.0",
         "path-is-absolute": "^1.0.0"
       }
@@ -3783,7 +3807,7 @@
     "inflight": {
       "version": "1.0.6",
       "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz",
-      "integrity": "sha1-Sb1jMdfQLQwJvJEKEHW6gWW1bfk=",
+      "integrity": "sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA==",
       "dev": true,
       "requires": {
         "once": "^1.3.0",
@@ -4007,6 +4031,12 @@
         "argparse": "^2.0.1"
       }
     },
+    "json-buffer": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/json-buffer/-/json-buffer-3.0.1.tgz",
+      "integrity": "sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ==",
+      "dev": true
+    },
     "json-parse-better-errors": {
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/json-parse-better-errors/-/json-parse-better-errors-1.0.2.tgz",
@@ -4025,6 +4055,15 @@
       "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
       "dev": true
     },
+    "keyv": {
+      "version": "4.5.4",
+      "resolved": "https://registry.npmjs.org/keyv/-/keyv-4.5.4.tgz",
+      "integrity": "sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw==",
+      "dev": true,
+      "requires": {
+        "json-buffer": "3.0.1"
+      }
+    },
     "kind-of": {
       "version": "6.0.3",
       "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.3.tgz",
@@ -4032,9 +4071,9 @@
       "dev": true
     },
     "known-css-properties": {
-      "version": "0.28.0",
+      "version": "0.29.0",
-      "resolved": "https://registry.npmjs.org/known-css-properties/-/known-css-properties-0.28.0.tgz",
+      "resolved": "https://registry.npmjs.org/known-css-properties/-/known-css-properties-0.29.0.tgz",
-      "integrity": "sha512-9pSL5XB4J+ifHP0e0jmmC98OGC1nL8/JjS+fi6mnTlIf//yt/MfVLtKg7S6nCtj/8KTcWX7nRlY0XywoYY1ISQ==",
+      "integrity": "sha512-Ne7wqW7/9Cz54PDt4I3tcV+hAyat8ypyOGzYRJQfdxnnjeWsTxt1cy8pjvvKeI5kfXuyvULyeeAvwvvtAX3ayQ==",
       "dev": true
     },
     "lines-and-columns": {
@@ -4303,7 +4342,7 @@
     "once": {
       "version": "1.4.0",
       "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
-      "integrity": "sha1-WDsap3WWHUsROsF9nFC6753Xa9E=",
+      "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==",
       "dev": true,
       "requires": {
         "wrappy": "1"
@@ -4357,7 +4396,7 @@
     "path-is-absolute": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz",
-      "integrity": "sha1-F0uSaHNVNP+8es5r9TpanhtcX18=",
+      "integrity": "sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg==",
       "dev": true
     },
     "path-key": {
@@ -4403,9 +4442,9 @@
       "dev": true
     },
     "postcss": {
-      "version": "8.4.28",
+      "version": "8.4.31",
-      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.4.28.tgz",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.4.31.tgz",
-      "integrity": "sha512-Z7V5j0cq8oEKyejIKfpD8b4eBy9cwW2JWPk0+fB1HOAMsfHbnAXLLS+PfVWlzMSLQaWttKDt607I0XHmpE67Vw==",
+      "integrity": "sha512-PS08Iboia9mts/2ygV3eLpY5ghnUcfLV/EXTOW1E2qYxJKGGBUtNjN76FYHnMs36RmARn41bC0AZmn+rR0OVpQ==",
       "dev": true,
       "requires": {
         "nanoid": "^3.3.6",
@@ -4433,9 +4472,9 @@
       "requires": {}
     },
     "postcss-scss": {
-      "version": "4.0.7",
+      "version": "4.0.9",
-      "resolved": "https://registry.npmjs.org/postcss-scss/-/postcss-scss-4.0.7.tgz",
+      "resolved": "https://registry.npmjs.org/postcss-scss/-/postcss-scss-4.0.9.tgz",
-      "integrity": "sha512-xPv2GseoyXPa58Nro7M73ZntttusuCmZdeOojUFR5PZDz2BR62vfYx1w9TyOnp1+nYFowgOMipsCBhxzVkAEPw==",
+      "integrity": "sha512-AjKOeiwAitL/MXxQW2DliT28EKukvvbEWx3LBmJIRN8KfBGZbRTxNYW0kSqi1COiTZ57nZ9NW06S6ux//N1c9A==",
       "dev": true,
       "requires": {}
     },
@@ -4456,9 +4495,9 @@
       "dev": true
     },
     "prettier": {
-      "version": "3.0.3",
+      "version": "3.2.5",
-      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.0.3.tgz",
+      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.2.5.tgz",
-      "integrity": "sha512-L/4pUDMxcNa8R/EthV08Zt42WBO4h1rarVtK0K+QJG0X187OLo7l699jWw0GKuwzkPQ//jMFA/8Xm6Fh3J/DAg==",
+      "integrity": "sha512-3/GWa9aOC0YeD7LUfvOG2NiDyhOWRvt1k+rcKhOuYnMY24iiCphgneUfJDyFXd6rZCAnuLBv6UeAULtrhT/F4A==",
       "dev": true
     },
     "punycode": {
@@ -4784,9 +4823,9 @@
       "dev": true
     },
     "stylelint": {
-      "version": "15.10.3",
+      "version": "15.11.0",
-      "resolved": "https://registry.npmjs.org/stylelint/-/stylelint-15.10.3.tgz",
+      "resolved": "https://registry.npmjs.org/stylelint/-/stylelint-15.11.0.tgz",
-      "integrity": "sha512-aBQMMxYvFzJJwkmg+BUUg3YfPyeuCuKo2f+LOw7yYbU8AZMblibwzp9OV4srHVeQldxvSFdz0/Xu8blq2AesiA==",
+      "integrity": "sha512-78O4c6IswZ9TzpcIiQJIN49K3qNoXTM8zEJzhaTE/xRTCZswaovSEVIa/uwbOltZrk16X4jAxjaOhzz/hTm1Kw==",
       "dev": true,
       "requires": {
         "@csstools/css-parser-algorithms": "^2.3.1",
@@ -4796,12 +4835,12 @@
         "balanced-match": "^2.0.0",
         "colord": "^2.9.3",
         "cosmiconfig": "^8.2.0",
-        "css-functions-list": "^3.2.0",
+        "css-functions-list": "^3.2.1",
         "css-tree": "^2.3.1",
         "debug": "^4.3.4",
         "fast-glob": "^3.3.1",
         "fastest-levenshtein": "^1.0.16",
-        "file-entry-cache": "^6.0.1",
+        "file-entry-cache": "^7.0.0",
         "global-modules": "^2.0.0",
         "globby": "^11.1.0",
         "globjoin": "^0.1.4",
@@ -4810,13 +4849,13 @@
         "import-lazy": "^4.0.0",
         "imurmurhash": "^0.1.4",
         "is-plain-object": "^5.0.0",
-        "known-css-properties": "^0.28.0",
+        "known-css-properties": "^0.29.0",
         "mathml-tag-names": "^2.1.3",
         "meow": "^10.1.5",
         "micromatch": "^4.0.5",
         "normalize-path": "^3.0.0",
         "picocolors": "^1.0.0",
-        "postcss": "^8.4.27",
+        "postcss": "^8.4.28",
         "postcss-resolve-nested-selector": "^0.1.1",
         "postcss-safe-parser": "^6.0.0",
         "postcss-selector-parser": "^6.0.13",
@@ -4839,14 +4878,14 @@
       "requires": {}
     },
     "stylelint-config-recommended-scss": {
-      "version": "13.0.0",
+      "version": "13.1.0",
-      "resolved": "https://registry.npmjs.org/stylelint-config-recommended-scss/-/stylelint-config-recommended-scss-13.0.0.tgz",
+      "resolved": "https://registry.npmjs.org/stylelint-config-recommended-scss/-/stylelint-config-recommended-scss-13.1.0.tgz",
-      "integrity": "sha512-7AmMIsHTsuwUQm7I+DD5BGeIgCvqYZ4BpeYJJpb1cUXQwrJAKjA+GBotFZgUEGP8lAM+wmd91ovzOi8xfAyWEw==",
+      "integrity": "sha512-8L5nDfd+YH6AOoBGKmhH8pLWF1dpfY816JtGMePcBqqSsLU+Ysawx44fQSlMOJ2xTfI9yTGpup5JU77c17w1Ww==",
       "dev": true,
       "requires": {
-        "postcss-scss": "^4.0.7",
+        "postcss-scss": "^4.0.9",
         "stylelint-config-recommended": "^13.0.0",
-        "stylelint-scss": "^5.1.0"
+        "stylelint-scss": "^5.3.0"
       }
     },
     "stylelint-config-standard": {
@@ -4859,25 +4898,34 @@
       }
     },
     "stylelint-config-standard-scss": {
-      "version": "11.0.0",
+      "version": "11.1.0",
-      "resolved": "https://registry.npmjs.org/stylelint-config-standard-scss/-/stylelint-config-standard-scss-11.0.0.tgz",
+      "resolved": "https://registry.npmjs.org/stylelint-config-standard-scss/-/stylelint-config-standard-scss-11.1.0.tgz",
-      "integrity": "sha512-fGE79NBOLg09a9afqGH/guJulRULCaQWWv4cv1v2bMX92B+fGb0y56WqIguwvFcliPmmUXiAhKrrnXilIeXoHA==",
+      "integrity": "sha512-5gnBgeNTgRVdchMwiFQPuBOtj9QefYtfXiddrOMJA2pI22zxt6ddI2s+e5Oh7/6QYl7QLJujGnaUR5YyGq72ow==",
       "dev": true,
       "requires": {
-        "stylelint-config-recommended-scss": "^13.0.0",
+        "stylelint-config-recommended-scss": "^13.1.0",
         "stylelint-config-standard": "^34.0.0"
       }
     },
     "stylelint-scss": {
-      "version": "5.1.0",
+      "version": "5.3.0",
-      "resolved": "https://registry.npmjs.org/stylelint-scss/-/stylelint-scss-5.1.0.tgz",
+      "resolved": "https://registry.npmjs.org/stylelint-scss/-/stylelint-scss-5.3.0.tgz",
-      "integrity": "sha512-E+KlQFXv1Euha43qw3q+wKBSli557wxbbo6/39DWhRNXlUa9Cz+FYrcgz+PT6ag0l6UisCYjAGCNhoSl4FcwlA==",
+      "integrity": "sha512-Sc7S1uWqStMc99NREsHNxpxHHFRvjo2pWILNl/UCwWO8PxhODK8qbJH0GHWIALxl6BD5rwJL4cSm4jk36hi6fg==",
       "dev": true,
       "requires": {
+        "known-css-properties": "^0.28.0",
         "postcss-media-query-parser": "^0.2.3",
         "postcss-resolve-nested-selector": "^0.1.1",
         "postcss-selector-parser": "^6.0.13",
         "postcss-value-parser": "^4.2.0"
+      },
+      "dependencies": {
+        "known-css-properties": {
+          "version": "0.28.0",
+          "resolved": "https://registry.npmjs.org/known-css-properties/-/known-css-properties-0.28.0.tgz",
+          "integrity": "sha512-9pSL5XB4J+ifHP0e0jmmC98OGC1nL8/JjS+fi6mnTlIf//yt/MfVLtKg7S6nCtj/8KTcWX7nRlY0XywoYY1ISQ==",
+          "dev": true
+        }
       }
     },
     "supports-color": {
@@ -5049,7 +5097,7 @@
     "wrappy": {
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
-      "integrity": "sha1-tSQ9jz7BqjXxNkYFvA0QNuMKtp8=",
+      "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
       "dev": true
     },
     "write-file-atomic": {

package.json

@@ -7,9 +7,9 @@
   "bugs": "https://github.com/just-the-docs/just-the-docs/issues",
   "devDependencies": {
     "npm-run-all": "^4.1.5",
-    "prettier": "^3.0.3",
+    "prettier": "^3.2.5",
-    "stylelint": "^15.10.3",
+    "stylelint": "^15.11.0",
-    "stylelint-config-standard-scss": "^11.0.0"
+    "stylelint-config-standard-scss": "^11.1.0"
   },
   "scripts": {
     "lint": "npm-run-all --parallel --continue-on-error lint:*",