Bump nokogiri from 1.18.3 to 1.18.4 (#1631)

Bumps [nokogiri](https://github.com/sparklemotion/nokogiri) from 1.18.3 to 1.18.4.
- [Release notes](https://github.com/sparklemotion/nokogiri/releases)
- [Changelog](https://github.com/sparklemotion/nokogiri/blob/main/CHANGELOG.md)
- [Commits](https://github.com/sparklemotion/nokogiri/compare/v1.18.3...v1.18.4)

---
updated-dependencies:
- dependency-name: nokogiri
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

.github/workflows/ci.yml

@@ -15,54 +15,54 @@ jobs:
       fail-fast: false
       matrix:
         jekyll-version: [3.9, 4.3]
-        os: [ ubuntu-latest, macos-latest, windows-latest ]
-        ruby-version: ["3.0", "3.1", "3.2"]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        ruby-version: ["3.1", "3.2", "3.3", "3.4"]
     runs-on: ${{ matrix.os }}
     steps:
-    - uses: actions/checkout@v4
-    - name: Setup Ruby ${{ matrix.ruby-version }}
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{ matrix.ruby-version }}
-        bundler-cache: false
-    - name: Bundle Install (Jekyll ${{ matrix.jekyll-version }})
-      run: bundle install
-      env:
-        BUNDLE_GEMFILE: fixtures/Gemfile-jekyll-${{ matrix.jekyll-version }}
-    - name: Init Search
-      run: bundle exec rake search:init
-      env:
-        BUNDLE_GEMFILE: fixtures/Gemfile-jekyll-${{ matrix.jekyll-version }}
-    - name: Build Site
-      run: bundle exec jekyll build
-      env:
-        BUNDLE_GEMFILE: fixtures/Gemfile-jekyll-${{ matrix.jekyll-version }}
+      - uses: actions/checkout@v4
+      - name: Setup Ruby ${{ matrix.ruby-version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: false
+      - name: Bundle Install (Jekyll ${{ matrix.jekyll-version }})
+        run: bundle install
+        env:
+          BUNDLE_GEMFILE: fixtures/Gemfile-jekyll-${{ matrix.jekyll-version }}
+      - name: Init Search
+        run: bundle exec rake search:init
+        env:
+          BUNDLE_GEMFILE: fixtures/Gemfile-jekyll-${{ matrix.jekyll-version }}
+      - name: Build Site
+        run: bundle exec jekyll build
+        env:
+          BUNDLE_GEMFILE: fixtures/Gemfile-jekyll-${{ matrix.jekyll-version }}
 
   github-pages-build:
     name: Build (github-pages gem)
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
-    - name: Setup Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: "3.2"
-        bundler-cache: false
-    - name: Bundle Install
-      run: bundle install
-      env:
-        BUNDLE_GEMFILE: fixtures/Gemfile-github-pages
-    - name: Build Site
-      run: bundle exec jekyll build
-      env:
-        BUNDLE_GEMFILE: fixtures/Gemfile-github-pages
+      - uses: actions/checkout@v4
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: false
+      - name: Bundle Install
+        run: bundle install
+        env:
+          BUNDLE_GEMFILE: fixtures/Gemfile-github-pages
+      - name: Build Site
+        run: bundle exec jekyll build
+        env:
+          BUNDLE_GEMFILE: fixtures/Gemfile-github-pages
 
   validate:
     name: Validate HTML
     strategy:
       fail-fast: false
       matrix:
-        ruby-version: ["3.2"]
+        ruby-version: ["3.4"]
     runs-on: ubuntu-latest
 
     steps:
@@ -86,7 +86,7 @@ jobs:
         with:
           config: fixtures/html5validator-config.yml
       - name: Test with html-proofer
-        run: bundle exec htmlproofer _site --ignore-urls "/github.com/,/web.archive.org/"
+        run: bundle exec htmlproofer _site --ignore-urls "/github.com/,/web.archive.org/,/flickr.com/"
         env:
           NOKOGIRI_USE_SYSTEM_LIBRARIES: true
 
@@ -96,13 +96,13 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [18.x]
+        node-version: [22.x]
 
     steps:
-    - uses: actions/checkout@v4
-    - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v3
-      with:
-        node-version: ${{ matrix.node-version }}
-    - run: npm install
-    - run: npm test
+      - uses: actions/checkout@v4
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm install
+      - run: npm test

.github/workflows/deploy.yml

@@ -34,7 +34,7 @@ jobs:
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: "3.2"
+          ruby-version: "3.4"
           bundler-cache: true # runs 'bundle install' and caches installed gems automatically
           cache-version: 0 # Increment this number if you need to re-download cached gems
       - name: Setup Pages
@@ -47,7 +47,9 @@ jobs:
           JEKYLL_ENV: production
       - name: Upload artifact
         # Automatically uploads an artifact from the './_site' directory by default
-        uses: actions/upload-pages-artifact@v2
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
 
   # Deployment job
   deploy:
@@ -59,4 +61,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v2
+        uses: actions/deploy-pages@v4

.github/workflows/publish-gem.yml

@@ -1,7 +1,6 @@
 name: Publish Ruby Gem
 
-on:
-  workflow_dispatch
+on: workflow_dispatch
 
 jobs:
   build:
@@ -9,23 +8,23 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
-    - name: Setup Ruby 3.2
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: "3.2"
+      - uses: actions/checkout@v4
+      - name: Setup Ruby 3.4
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
 
-    - name: Publish to GPR
-      run: |
-        mkdir -p $HOME/.gem
-        touch $HOME/.gem/credentials
-        chmod 0600 $HOME/.gem/credentials
-        printf -- "---\n:github: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
-        gem build *.gemspec
-        gem push --KEY github --host https://rubygems.pkg.github.com/${OWNER} *.gem
-      env:
-        GEM_HOST_API_KEY: "Bearer ${{secrets.GITHUB_TOKEN}}"
-        OWNER: ${{ github.repository_owner }}
+      - name: Publish to GPR
+        run: |
+          mkdir -p $HOME/.gem
+          touch $HOME/.gem/credentials
+          chmod 0600 $HOME/.gem/credentials
+          printf -- "---\n:github: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
+          gem build *.gemspec
+          gem push --KEY github --host https://rubygems.pkg.github.com/${OWNER} *.gem
+        env:
+          GEM_HOST_API_KEY: "Bearer ${{secrets.GITHUB_TOKEN}}"
+          OWNER: ${{ github.repository_owner }}
 
     # Disabled as this does not handle 2FA
     # - name: Publish to RubyGems

CHANGELOG.md

@@ -23,6 +23,155 @@ Docs changes made since the latest release:
 
 - N/A
 
+## Release v0.10.1
+
+Hi folks! This patch fixes two bugs related to generated navigation elements and improves our docs.
+
+This release should be a straightforward upgrade for all users of Just the Docs. Thank you for your continued support!
+
+### Bugfixes
+
+- Fixed: `back_to_top` not displaying when no other footer variables are set by [@mattxwang] in [#1461]
+- Fixed: auto-generated child navigation (TOC) by [@pdmosses] in [#1590]
+
+### Documentation
+
+- Fixed: incorrect docs for example with minimal layout parent, default layout child by [@janbrasna] in [#1540]
+- Fixed: unclear docs on using in-page table of contents by [@sebjameswml] in [#1551]
+
+### New Contributors
+
+- [@janbrasna] made their first contribution in [#1540]
+- [@sebjameswml] made their first contribution in [#1551]
+
+[@janbrasna]: https://github.com/janbrasna
+[@sebjameswml]: https://github.com/sebjameswml
+
+[#1461]: https://github.com/just-the-docs/just-the-docs/pull/1461
+[#1540]: https://github.com/just-the-docs/just-the-docs/pull/1540
+[#1551]: https://github.com/just-the-docs/just-the-docs/pull/1551
+[#1590]: https://github.com/just-the-docs/just-the-docs/pull/1590
+
+## Release v0.10.0
+
+Hi folks! This minor release adds one of our most-requested features: unlimited multi-level navigation (also known as recursive navigation). Huge thanks to [@pdmosses] for his wonderful work in implementing this feature!
+
+This release should be a straightforward upgrade for all users of Just the Docs. Thank you for your continued support!
+
+### Using Release `v0.10.0`
+
+Users who have not pinned the theme version will be **automatically upgraded to `v0.9.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.10.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.10.0"
+```
+
+To use and pin a previous version of the theme, replace the `0.10.0` with the desired release tag.
+
+### New Features
+
+- Added: Allow unlimited multi-level navigation by [@pdmosses] in [#1431]
+
+### Documentation
+
+- Added: Allow unlimited multi-level navigation by [@pdmosses] in [#1440]
+- Added: sitemap (via `jekyll-sitemap` plugin) by [@mattxwang] in [#1530]
+- Fixed: (non-systemic) accessibility issues flagged by aXe by [@mattxwang] in [#1531]
+
+[#1431]: https://github.com/just-the-docs/just-the-docs/pull/1431
+[#1440]: https://github.com/just-the-docs/just-the-docs/pull/1440
+[#1530]: https://github.com/just-the-docs/just-the-docs/pull/1530
+[#1530]: https://github.com/just-the-docs/just-the-docs/pull/1531
+
+## Release v0.9.0
+
+Hi folks! This minor release adds a `nav_enabled` set of variables to enable/disable the navigation at a site, layout, and page level --- and uses that to add search and auxilary links to the `minimal` layout. In addition, it fixes `search-data.json` corruption with default layouts and some minor CSS/SCSS issues.
+
+This release should be a straightforward upgrade for all users of Just the Docs. Thank you for your continued support!
+
+### Using Release `v0.9.0`
+
+Users who have not pinned the theme version will be **automatically upgraded to `v0.9.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.9.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.9.0"
+```
+
+To use and pin a previous version of the theme, replace the `0.9.0` with the desired release tag.
+
+### New Features
+
+- Added: `nav_enabled` site, layout, and page-level variable to selectively show or hide the side/mobile menu by [@kevinlin1] in [#1441]
+- Added: site-wide search bar and auxiliary links to the `minimal` layout by [@kevinlin1] in [#1441]
+
+### Bugfixes
+
+- Fixed: protect `search-data.json` file from front matter default for layout by [@mattxwang] in [#1468]
+- Fixed: Sass mixed declarations by [@bobvandevijver] in [#1495]
+- Fixed: redundant `monospace` in `pre`, `code`, `kbd`, `samp` reset by [@mattxwang] in [#1508]
+
+### Documentation
+
+- Docs: Explained the `nav_enabled` variables as an alternative to using the minimal layout [@kevinlin1] in [#1441].
+
+### New Contributors
+
+- [@bobvandevijver] made their first contribution in [#1495]
+
+[@bobvandevijver]: https://github.com/bobvandevijver
+
+[#1441]: https://github.com/just-the-docs/just-the-docs/pull/1441
+[#1468]: https://github.com/just-the-docs/just-the-docs/pull/1468
+[#1495]: https://github.com/just-the-docs/just-the-docs/pull/1495
+[#1508]: https://github.com/just-the-docs/just-the-docs/pull/1508
+
+## Release v0.8.2
+
+Hi everyone! This patch release fixes a bug where a default layout with unrestricted `scope` (`path: ""`) breaks JavaScript functionality. Users who do not use a default layout with unrestricted `scope` should not be affected. This should be a straightforward upgrade for all users. Thank you to [@pdmosses] for triaging and fixing the bug!
+
+### Bugfixes
+
+- Fixed: Protect theme JS file from front matter default for layout by [@pdmosses] in [#1447]
+
+[#1447]: https://github.com/just-the-docs/just-the-docs/pull/1447
+
+## 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.
@@ -520,7 +669,7 @@ We're so excited to release Just the Docs `v0.4.0`. This release has been almost
 - [callouts](https://just-the-docs.com/docs/ui-components/callouts/), a new design component to highlight content
 - [configuring mermaid.js](https://just-the-docs.com/docs/ui-components/code/#mermaid-diagram-code-blocks), a markdown-native diagram visualization library
 - [copy code button](https://just-the-docs.com/docs/ui-components/code/#copy-button) for code snippets
-- [external navigation links](https://just-the-docs.com/docs/navigation-structure/#external-navigation-links)
+- external navigation links
 - major improvements to nav generation efficiency and robustness
 - minor improvements to built-in accessibility (SVG icons, nav titles, skip to main content)
 - [modularized site components](https://just-the-docs.com/docs/customization/#custom-layouts-and-includes) (advanced feature)

Dockerfile

@@ -1,12 +0,0 @@
-FROM ruby:2.7
-
-ENV LC_ALL C.UTF-8
-ENV LANG en_US.UTF-8
-ENV LANGUAGE en_US.UTF-8
-
-WORKDIR /usr/src/app
-
-COPY Gemfile just-the-docs.gemspec ./
-RUN gem install bundler && bundle install
-
-EXPOSE 4000

Gemfile

@@ -1,8 +1,12 @@
 source "https://rubygems.org"
 gemspec
 
+gem "base64"
+gem "csv"
+
 gem "jekyll-github-metadata", ">= 2.15"
 
 gem "jekyll-include-cache", group: :jekyll_plugins
+gem "jekyll-sitemap", group: :jekyll_plugins
 
 gem "html-proofer", "~> 5.0", :group => :development

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    just-the-docs (0.8.0)
+    just-the-docs (0.10.1)
       jekyll (>= 3.8.5)
       jekyll-include-cache
       jekyll-seo-tag (>= 2.0)
@@ -10,40 +10,50 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    Ascii85 (1.1.0)
-    addressable (2.8.6)
-      public_suffix (>= 2.0.2, < 6.0)
+    Ascii85 (2.0.1)
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
     afm (0.2.2)
-    async (2.6.3)
-      console (~> 1.10)
+    async (2.23.0)
+      console (~> 1.29)
       fiber-annotation
-      io-event (~> 1.1)
-      timers (~> 4.1)
+      io-event (~> 1.9)
+      metrics (~> 0.12)
+      traces (~> 0.15)
     base64 (0.2.0)
+    bigdecimal (3.1.9)
     colorator (1.1.0)
-    concurrent-ruby (1.2.2)
-    console (1.23.2)
+    concurrent-ruby (1.3.5)
+    console (1.29.3)
       fiber-annotation
-      fiber-local
+      fiber-local (~> 1.1)
+      json
+    csv (3.3.3)
     em-websocket (0.5.3)
       eventmachine (>= 0.12.9)
       http_parser.rb (~> 0)
     ethon (0.16.0)
       ffi (>= 1.15.0)
     eventmachine (1.2.7)
-    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.16.3)
+    faraday (2.9.0)
+      faraday-net_http (>= 2.0, < 3.2)
+    faraday-net_http (3.1.0)
+      net-http
+    ffi (1.17.1-arm64-darwin)
+    ffi (1.17.1-x86_64-linux-gnu)
     fiber-annotation (0.2.0)
-    fiber-local (1.0.0)
+    fiber-local (1.1.0)
+      fiber-storage
+    fiber-storage (1.0.0)
     forwardable-extended (2.6.0)
-    google-protobuf (3.25.1-arm64-darwin)
-    google-protobuf (3.25.1-x86_64-linux)
+    google-protobuf (4.29.3-arm64-darwin)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.29.3-x86_64-linux)
+      bigdecimal
+      rake (>= 13)
     hashery (2.1.2)
-    html-proofer (5.0.8)
+    html-proofer (5.0.10)
       addressable (~> 2.3)
       async (~> 2.1)
       nokogiri (~> 1.13)
@@ -53,20 +63,23 @@ GEM
       yell (~> 2.0)
       zeitwerk (~> 2.5)
     http_parser.rb (0.8.0)
-    i18n (1.14.1)
+    i18n (1.14.7)
       concurrent-ruby (~> 1.0)
-    io-event (1.2.3)
-    jekyll (4.3.3)
+    io-event (1.9.0)
+    jekyll (4.4.1)
       addressable (~> 2.4)
+      base64 (~> 0.2)
       colorator (~> 1.0)
+      csv (~> 3.0)
       em-websocket (~> 0.5)
       i18n (~> 1.0)
       jekyll-sass-converter (>= 2.0, < 4.0)
       jekyll-watch (~> 2.0)
+      json (~> 2.6)
       kramdown (~> 2.3, >= 2.3.1)
       kramdown-parser-gfm (~> 1.0)
       liquid (~> 4.0)
-      mercenary (>= 0.3.6, < 0.5)
+      mercenary (~> 0.3, >= 0.3.6)
       pathutil (~> 0.9)
       rouge (>= 3.0, < 5.0)
       safe_yaml (~> 1.0)
@@ -81,72 +94,82 @@ GEM
       sass-embedded (~> 1.54)
     jekyll-seo-tag (2.8.0)
       jekyll (>= 3.8, < 5.0)
+    jekyll-sitemap (1.4.0)
+      jekyll (>= 3.7, < 5.0)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
-    kramdown (2.4.0)
-      rexml
+    json (2.10.2)
+    kramdown (2.5.1)
+      rexml (>= 3.3.9)
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
     liquid (4.0.4)
-    listen (3.8.0)
+    listen (3.9.0)
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     mercenary (0.4.0)
-    nokogiri (1.16.2-arm64-darwin)
+    metrics (0.12.1)
+    net-http (0.4.1)
+      uri
+    nokogiri (1.18.4-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.16.2-x86_64-linux)
+    nokogiri (1.18.4-x86_64-linux-gnu)
       racc (~> 1.4)
     octokit (6.1.1)
       faraday (>= 1, < 3)
       sawyer (~> 0.9)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
-    pdf-reader (2.11.0)
-      Ascii85 (~> 1.0)
+    pdf-reader (2.14.1)
+      Ascii85 (>= 1.0, < 3.0, != 2.0.0)
       afm (~> 0.2.1)
       hashery (~> 2.0)
       ruby-rc4
       ttfunk
-    public_suffix (5.0.4)
-    racc (1.7.3)
+    public_suffix (6.0.1)
+    racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.1.0)
+    rake (13.2.1)
     rb-fsevent (0.11.2)
-    rb-inotify (0.10.1)
+    rb-inotify (0.11.1)
       ffi (~> 1.0)
-    rexml (3.2.6)
-    rouge (4.2.0)
+    rexml (3.4.0)
+    rouge (4.5.1)
     ruby-rc4 (0.1.5)
-    ruby2_keywords (0.0.5)
     safe_yaml (1.0.5)
-    sass-embedded (1.69.6-arm64-darwin)
-      google-protobuf (~> 3.25)
-    sass-embedded (1.69.6-x86_64-linux-gnu)
-      google-protobuf (~> 3.25)
+    sass-embedded (1.83.4-arm64-darwin)
+      google-protobuf (~> 4.29)
+    sass-embedded (1.83.4-x86_64-linux-gnu)
+      google-protobuf (~> 4.29)
     sawyer (0.9.2)
       addressable (>= 2.3.5)
       faraday (>= 0.17.3, < 3)
     terminal-table (3.0.2)
       unicode-display_width (>= 1.1.1, < 3)
-    timers (4.3.5)
-    ttfunk (1.7.0)
-    typhoeus (1.4.0)
+    traces (0.15.2)
+    ttfunk (1.8.0)
+      bigdecimal (~> 3.1)
+    typhoeus (1.4.1)
       ethon (>= 0.9.0)
-    unicode-display_width (2.5.0)
-    webrick (1.8.1)
+    unicode-display_width (2.6.0)
+    uri (0.13.2)
+    webrick (1.9.1)
     yell (2.2.2)
-    zeitwerk (2.6.11)
+    zeitwerk (2.7.2)
 
 PLATFORMS
   arm64-darwin
-  x86_64-linux
+  x86_64-linux-gnu
 
 DEPENDENCIES
+  base64
   bundler (>= 2.3.5)
+  csv
   html-proofer (~> 5.0)
   jekyll-github-metadata (>= 2.15)
   jekyll-include-cache
+  jekyll-sitemap
   just-the-docs!
 
 BUNDLED WITH
-   2.4.13
+   2.5.9

MIGRATION.md

@@ -41,7 +41,19 @@ This document contains instructions on how to migrate and upgrade Just the Docs
 > and pull the changes of a new release to your clone,
 > you may need to resolve merge conflicts.
 
-[CHANGELOG]: {{ site.baseurl }}{% link CHANGELOG.md %}
+[CHANGELOG]: {% link CHANGELOG.md %}
+
+## v0.9.x - v0.10.0
+
+There are no potentially-breaking changes in v0.10.0.
+
+## v0.8.x - v0.9.0
+
+There are no potentially-breaking changes in v0.9.0.
+
+## v0.7.x - v0.8.0
+
+There are no potentially-breaking changes in v0.8.0.
 
 ## v0.6.x - v0.7.0
 
@@ -373,7 +385,7 @@ For changes since v0.3.3, the log usually references the merged PR that made the
 
 #### Configuration
 
-- Mermaid support: first-class support for [Mermaid](https://mermaid.js.org/) - a JavaScript-based diagram and charting tool supported by GitHub - has been added to the theme. **This feature is opt-in.** See the new doc subsections in [Configuration]({% link docs/configuration.md %}#mermaid-diagrams) and [Code]({% link docs/ui-components/code.md %}#mermaid-diagram-code-blocks) for more.
+- Mermaid support: first-class support for [Mermaid](https://mermaid.js.org/) - a JavaScript-based diagram and charting tool supported by GitHub - has been added to the theme. **This feature is opt-in.** See the new doc subsections in [Configuration]({% link docs/configuration.md %}#mermaid-diagrams) and [Code]({% link docs/ui-components/code/index.md %}#mermaid-diagram-code-blocks) for more.
 - Multiple Google Analytics tags are now supported. PR: [#1029]
 
 #### Customization

README.md

@@ -32,7 +32,7 @@ More specifically, the created site:
 
 Other than that, you're free to customize sites that you create with the template, however you like. You can easily change the versions of `just-the-docs` and Jekyll it uses, as well as adding further plugins.
 
-### Use RubyGems
+### Use as a Ruby Gem
 
 Alternatively, you can install the theme as a Ruby Gem, without creating a new site.
 
@@ -48,17 +48,11 @@ And add this line to your Jekyll site's `_config.yml`:
 theme: just-the-docs
 ```
 
-And then execute:
+And then install all relevant dependencies:
 
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install just-the-docs
-
-Alternatively, you can run it inside Docker while developing your site
-
-    $ docker-compose up
+```shell
+$ bundle
+```
 
 ## Usage
 

_config.yml

@@ -21,33 +21,40 @@ repository: just-the-docs/just-the-docs # for github-metadata
 
 permalink: pretty
 
+defaults:
+  - scope:
+      path: "docs" # an empty string here means all files in the project
+      type: "pages"
+    values:
+      layout: "default"
+
 exclude:
- # from https://github.com/jekyll/jekyll/blob/master/lib/site_template/_config.yml:
-   - .sass-cache/
-   - .jekyll-cache/
-   - gemfiles/
-   - Gemfile
-   - Gemfile.lock
-   - node_modules/
-   - vendor/bundle/
-   - vendor/cache/
-   - vendor/gems/
-   - vendor/ruby/
- # specific to the theme website:
-   - bin/
-   - lib/
-   - "*.gemspec"
-   - "*.gem"
-   - LICENSE.txt
-   - package.json
-   - package-lock.json
-   - Rakefile
-   - README.md
-   - CODE_OF_CONDUCT.md
-   - docker-compose.yml
-   - Dockerfile
- # theme test code
-   - fixtures/
+  # from https://github.com/jekyll/jekyll/blob/master/lib/site_template/_config.yml:
+  - .sass-cache/
+  - .jekyll-cache/
+  - gemfiles/
+  - Gemfile
+  - Gemfile.lock
+  - node_modules/
+  - vendor/bundle/
+  - vendor/cache/
+  - vendor/gems/
+  - vendor/ruby/
+  # specific to the theme website:
+  - bin/
+  - lib/
+  - "*.gemspec"
+  - "*.gem"
+  - LICENSE.txt
+  - package.json
+  - package-lock.json
+  - Rakefile
+  - README.md
+  - CODE_OF_CONDUCT.md
+  - docker-compose.yml
+  - Dockerfile
+  # theme test code
+  - fixtures/
 
 # Set a path/url to a logo that will be displayed instead of the title
 #logo: "/assets/images/just-the-docs.png"
@@ -79,7 +86,7 @@ search:
   # 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'
+  focus_shortcut_key: "k"
 
 # For copy button on code
 enable_copy_code_button: true
@@ -109,6 +116,10 @@ aux_links:
 # Makes Aux links open in a new tab. Default is false
 aux_links_new_tab: false
 
+# Enable or disable the side/mobile menu globally
+# Nav menu can also be selectively enabled or disabled using page variables or the minimal layout
+nav_enabled: true
+
 # Sort order for navigation links
 # nav_sort: case_insensitive # default, equivalent to nil
 nav_sort: case_sensitive # Capital letters sorted before lowercase
@@ -118,6 +129,13 @@ nav_external_links:
   - title: Just the Docs on GitHub
     url: https://github.com/just-the-docs/just-the-docs
 
+# Show navigation error report
+nav_error_report: true # default is false/nil.
+
+liquid:
+  error_mode: strict
+  strict_filters: true
+
 # Footer content
 # appears at the bottom of every page's main content
 
@@ -125,14 +143,12 @@ nav_external_links:
 back_to_top: true
 back_to_top_text: "Back to top"
 
-footer_content: "Copyright &copy; 2017-2020 Patrick Marsceill. Distributed by an <a href=\"https://github.com/just-the-docs/just-the-docs/tree/main/LICENSE.txt\">MIT license.</a> <a href=\"https://www.netlify.com/\">This site is powered by Netlify.</a>"
+footer_content: 'Copyright &copy; 2017-2020 Patrick Marsceill. Distributed by an <a href="https://github.com/just-the-docs/just-the-docs/tree/main/LICENSE.txt">MIT license.</a> <a href="https://www.netlify.com/">This site is powered by Netlify.</a>'
 
 # Footer last edited timestamp
 last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter
 last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html
 
-
-
 # Footer "Edit this page on GitHub" link text
 gh_edit_link: true # show or hide edit this page link
 gh_edit_link_text: "Edit this page on GitHub"
@@ -171,6 +187,7 @@ plugins:
   - jekyll-seo-tag
   - jekyll-github-metadata
   - jekyll-include-cache
+  - jekyll-sitemap
 
 kramdown:
   syntax_highlighter_opts:

_includes/components/breadcrumbs.html

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

_includes/components/children_nav.html

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

_includes/components/footer.html

@@ -1,7 +1,7 @@
 {% capture footer_custom %}
   {%- include footer_custom.html -%}
 {% endcapture %}
-{% if footer_custom != "" or site.last_edit_timestamp or site.gh_edit_link %}
+{% if footer_custom != "" or site.last_edit_timestamp or site.gh_edit_link or site.back_to_top %}
   <hr>
   <footer>
     {% if site.back_to_top %}

_includes/components/nav.html

@@ -1,75 +0,0 @@
-{%- comment -%}
-  Include as: {%- include components/nav.html pages=pages -%}
-  Depends on: include.pages.
-  Results in: HTML for the navigation panel.
-  Includes:
-    sorted_pages.html
-  Overwrites:
-    nav_pages, first_level_pages, second_level_pages, third_level_pages,
-    node, children_list, child, grand_children_list, grand_child.
-{%- endcomment -%}
-
-{%- assign nav_pages = include.pages
-    | where_exp: "item", "item.title != nil"
-    | where_exp: "item", "item.nav_exclude != true" -%}
-
-{%- include sorted_pages.html pages = nav_pages -%}
-
-{%- comment -%}
-  It might be more efficient to sort the pages at each level separately.
-{%- endcomment -%}
-
-{%- assign first_level_pages = sorted_pages
-    | where_exp: "item", "item.parent == nil" -%}
-{%- assign second_level_pages = sorted_pages
-    | where_exp: "item", "item.parent != nil"
-    | where_exp: "item", "item.grand_parent == nil" -%}
-{%- assign third_level_pages = sorted_pages
-    | where_exp: "item", "item.grand_parent != nil" -%}
-
-<ul class="nav-list">
-{%- for node in first_level_pages -%}
-  <li class="nav-list-item">
-    {%- if node.has_children -%}
-    <button class="nav-list-expander btn-reset" aria-label="toggle items in {{ node.title }} category" aria-pressed="false">
-      <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg>
-    </button>
-    {%- endif -%}
-    <a href="{{ node.url | relative_url }}" class="nav-list-link">{{ node.title }}</a>
-    {%- if node.has_children -%}
-      {%- assign children_list = second_level_pages
-            | where: "parent", node.title -%}
-      {%- if node.child_nav_order == 'desc' or node.child_nav_order == 'reversed' -%}
-        {%- assign children_list = children_list | reverse -%}
-      {%- endif -%}
-      <ul class="nav-list">
-      {%- for child in children_list -%}
-        <li class="nav-list-item">
-          {%- if child.has_children -%}
-          <button class="nav-list-expander btn-reset" aria-label="toggle items in {{ child.title }} category" aria-pressed="false">
-            <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg>
-          </button>
-          {%- endif -%}
-          <a href="{{ child.url | relative_url }}" class="nav-list-link">{{ child.title }}</a>
-          {%- if child.has_children -%}
-            {%- assign grand_children_list = third_level_pages
-                  | where: "parent", child.title
-                  | where: "grand_parent", node.title -%}
-            {%- if child.child_nav_order == 'desc' or child.child_nav_order == 'reversed' -%}
-              {%- assign grand_children_list = grand_children_list | reverse -%}
-            {%- endif -%}
-            <ul class="nav-list">
-            {%- for grand_child in grand_children_list -%}
-              <li class="nav-list-item">
-                <a href="{{ grand_child.url | relative_url }}" class="nav-list-link">{{ grand_child.title }}</a>
-              </li>
-            {%- endfor -%}
-            </ul>
-          {%- endif -%}
-        </li>
-      {%- endfor -%}
-      </ul>
-    {%- endif -%}
-  </li>
-{%- endfor -%}
-</ul>

_includes/components/nav/children.html

@@ -0,0 +1,48 @@
+{%- comment -%}
+  Include as: {%- include components/nav/children.html node=node ancestors=title_array all=bool -%}
+  Depends on: include.node, include.ancestors, include.all, nav_parenthood, nav_top_node_titles.
+  Includes: components/nav/sorted.html.
+  Assigns to: nav_children.
+  Overwrites:
+    nav_candidates, nav_child, nav_child_ok.
+{%- endcomment -%}
+
+{%- assign nav_children = "" | split: "" -%}
+
+{%- if include.all == true or include.node.has_children != false -%}
+
+  {%- assign nav_candidates = nav_parenthood
+        | where: "name", include.node.title | map: "items" | first -%}
+
+  {%- for nav_child in nav_candidates -%}
+    {%- assign nav_child_ok = true -%}
+
+    {%- if nav_child.grand_parent and nav_child.grand_parent != include.node.parent -%}
+      {%- assign nav_child_ok = false -%}
+    {%- endif -%}
+
+    {%- if nav_child.ancestor and nav_child.ancestor != include.node.title -%}
+      {%- unless include.ancestors contains nav_child.ancestor -%}
+        {%- assign nav_child_ok = false -%}
+      {%- endunless -%}
+    {%- endif -%}
+
+    {%- comment -%}
+      The following check rejects nav_child as 3rd-level when include.node is 2nd-level
+      and nav_child can also be 2nd-level. This is for backwards compatibility with
+      existing 3-level sites.
+    {%- endcomment -%}
+    {%- if nav_child.grand_parent == nil and nav_child.ancestor == nil and 
+          nav_top_node_titles contains nav_child.parent and include.ancestors.size >= 1 -%}
+      {%- assign nav_child_ok = false -%}
+    {%- endif -%}
+
+    {%- if nav_child_ok -%}
+      {%- assign nav_children = nav_children | push: nav_child -%}
+    {%- endif -%}
+  {%- endfor -%}
+
+{%- endif -%}
+
+{%- include components/nav/sorted.html pages=nav_children -%}
+{%- assign nav_children = nav_sorted -%}

_includes/components/nav/links.html

@@ -0,0 +1,53 @@
+{%- comment -%}
+  Include as: {%- include components/nav/links.html pages=page_array ancestors=title_array all=bool -%}
+  Depends on: include.pages, include.ancestors, include.all.
+  Results in: HTML for the main navigation when all is nil or false;
+    includes links to pages excluded from the main navigation when all is true.
+  Includes: components/nav/sorted.html, components/nav/children.html, components/nav/links.html.
+  Overwrites:
+    node, nav_children, nav_ancestors.
+{%- endcomment -%}
+
+<ul class="nav-list">
+  {%- for node in include.pages -%}
+  {%- if include.all == true or node.nav_exclude != true -%}
+
+  {%- if include.ancestors contains node.title -%}
+  
+    <li class="nav-list-item">
+      <a href="{{ node.url | relative_url }}" class="nav-list-link"> ∞ </a>
+    </li>
+    {%- capture nav_error_report -%}
+      <blockquote class="warning">
+        A page has the same title as its parent page or one of its ancestral pages!<br>
+        This causes an incorrect link in the main navigation panel.<br>
+        Page title: <code>{{ node.title }}</code>, location: <code>{{ node.path }}</code>.
+      </blockquote>
+    {%- endcapture -%}
+
+  {%- else -%}
+  
+    {%- include components/nav/children.html node=node ancestors=include.ancestors all=include.all -%}
+
+    <li class="nav-list-item">
+      {%- if nav_children.size >= 1 -%}
+      <button class="nav-list-expander btn-reset" aria-label="toggle items in {{ node.title }} category" aria-pressed="false">
+        <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg>
+      </button>
+      {%- endif -%}
+      <a href="{{ node.url | relative_url }}" class="nav-list-link">{{ node.title }}</a>
+      {%- if nav_children.size >= 1 -%}
+        {%- if node.child_nav_order == 'desc' or node.child_nav_order == 'reversed' -%}
+          {%- assign nav_children = nav_children | reverse -%}
+        {%- endif -%}
+        {%- assign nav_ancestors = include.ancestors | push: node.title -%}
+        {%- include components/nav/links.html pages=nav_children ancestors=nav_ancestors all=include.all -%}
+      {%- endif -%}
+    </li>
+  
+  {%- endif -%}
+  
+  {%- endif -%}
+  {%- endfor -%}
+</ul>
+{%- comment -%}{%- endcomment -%}

_includes/components/nav/pages.html

@@ -0,0 +1,23 @@
+{%- comment -%}
+  Include as: {%- include components/nav/pages.html pages=page_array all=bool -%}
+  Depends on: include.pages.
+  Results in: HTML for the main navigation when all is nil or false;
+    adds links to pages excluded from the main navigation when all is true.
+  Includes: components/nav/links.html
+  Assigns to:
+    nav_parenthood, nav_top_nodes, nav_top_node_titles, nav_ancestors.
+{%- endcomment -%}
+
+{%- assign nav_parenthood = include.pages
+      | where_exp: "item", "item.title != nil" | group_by: "parent" -%}
+
+{%- assign nav_top_nodes = nav_parenthood
+      | where_exp: "item", "item.name == ''" | map: "items" | first -%}
+
+{%- include components/nav/sorted.html pages=nav_top_nodes -%}
+
+{% assign nav_top_node_titles = nav_top_nodes | map: "title" -%}
+
+{%- assign nav_ancestors = "" | split: "" -%}
+
+{%- include components/nav/links.html pages=nav_sorted ancestors=nav_ancestors all=include.all -%}

_includes/components/nav/sorted.html

@@ -1,7 +1,7 @@
 {%- comment -%}
-  Include as: {%- include sorted_pages.html pages=array_of_pages -%}
+  Include as: {%- include components/nav/sorted.html pages=page_array -%}
   Depends on: include.pages.
-  Assigns to: sorted_pages.
+  Assigns to: nav_sorted.
   Overwrites: 
     nav_order_pages, title_order_pages, double_quote, empty_array,
     nav_number_pages, nav_string_pages, nav_order_groups, group,
@@ -103,7 +103,7 @@
   {%- endif -%}
 {%- endunless -%}
 
-{%- assign sorted_pages = nav_number_pages
+{%- assign nav_sorted = nav_number_pages
       | concat: nav_string_pages
       | concat: title_number_pages
       | concat: title_string_pages -%}

_includes/components/site_nav.html

@@ -1,9 +1,10 @@
 {%- comment -%}
-  Include as: {%- include_cached components/site_nav.html -%}
+  Include as: {%- include_cached components/site_nav.html all=bool -%}
   Depends on: site.
-  Results in: HTML for the site-nav.
+  Results in: cached HTML for the main navigation when `all` is nil or false;
+    includes links to pages excluded from the main navigation when `all` is true.
   Includes:
-    components/nav.html
+    components/nav/pages.html
   Overwrites:
     pages_top_size, collections_size, collection_entry,
     collection_key, collection_value, collection.
@@ -16,7 +17,7 @@
         | where_exp:"item", "item.nav_exclude != true"
         | size %}
   {% if pages_top_size > 0 %}
-    {% include components/nav.html pages=site.html_pages %}
+    {% include components/nav/pages.html pages=site.html_pages all=include.all %}
   {% endif %}
   {%- if site.nav_external_links -%}
     <ul class="nav-list">
@@ -51,17 +52,21 @@
                 </button>
                 {%- endif -%}
                 <div class="nav-category">{{ collection_value.name }}</div>
-                {% include components/nav.html pages=collection %}
+                {% include components/nav/pages.html pages=collection all=include.all %}
               </li>
             </ul>
           {% else %}
             <div class="nav-category">{{ collection_value.name }}</div>
-            {% include components/nav.html pages=collection %}
+            {% include components/nav/pages.html pages=collection all=include.all %}
           {% endif %}
         {% else %}
-          {% include components/nav.html pages=collection %}
+          {% include components/nav/pages.html pages=collection all=include.all %}
         {% endif %}
       {% endif %}
     {% endfor %}
   {% endif %}
 </nav>
+
+{% if site.nav_error_report %}
+{{ nav_error_report }}
+{%- endif %}

_includes/css/activation.scss.liquid

@@ -20,313 +20,306 @@
   - The other two rules ensure that all folding collections are expanded.
 {%- endcomment -%}
 
-{%- capture activation_no_nav_link %}
-.site-nav ul li a {
-  background-image: none;
-}
+{%- capture site_nav -%}
+{%- include_cached components/site_nav.html -%}
+{%- endcapture -%}
 
-{%- if site.just_the_docs.collections %}
-.site-nav > ul.nav-category-list > li > button svg {
-  transform: rotate(-90deg);
-}
-.site-nav > ul.nav-category-list > li.nav-list-item > ul.nav-list {
-  display: block;
-}
-{%- endif %}
+{%- capture activation_no_nav_link %}
+    .site-nav ul li a {
+      background-image: none;
+    }
+
+    {%- if site.just_the_docs.collections %}
+    .site-nav > ul.nav-category-list > li > button svg {
+      transform: rotate(-90deg);
+    }
+    .site-nav > ul.nav-category-list > li.nav-list-item > ul.nav-list {
+      display: block;
+    }
+    {%- endif %}
 {% endcapture -%}
 
 {%- capture nav_list_link -%}
 <a href="{{ page.url | relative_url }}" class="nav-list-link">
 {%- endcapture -%}
 
-{%- capture site_nav -%}
-{%- include_cached components/site_nav.html -%}
-{%- endcapture -%}
-
 {%- if site_nav contains nav_list_link -%}
 
-{%- capture nav_list -%}
-<ul class="nav-list
-{%- endcapture -%}
+  {%- capture nav_list -%}
+  <ul class="nav-list
+  {%- endcapture -%}
 
-{%- assign nav_list_end = "</ul>" -%}
+  {%- assign nav_list_end = "</ul>" -%}
 
-{%- capture nav_list_item -%}
-<li class="nav-list-item
-{%- endcapture -%}
+  {%- capture nav_list_item -%}
+  <li class="nav-list-item
+  {%- endcapture -%}
 
-{%- capture nav_category_list -%}
-<ul class="nav-list nav-category-list">
-{%- 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_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_splits =
+        nav_list_link_prefix | split: nav_list_item | pop -%}
 
-{%- assign nav_levels = "" | split: "" | push: 1 -%}
+  {%- 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.
+  {%- 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:
     
-  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;
+      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
     
-  - 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);
+    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.
     
-  - 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 %}
+    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 -%}
+  {%- 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_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 -%}
+    {%- 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 -%}
+    {%- 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 -%}
+      {%- 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 -%}
+    {%- 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 -%}
+      {%- 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 -%}
+    {%- 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 -%}
 
-    {%- 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 -%}
+  {%- endfor -%}
 
-    {%- 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 nav_levels = nav_levels | where_exp: "item", "item >= 1" -%}
 
-  {%- endif -%}
+  {%- comment -%}
+    The generated CSS depends on the position of the current page in each level in
+    the navigation.
 
-{%- endfor -%}
+    nav_page_level is the depth of the navigation hierarchy (ignoring collections).
+    In existing 3-level sites, nav_page_level <= 3.
+    In multi-level sites, nav_page_level is unbounded.
+  {%- endcomment -%}
 
-{%- assign nav_levels = nav_levels | where_exp: "item", "item >= 1" -%}
+  {%- assign nav_page_level = nav_levels.size | minus: 1 -%}
+  {%- assign nav_page_parent_level = nav_page_level | minus: 1 -%}
+  {%- assign nav_page_grandparent_level = nav_page_level | minus: 2 -%}
 
-{%- endif -%}
-
-{%- comment -%}
-  The generated CSS depends on the position of the current page in each level in
-  the navigation.
-{%- endcomment -%}
-
-{%- if nav_levels[1] == nil -%}
-
-{{ activation_no_nav_link }}
-
-{%- else -%}
-
-{%- if nav_levels[2] == nil and nav_levels[3] -%}
-
-{{ activation_no_nav_link }}
-
-{%- else -%}
-
-{%- comment -%}
-  The site-nav is:
-  - an optional ul.nav-list with li.nav-list-items for non-collection top-level pages
-  - an optional ul.nav-list with li.nav-list-item.externals
-  - any number of just-the-docs.collections
-  
-  A non-foldable collection is:
-  - a div.nav-category with the collection name, followed by:
-  - a ul.nav-list with li.nav-list-items for its top-level pages
-  
-  A foldable collection is:
-  - a ul.nav-list.nav-category-list with a single li.nav-list-item containing:
-    - an optional button with the expander svg
-    - a div.nav-category with the collection name
+  {%- 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
-  
-  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 -%}
+    
+    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 -%}
+  {%- if page.collection == nil -%}
 
-  {%- capture activation_collection_prefix -%}
-  .site-nav > ul.nav-list:first-child
-  {%- endcapture -%}
+    {%- capture activation_collection_prefix -%}
+    .site-nav > ul.nav-list:first-child
+    {%- endcapture -%}
 
-  {%- capture activation_other_collection_prefix -%}
-  .site-nav > ul.nav-list:not(:first-child)
-  {%- endcapture -%}
+    {%- capture activation_other_collection_prefix -%}
+    .site-nav > ul.nav-list:not(:first-child)
+    {%- endcapture -%}
 
-{%- else -%}
+  {%- else -%}
+
+    {%- capture activation_collection_prefix -%}
+    .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 -%}
 
-  {%- capture activation_collection_prefix -%}
-  .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 -%}
+  {%- comment -%}
+    The required background image of the link to the current page may involve SCSS.
+    To avoid page-dependent SCSS, all nav links initially have that background image.
+    The following rule removes the image from the links to all parents, siblings,
+    and children of the current page.
+  {%- endcomment %}
 
-{%- endif -%}
+    {% if nav_page_level >= 2 -%}
+    {%- for i in (1..nav_page_parent_level) -%}
+    {{ activation_collection_prefix }} >
+    {%- for j in (2..i) %} li > ul >
+    {%- endfor %} li > a,
+    {% endfor -%}
+    {%- endif %}
+    {{ activation_collection_prefix }} >
+    {%- for i in (1..nav_page_parent_level) %} li > ul >
+    {%- endfor %} li:not(:nth-child({{ nav_levels[nav_page_level] }})) > a,
+    {{ activation_collection_prefix }} >
+    {%- for i in (1..nav_page_level) %} li > ul >
+    {%- endfor %} li a {
+      background-image: none;
+    }
 
-{%- comment -%}
-  The required background image of the link to the current page may involve SCSS.
-  To avoid page-dependent SCSS, all nav links initially have that background image.
-  The following rule removes the image from the links to all parents, siblings,
-  and children of the current page.
-{%- endcomment %}
+  {%- comment -%}
+    The following rule removes the image from the links to pages in other collections.
+  {%- endcomment %}
 
-{% if nav_levels[3] -%}
+    {{ activation_other_collection_prefix }} a,
+    .site-nav li.external a {
+      background-image: none;
+    }
 
-{{ activation_collection_prefix }} > li > a,
-{{ activation_collection_prefix }} > li > ul > li > a,
-{{ activation_collection_prefix }} > li > ul > li > ul > li:not(:nth-child({{ nav_levels[3] }})) > a {
-  background-image: none;
-}
+  {%- comment -%}
+    The following rule styles the link to the current page.
+  {%- endcomment %}
 
-{%- elsif nav_levels[2] -%}
+    {{ activation_collection_prefix }} > li:nth-child({{ nav_levels[1] }})
+    {%- for i in (2..nav_page_level) %} > ul > li:nth-child({{ nav_levels[i] }})
+    {%- endfor %} > a {
+      font-weight: 600;
+      text-decoration: none;
+    }
 
-{{ activation_collection_prefix }} > li > a,
-{{ activation_collection_prefix }} > li > ul > li:not(:nth-child({{ nav_levels[2] }})) > a,
-{{ activation_collection_prefix }} > li > ul > li > ul > li > a {
-  background-image: none;
-}
+  {%- 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
+    {%- for i in (2..nav_page_level) %},
+    {{ activation_collection_prefix }} > li:nth-child({{ nav_levels[1] }}) > 
+    {%- for j in (2..i) %} ul > li:nth-child({{ nav_levels[j] }}) >
+    {%- endfor %} button svg
+    {%- endfor %} {
+      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
+    {%- for i in (2..nav_page_level) %},
+    {{ activation_collection_prefix }} > li.nav-list-item:nth-child({{ nav_levels[1] }}) >
+    {%- for j in (2..i) %} ul.nav-list > li.nav-list-item:nth-child({{ nav_levels[j] }}) >
+    {%- endfor %} ul.nav-list
+    {%- endfor %} {
+      display: block;
+    }
 
 {%- else -%}
 
-{{ activation_collection_prefix }} > li:not(:nth-child({{ nav_levels[1] }})) > a,
-{{ activation_collection_prefix }} > li > ul > li > a,
-{{ activation_collection_prefix }} > li > ul > li > ul > li > a {
-  background-image: none;
-}
+  {%- comment -%}
+    not site_nav contains nav_list_link
+  {%- endcomment -%}
 
-{%- endif %}
-
-{%- comment -%}
-  The following rule removes the image from the links to pages in other collections.
-{%- endcomment %}
-
-{{ activation_other_collection_prefix }} a,
-.site-nav li.external a {
-  background-image: none;
-}
-
-{%- comment -%}
-  The following rule styles the link to the current page.
-{%- endcomment %}
-
-{{ activation_collection_prefix }} > li:nth-child({{ nav_levels[1] }})
-{%- if nav_levels[2] %} > ul > li:nth-child({{ nav_levels[2] }})
-{%- if nav_levels[3] %} > ul > li:nth-child({{ nav_levels[3] }})
-{%- endif -%}
-{%- endif %} > a {
-  font-weight: 600;
-  text-decoration: none;
-}
-
-{%- comment -%}
-  The following rules unfold all collections, and display the links to any children
-  of the current page.
-  
-  To avoid dependence on the SCSS variable nav-list-expander-right, the direction
-  of the rotation of the expander icon is fixed, and corresponds to the appearance
-  when nav-list-expander-right is true. This results in a minor visual difference
-  between the appearance of active expander icons when JS is enabled/disabled and
-  nav-list-expander-right is false, which seems unavoidable.
-{%- endcomment %}
-
-{%- if site.just_the_docs.collections %}
-.site-nav > ul.nav-category-list > li > button svg,
-{% endif -%}
-{{ activation_collection_prefix }} > li:nth-child({{ nav_levels[1] }}) > button svg
-{%- if nav_levels[2] -%},
-{{ activation_collection_prefix }} > li:nth-child({{ nav_levels[1] }}) > ul > li:nth-child({{ nav_levels[2] }}) > button svg
-{%- endif %} {
-  transform: rotate(-90deg);
-}
-
-{%- if site.just_the_docs.collections %}
-.site-nav > ul.nav-category-list > li.nav-list-item > ul.nav-list,
-{% endif -%}
-{{ activation_collection_prefix }} > li.nav-list-item:nth-child({{ nav_levels[1] }}) > ul.nav-list
-{%- if nav_levels[2] %},
-{{ activation_collection_prefix }} > li.nav-list-item:nth-child({{ nav_levels[1] }}) > ul.nav-list > li.nav-list-item:nth-child({{ nav_levels[2] }}) > ul.nav-list
-{%- endif %} {
-  display: block;
-}
+    {{ activation_no_nav_link }}
 
 {%- endif -%}
-{%- endif -%}

_layouts/default.html

@@ -9,7 +9,13 @@ layout: table_wrappers
 <body>
   <a class="skip-to-main" href="#main-content">Skip to main content</a>
   {% include icons/icons.html %}
-  {% include components/sidebar.html %}
+  {% if page.nav_enabled == true %}
+    {% include components/sidebar.html %}
+  {% elsif layout.nav_enabled == true and page.nav_enabled == nil %}
+    {% include components/sidebar.html %}
+  {% elsif site.nav_enabled != false and layout.nav_enabled == nil and page.nav_enabled == nil %}
+    {% include components/sidebar.html %}
+  {% endif %}
   <div class="main" id="top">
     {% include components/header.html %}
     <div class="main-content-wrap">
@@ -22,7 +28,7 @@ layout: table_wrappers
             {{ content }}
           {% endif %}
 
-          {% if page.has_children == true and page.has_toc != false %}
+          {% if page.has_toc != false %}
             {% include components/children_nav.html %}
           {% endif %}
         </main>

_layouts/minimal.html

@@ -1,34 +1,6 @@
 ---
-layout: table_wrappers
+layout: default
+nav_enabled: false
 ---
 
-<!DOCTYPE html>
-
-<html lang="{{ site.lang | default: 'en-US' }}">
-{% include head.html %}
-<body>
-  <a class="skip-to-main" href="#main-content">Skip to main content</a>
-  {% include icons/icons.html %}
-  <div class="main-content-wrap" id="top">
-    {% include components/breadcrumbs.html %}
-    <div id="main-content" class="main-content" role="main">
-      {% if site.heading_anchors != false %}
-        {% include vendor/anchor_headings.html html=content beforeHeading="true" anchorBody="<svg viewBox=\"0 0 16 16\" aria-hidden=\"true\"><use xlink:href=\"#svg-link\"></use></svg>" anchorClass="anchor-heading" anchorAttrs="aria-labelledby=\"%html_id%\"" %}
-      {% else %}
-        {{ content }}
-      {% endif %}
-
-      {% if page.has_children == true and page.has_toc != false %}
-        {% include components/children_nav.html %}
-      {% endif %}
-
-      {% include components/footer.html %}
-
-    </div>
-  </div>
-
-  {% if site.mermaid %}
-    {% include components/mermaid.html %}
-  {% endif %}
-</body>
-</html>
+{{ content }}

_sass/base.scss

@@ -10,9 +10,9 @@
 }
 
 html {
-  @include fs-4;
-
   scroll-behavior: smooth;
+
+  @include fs-4;
 }
 
 body {

_sass/code.scss

@@ -142,10 +142,10 @@ div.highlighter-rouge {
 
 // for AsciiDoc. we also need to fix the margins for its parent container.
 div.listingblock {
-  @include scroll-and-spacing("div.content", "div.content > pre");
-
   margin-top: 0;
   margin-bottom: $sp-3;
+
+  @include scroll-and-spacing("div.content", "div.content > pre");
 }
 
 // {% highlight LANG %}...{% endhighlight %},
@@ -176,12 +176,12 @@ figure.highlight {
 
   td,
   pre {
-    @include fs-2;
-
     min-width: 0;
     padding: 0;
     background-color: $code-background-color;
     border: 0;
+
+    @include fs-2;
   }
 
   td.gl {

_sass/labels.scss

@@ -14,9 +14,9 @@
   text-transform: uppercase;
   vertical-align: middle;
   background-color: $blue-100;
-  @include fs-2;
-
   border-radius: 12px;
+
+  @include fs-2;
 }
 
 .label-green:not(g) {

_sass/layout.scss

@@ -19,32 +19,57 @@
     width: calc((100% - #{$nav-width + $content-width}) / 2 + #{$nav-width});
     min-width: $nav-width;
   }
+
+  & + .main {
+    @include mq(md) {
+      margin-left: $nav-width-md;
+    }
+
+    @include mq(lg) {
+      // stylelint-disable function-name-case
+      // disable for Max(), we want to use the CSS max() function
+      margin-left: Max(
+        #{$nav-width},
+        calc((100% - #{$nav-width + $content-width}) / 2 + #{$nav-width})
+      );
+      // stylelint-enable function-name-case
+    }
+
+    .main-header {
+      display: none;
+      background-color: $sidebar-color;
+
+      @include mq(md) {
+        display: flex;
+        background-color: $body-background-color;
+      }
+
+      &.nav-open {
+        display: block;
+
+        @include mq(md) {
+          display: flex;
+        }
+      }
+    }
+  }
 }
 
 .main {
+  margin: auto;
+
   @include mq(md) {
     position: relative;
     max-width: $content-width;
-    margin-left: $nav-width-md;
-  }
-
-  @include mq(lg) {
-    // stylelint-disable function-name-case
-    // disable for Max(), we want to use the CSS max() function
-    margin-left: Max(
-      #{$nav-width},
-      calc((100% - #{$nav-width + $content-width}) / 2 + #{$nav-width})
-    );
-    // stylelint-enable function-name-case
   }
 }
 
 .main-content-wrap {
-  @include container;
-
   padding-top: $gutter-spacing-sm;
   padding-bottom: $gutter-spacing-sm;
 
+  @include container;
+
   @include mq(md) {
     padding-top: $gutter-spacing;
     padding-bottom: $gutter-spacing;
@@ -53,23 +78,12 @@
 
 .main-header {
   z-index: 0;
-  display: none;
-  background-color: $sidebar-color;
+  border-bottom: $border $border-color;
 
   @include mq(md) {
     display: flex;
     justify-content: space-between;
     height: $header-height;
-    background-color: $body-background-color;
-    border-bottom: $border $border-color;
-  }
-
-  &.nav-open {
-    display: block;
-
-    @include mq(md) {
-      display: flex;
-    }
   }
 }
 
@@ -112,8 +126,6 @@
 }
 
 .site-title {
-  @include container;
-
   flex-grow: 1;
   display: flex;
   height: 100%;
@@ -121,6 +133,9 @@
   padding-top: $sp-3;
   padding-bottom: $sp-3;
   color: $body-heading-color;
+
+  @include container;
+
   @include fs-6;
 
   @include mq(md) {
@@ -186,14 +201,15 @@ body {
 // stylelint-enable selector-max-type
 
 .site-footer {
-  @include container;
-
   position: absolute;
   bottom: 0;
   left: 0;
   padding-top: $sp-4;
   padding-bottom: $sp-4;
   color: $grey-dk-000;
+
+  @include container;
+
   @include fs-2;
 
   @include mq(md) {

_sass/navigation.scss

@@ -8,11 +8,11 @@
   list-style: none;
 
   .nav-list-item {
-    @include fs-4;
-
     position: relative;
     margin: 0;
 
+    @include fs-4;
+
     @include mq(md) {
       @include fs-3;
     }

_sass/support/mixins/_typography.scss

@@ -1,5 +1,7 @@
 @mixin fs-1 {
-  font-size: $font-size-1 !important;
+  & {
+    font-size: $font-size-1 !important;
+  }
 
   @include mq(sm) {
     font-size: $font-size-1-sm !important;
@@ -7,7 +9,9 @@
 }
 
 @mixin fs-2 {
-  font-size: $font-size-2 !important;
+  & {
+    font-size: $font-size-2 !important;
+  }
 
   @include mq(sm) {
     font-size: $font-size-3 !important;
@@ -15,7 +19,9 @@
 }
 
 @mixin fs-3 {
-  font-size: $font-size-3 !important;
+  & {
+    font-size: $font-size-3 !important;
+  }
 
   @include mq(sm) {
     font-size: $font-size-4 !important;
@@ -23,7 +29,9 @@
 }
 
 @mixin fs-4 {
-  font-size: $font-size-4 !important;
+  & {
+    font-size: $font-size-4 !important;
+  }
 
   @include mq(sm) {
     font-size: $font-size-5 !important;
@@ -31,7 +39,9 @@
 }
 
 @mixin fs-5 {
-  font-size: $font-size-5 !important;
+  & {
+    font-size: $font-size-5 !important;
+  }
 
   @include mq(sm) {
     font-size: $font-size-6 !important;
@@ -39,7 +49,9 @@
 }
 
 @mixin fs-6 {
-  font-size: $font-size-6 !important;
+  & {
+    font-size: $font-size-6 !important;
+  }
 
   @include mq(sm) {
     font-size: $font-size-7 !important;
@@ -48,8 +60,10 @@
 }
 
 @mixin fs-7 {
-  font-size: $font-size-7 !important;
-  line-height: $body-heading-line-height;
+  & {
+    font-size: $font-size-7 !important;
+    line-height: $body-heading-line-height;
+  }
 
   @include mq(sm) {
     font-size: $font-size-8 !important;
@@ -57,8 +71,10 @@
 }
 
 @mixin fs-8 {
-  font-size: $font-size-8 !important;
-  line-height: $body-heading-line-height;
+  & {
+    font-size: $font-size-8 !important;
+    line-height: $body-heading-line-height;
+  }
 
   @include mq(sm) {
     font-size: $font-size-9 !important;
@@ -66,8 +82,10 @@
 }
 
 @mixin fs-9 {
-  font-size: $font-size-9 !important;
-  line-height: $body-heading-line-height;
+  & {
+    font-size: $font-size-9 !important;
+    line-height: $body-heading-line-height;
+  }
 
   @include mq(sm) {
     font-size: $font-size-10 !important;
@@ -75,8 +93,10 @@
 }
 
 @mixin fs-10 {
-  font-size: $font-size-10 !important;
-  line-height: $body-heading-line-height;
+  & {
+    font-size: $font-size-10 !important;
+    line-height: $body-heading-line-height;
+  }
 
   @include mq(sm) {
     font-size: $font-size-10-sm !important;

_sass/tables.scss

@@ -21,14 +21,14 @@ table {
 
 th,
 td {
-  @include fs-3;
-
   min-width: 7.5rem;
   padding: $sp-2 $sp-3;
   background-color: $table-background-color;
   border-bottom: $border rgba($border-color, 0.5);
   border-left: $border $border-color;
 
+  @include fs-3;
+
   &:first-of-type {
     border-left: 0;
   }

_sass/typography.scss

@@ -3,9 +3,9 @@
 
 h1,
 .text-alpha {
-  @include fs-8;
-
   font-weight: 300;
+
+  @include fs-8;
 }
 
 h2,
@@ -21,11 +21,11 @@ h3,
 
 h4,
 .text-delta {
-  @include fs-2;
-
   font-weight: 400;
   text-transform: uppercase;
   letter-spacing: 0.1em;
+
+  @include fs-2;
 }
 
 h4 code {

_sass/vendor/OneDarkJekyll/syntax.scss

@@ -5,198 +5,261 @@ pre.highlight {
   background: #31343f;
   color: #dee2f7;
 }
+
 .highlight pre {
   background: #31343f;
 }
+
 .highlight .hll {
   background: #31343f;
 }
+
 .highlight .c {
   color: #63677e;
   font-style: italic;
 }
+
 .highlight .err {
   color: #960050;
   background-color: #1e0010;
 }
+
 .highlight .k {
   color: #e19ef5;
 }
+
 .highlight .l {
   color: #a3eea0;
 }
+
 .highlight .n {
   color: #dee2f7;
 }
+
 .highlight .o {
   color: #dee2f7;
 }
+
 .highlight .p {
   color: #dee2f7;
 }
+
 .highlight .cm {
   color: #63677e;
   font-style: italic;
 }
+
 .highlight .cp {
   color: #63677e;
   font-style: italic;
 }
+
 .highlight .c1 {
   color: #63677e;
   font-style: italic;
 }
+
 .highlight .cs {
   color: #63677e;
   font-style: italic;
 }
+
 .highlight .ge {
   font-style: italic;
 }
+
 .highlight .gs {
   font-weight: 700;
 }
+
 .highlight .kc {
   color: #e19ef5;
 }
+
 .highlight .kd {
   color: #e19ef5;
 }
+
 .highlight .kn {
   color: #e19ef5;
 }
+
 .highlight .kp {
   color: #e19ef5;
 }
+
 .highlight .kr {
   color: #e19ef5;
 }
+
 .highlight .kt {
   color: #e19ef5;
 }
+
 .highlight .ld {
   color: #a3eea0;
 }
+
 .highlight .m {
   color: #eddc96;
 }
+
 .highlight .s {
   color: #a3eea0;
 }
+
 .highlight .na {
   color: #eddc96;
 }
+
 .highlight .nb {
   color: #fdce68;
 }
+
 .highlight .nc {
   color: #fdce68;
 }
+
 .highlight .no {
   color: #fdce68;
 }
+
 .highlight .nd {
   color: #fdce68;
 }
+
 .highlight .ni {
   color: #fdce68;
 }
+
 .highlight .ne {
   color: #fdce68;
 }
+
 .highlight .nf {
   color: #dee2f7;
 }
+
 .highlight .nl {
   color: #fdce68;
 }
+
 .highlight .nn {
   color: #dee2f7;
 }
+
 .highlight .nx {
   color: #dee2f7;
 }
+
 .highlight .py {
   color: #fdce68;
 }
+
 .highlight .nt {
   color: #f9867b;
 }
+
 .highlight .nv {
   color: #fdce68;
 }
+
 .highlight .ow {
   font-weight: 700;
 }
+
 .highlight .w {
   color: #f8f8f2;
 }
+
 .highlight .mf {
   color: #eddc96;
 }
+
 .highlight .mh {
   color: #eddc96;
 }
+
 .highlight .mi {
   color: #eddc96;
 }
+
 .highlight .mo {
   color: #eddc96;
 }
+
 .highlight .sb {
   color: #a3eea0;
 }
+
 .highlight .sc {
   color: #a3eea0;
 }
+
 .highlight .sd {
   color: #a3eea0;
 }
+
 .highlight .s2 {
   color: #a3eea0;
 }
+
 .highlight .se {
   color: #a3eea0;
 }
+
 .highlight .sh {
   color: #a3eea0;
 }
+
 .highlight .si {
   color: #a3eea0;
 }
+
 .highlight .sx {
   color: #a3eea0;
 }
+
 .highlight .sr {
   color: #7be2f9;
 }
+
 .highlight .s1 {
   color: #a3eea0;
 }
+
 .highlight .ss {
   color: #7be2f9;
 }
+
 .highlight .bp {
   color: #fdce68;
 }
+
 .highlight .vc {
   color: #fdce68;
 }
+
 .highlight .vg {
   color: #fdce68;
 }
+
 .highlight .vi {
   color: #f9867b;
 }
+
 .highlight .il {
   color: #eddc96;
 }
+
 .highlight .gu {
   color: #75715e;
 }
+
 .highlight .gd {
   color: #f92672;
 }
+
 .highlight .gi {
   color: #a6e22e;
 }

_sass/vendor/OneLightJekyll/syntax.scss

@@ -5,204 +5,269 @@ pre.highlight {
   background: #f9f9f9;
   color: #383942;
 }
+
 .highlight pre {
   background: #f9f9f9;
 }
+
 .highlight .hll {
   background: #f9f9f9;
 }
+
 .highlight .c {
   color: #9fa0a6;
   font-style: italic;
 }
+
 .highlight .err {
   color: #fff;
   background-color: #e05151;
 }
+
 .highlight .k {
   color: #a625a4;
 }
+
 .highlight .l {
   color: #50a04f;
 }
+
 .highlight .n {
   color: #383942;
 }
+
 .highlight .o {
   color: #383942;
 }
+
 .highlight .p {
   color: #383942;
 }
+
 .highlight .cm {
   color: #9fa0a6;
   font-style: italic;
 }
+
 .highlight .cp {
   color: #9fa0a6;
   font-style: italic;
 }
+
 .highlight .c1 {
   color: #9fa0a6;
   font-style: italic;
 }
+
 .highlight .cs {
   color: #9fa0a6;
   font-style: italic;
 }
+
 .highlight .ge {
   font-style: italic;
 }
+
 .highlight .gs {
   font-weight: 700;
 }
+
 .highlight .kc {
   color: #a625a4;
 }
+
 .highlight .kd {
   color: #a625a4;
 }
+
 .highlight .kn {
   color: #a625a4;
 }
+
 .highlight .kp {
   color: #a625a4;
 }
+
 .highlight .kr {
   color: #a625a4;
 }
+
 .highlight .kt {
   color: #a625a4;
 }
+
 .highlight .ld {
   color: #50a04f;
 }
+
 .highlight .m {
   color: #b66a00;
 }
+
 .highlight .s {
   color: #50a04f;
 }
+
 .highlight .na {
   color: #b66a00;
 }
+
 .highlight .nb {
   color: #ca7601;
 }
+
 .highlight .nc {
   color: #ca7601;
 }
+
 .highlight .no {
   color: #ca7601;
 }
+
 .highlight .nd {
   color: #ca7601;
 }
+
 .highlight .ni {
   color: #ca7601;
 }
+
 .highlight .ne {
   color: #ca7601;
 }
+
 .highlight .nf {
   color: #383942;
 }
+
 .highlight .nl {
   color: #ca7601;
 }
+
 .highlight .nn {
   color: #383942;
 }
+
 .highlight .nx {
   color: #383942;
 }
+
 .highlight .py {
   color: #ca7601;
 }
+
 .highlight .nt {
   color: #e35549;
 }
+
 .highlight .nv {
   color: #ca7601;
 }
+
 .highlight .ow {
   font-weight: 700;
 }
+
 .highlight .w {
   color: #f8f8f2;
 }
+
 .highlight .mf {
   color: #b66a00;
 }
+
 .highlight .mh {
   color: #b66a00;
 }
+
 .highlight .mi {
   color: #b66a00;
 }
+
 .highlight .mo {
   color: #b66a00;
 }
+
 .highlight .sb {
   color: #50a04f;
 }
+
 .highlight .sc {
   color: #50a04f;
 }
+
 .highlight .sd {
   color: #50a04f;
 }
+
 .highlight .s2 {
   color: #50a04f;
 }
+
 .highlight .se {
   color: #50a04f;
 }
+
 .highlight .sh {
   color: #50a04f;
 }
+
 .highlight .si {
   color: #50a04f;
 }
+
 .highlight .sx {
   color: #50a04f;
 }
+
 .highlight .sr {
   color: #0083bb;
 }
+
 .highlight .s1 {
   color: #50a04f;
 }
+
 .highlight .ss {
   color: #0083bb;
 }
+
 .highlight .bp {
   color: #ca7601;
 }
+
 .highlight .vc {
   color: #ca7601;
 }
+
 .highlight .vg {
   color: #ca7601;
 }
+
 .highlight .vi {
   color: #e35549;
 }
+
 .highlight .il {
   color: #b66a00;
 }
+
 .highlight .gu {
   color: #75715e;
 }
+
 .highlight .gd {
   color: #e05151;
 }
+
 .highlight .gi {
   color: #43d089;
 }
+
 .highlight .language-json .w + .s2 {
   color: #e35549;
 }
+
 .highlight .language-json .kc {
   color: #0083bb;
 }

_sass/vendor/normalize.scss/normalize.scss

@@ -10,7 +10,7 @@
 
 html {
   line-height: 1.15; /* 1 */
-  -webkit-text-size-adjust: 100%; /* 2 */
+  text-size-adjust: 100%; /* 2 */
 }
 
 /* Sections
@@ -62,7 +62,7 @@ hr {
  */
 
 pre {
-  font-family: monospace, monospace; /* 1 */
+  font-family: monospace; /* 1 */
   font-size: 1em; /* 2 */
 }
 
@@ -105,7 +105,7 @@ strong {
 code,
 kbd,
 samp {
-  font-family: monospace, monospace; /* 1 */
+  font-family: monospace; /* 1 */
   font-size: 1em; /* 2 */
 }
 
@@ -198,7 +198,7 @@ button,
 [type="button"],
 [type="reset"],
 [type="submit"] {
-  -webkit-appearance: button;
+  appearance: button;
 }
 
 /**
@@ -290,7 +290,7 @@ textarea {
  */
 
 [type="search"] {
-  -webkit-appearance: textfield; /* 1 */
+  appearance: textfield; /* 1 */
   outline-offset: -2px; /* 2 */
 }
 
@@ -299,7 +299,7 @@ textarea {
  */
 
 [type="search"]::-webkit-search-decoration {
-  -webkit-appearance: none;
+  appearance: none;
 }
 
 /**
@@ -308,7 +308,7 @@ textarea {
  */
 
 ::-webkit-file-upload-button {
-  -webkit-appearance: button; /* 1 */
+  appearance: button; /* 1 */
   font: inherit; /* 2 */
 }
 

assets/js/just-the-docs.js

@@ -1,4 +1,5 @@
 ---
+layout: null
 ---
 (function (jtd, undefined) {
 
@@ -555,12 +556,14 @@ function activateNav() {
 // Document ready
 
 jtd.onReady(function(){
-  initNav();
+  if (document.getElementById('site-nav')) {
+    initNav();
+    activateNav();
+    scrollNav();
+  }
   {%- if site.search_enabled != false %}
   initSearch();
   {%- endif %}
-  activateNav();
-  scrollNav();
 });
 
 // Copy button on code

assets/js/zzzz-search-data.json

@@ -1,4 +1,5 @@
 ---
+layout: null
 permalink: /assets/js/search-data.json
 ---
 {

docker-compose.yml

@@ -1,14 +0,0 @@
-version: "3.5"
-
-services:
-  jekyll:
-    build:
-      context: ./
-    ports:
-      - 4000:4000
-    volumes:
-      - .:/usr/src/app
-    stdin_open: true
-    tty: true
-    command: bundle exec jekyll serve -H 0.0.0.0 -t
-

docs/configuration.md

@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Configuration
 nav_order: 2
 ---
@@ -87,7 +86,7 @@ mermaid:
 
 Provide a `path` instead of a `version` key to load the mermaid library from a local file.
 
-See [the Code documentation]({% link docs/ui-components/code.md %}#mermaid-diagram-code-blocks) for more configuration options and information.
+See [the Code documentation]({% link docs/ui-components/code/index.md %}#mermaid-diagram-code-blocks) for more configuration options and information.
 
 ## Aux links
 
@@ -101,6 +100,14 @@ aux_links:
 aux_links_new_tab: false
 ```
 
+## Navigation sidebar
+
+```yaml
+# Enable or disable the side/mobile menu globally
+# Nav menu can also be selectively enabled or disabled using page variables or the minimal layout
+nav_enabled: true
+```
+
 ## Heading anchor links
 
 ```yaml
@@ -118,7 +125,7 @@ New (v0.4.0)
 {: .label .label-green }
 
 External links can be added to the navigation through the `nav_external_links` option.
-See [Navigation Structure]({% link docs/navigation-structure.md %}#external-navigation-links) for more details.
+See [Navigation Structure]({% link docs/navigation/main/external.md %}) for more details.
 
 ## Footer content
 
@@ -145,7 +152,7 @@ gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into t
 _note: `footer_content` is deprecated, but still supported. For a better experience we have moved this into an include called `_includes/footer_custom.html` which will allow for robust markup / liquid-based content._
 
 - the "page last modified" data will only display if a page has a key called `last_modified_date`, formatted in some readable date format
-- `last_edit_time_format` uses Ruby's DateTime formatter; see examples and more information [at this link.](https://apidock.com/ruby/DateTime/strftime)
+- `last_edit_time_format` uses Ruby's DateTime formatter; for examples and information, please refer to the [official Ruby docs on `strftime` formatting](https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html)
 - `gh_edit_repository` is the URL of the project's GitHub repository
 - `gh_edit_branch` is the branch that the docs site is served from; defaults to `main`
 - `gh_edit_source` is the source directory that your project files are stored in (should be the same as [site.source](https://jekyllrb.com/docs/configuration/options/))

docs/customization.md

@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Customization
 nav_order: 6
 ---
@@ -21,8 +20,8 @@ Just the Docs supports two color schemes: light (default), and dark.
 
 To enable a color scheme, set the `color_scheme` parameter in your site's `_config.yml` file:
 
-#### Example
-{: .no_toc }
+### Example: preview dark color scheme
+{: .no_toc .text-delta }
 
 ```yaml
 # Color scheme supports "light" (default) and "dark"
@@ -77,8 +76,8 @@ Available variables are listed in the [\_variables.scss](https://github.com/just
 
 For example, to change the link color from the purple default to blue, include the following inside your scheme file:
 
-#### Example
-{: .no_toc }
+#### Example: custom link color
+{: .no_toc .text-delta }
 
 ```scss
 $link-color: $blue-000;
@@ -143,10 +142,10 @@ Additionally, you may want to add completely custom CSS specific to your content
 To do this, put your styles in the file `_sass/custom/custom.scss`.
 This will allow for all overrides to be kept in a single file, and for any upstream changes to still be applied.
 
-For example, if you'd like to add your own styles for printing a page, you could add the following styles.
+### Example: custom print styles
+{: .no_toc .text-delta }
 
-#### Example
-{: .no_toc }
+For example, if you'd like to add your own styles for printing a page, you could add the following styles.
 
 ```scss
 // Print-only styles.
@@ -178,9 +177,9 @@ New (v0.4.0)
 
 `_includes/toc_heading_custom.html`
 
-If the page has any child pages, and `has_toc` is not set to `false`, this content appears as a heading above the [auto-generating list of child pages]({% link docs/navigation-structure.md %}#auto-generating-table-of-contents) after the page's content.
+If the page has any child pages, and `has_toc` is not set to `false`, this content appears as a heading above the [auto-generating list of child pages]({% link docs/navigation/children.md %}) after the page's content.
 
-#### Example
+#### Example: changing TOC heading
 {: .no_toc }
 
 To change the default TOC heading to "Contents", create `_includes/toc_heading_custom.html` and add:
@@ -329,43 +328,9 @@ Future versions may subdivide components further; we guarantee that we will only
 
 ### Alternative layouts and example (`minimal`)
 
-Users can develop custom layouts that compose, omit, or add components differently. We provide one first-class example titled `minimal`, inspired by Kevin Lin's work in [just-the-class](https://github.com/kevinlin1/just-the-class). This `minimal` layout does not render the sidebar, header, or search. To see an example, visit the [minimal layout test]({{site.baseurl}}/docs/minimal-test/) page.
+Users can develop custom layouts that compose, omit, or add components differently. We provide one first-class example titled `minimal`, which disables the navigation sidebar. To see an example, visit the [minimal layout test]({{site.baseurl}}/docs/minimal-test/) page.
 
-Here is a simplified code example of what it looks like:
-
-{% raw %}
-
-```liquid
-<!-- a simplified version of _layouts/minimal.html -->
-<html>
-{% include head.html %}
-<body>
-  {% include icons/icons.html %}
-  {% comment %} Bandaid fix for breadcrumbs here! {% endcomment %}
-  {% include components/breadcrumbs.html %}
-
-  {% if site.heading_anchors != false %}
-    {% include vendor/anchor_headings.html html=content ... %}
-  {% else %}
-    {{ content }}
-  {% endif %}
-
-  {% if page.has_children == true and page.has_toc != false %}
-    {% include components/children_nav.html %}
-  {% endif %}
-
-  {% include components/footer.html %}
-
-  {% if site.mermaid %}
-    {% include components/mermaid.html %}
-  {% endif %}
-</body>
-</html>
-```
-
-{% endraw %}
-
-This layout is packaged in Just the Docs. Users can indicate this alternative layout in page front matter:
+Users can indicate this alternative layout in page front matter:
 
 {% raw %}
 
@@ -384,10 +349,10 @@ Similarly, users and developers can create other alternative layouts using Just
 
 Under the hood,
 
-- `default` and `minimal` inherit from the `table_wrappers` layout, which wraps all HTML `<table>` tags with a `div .table-wrapper`
+- `default` inherit from the `table_wrappers` layout, which wraps all HTML `<table>` tags with a `div .table-wrapper`
 - `table_wrappers` inherits from `vendor/compress`, which is a local copy of Anatol Broder's [jekyll-compress-html](https://github.com/penibelst/jekyll-compress-html) Jekyll plugin
 
-Note that as of now, `minimal` and `default` have no inheritance relationship.
+The `minimal` layout inherits from the `default` but assigns `nav_enabled: false` to disable the navigation sidebar.
 
 ### Overridden default Jekyll layouts
 

docs/index-test.md

@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Markdown kitchen sink
 nav_order: 99
 ---
@@ -28,17 +27,17 @@ There should be whitespace between paragraphs.
 
 There should be whitespace between paragraphs. We recommend including a README, or a file with information about your project.
 
-# [](#header-1)Header 1
+# Header 1
 
 This is a normal paragraph following a header. GitHub is a code hosting platform for version control and collaboration. It lets you and others work together on projects from anywhere.
 
-## [](#header-2)Header 2
+## Header 2
 
 > This is a blockquote following a header.
 >
 > When something is important enough, you do it even if the odds are not in your favor.
 
-### [](#header-3)Header 3
+### Header 3
 
 ```js
 // Javascript code with syntax highlighting.
@@ -55,19 +54,19 @@ GitHubPages::Dependencies.gems.each do |gem, version|
 end
 ```
 
-#### [](#header-4-with-code-not-transformed)Header 4 `with code not transformed`
+#### Header 4 `with code not transformed`
 
 *   This is an unordered list following a header.
 *   This is an unordered list following a header.
 *   This is an unordered list following a header.
 
-##### [](#header-5)Header 5
+##### Header 5
 
 1.  This is an ordered list following a header.
 2.  This is an ordered list following a header.
 3.  This is an ordered list following a header.
 
-###### [](#header-6)Header 6
+###### Header 6
 
 [This is a very long link which wraps and therefore doesn't overflow
 even when it comes at the beginning](.) of the line.
@@ -304,6 +303,8 @@ The following code is displayed as a diagram only when a `mermaid` key supplied
 
 ```mermaid
 graph TD;
+    accTitle: the diamond pattern
+    accDescr: a graph with four nodes: A points to B and C, while B and C both point to D
     A-->B;
     A-->C;
     B-->D;

docs/layout/layout.md

@@ -2,7 +2,6 @@
 title: Layout
 layout: default
 nav_order: 4.5
-has_children: true
 ---
 
 # Layout
@@ -18,17 +17,30 @@ You can use [Jekyll's front matter defaults] to specify the same layout for many
 
 ## The `default` layout
 
-This page uses the default layout.
+This page uses the default layout. This site configures `layout: default` as a [front matter default](https://jekyllrb.com/docs/configuration/front-matter-defaults/) value for all pages in the `docs` directory.
 
-It is a *responsive* layout: on medium and larger width displays, it displays a sidebar, including a navigation panel; on smaller width displays, the sidebar is automatically hidden under a button.
+The default layout of Just the Docs is a *responsive* layout: on medium and larger width displays, it displays a sidebar, including a navigation panel; on smaller width displays, the sidebar is automatically hidden under a button.
 
-Each child (and grandchild) page of a top-level page has so-called *breadcrumbs*: links to its parent (and grandparent) pages. It shows the breadcrumbs above the main content of the page.
+All pages except top-level pages automatically have a list of  so-called *breadcrumbs*: links to their parent pages and any higher-level ancestors. They show the breadcrumbs above the main content of the page.
 
 Each page that has child pages generally has a list of links to those pages (you can suppress it by `has_toc: false` in the front matter). It shows the list as a *table of contents* below the main content.
 
 ## The `minimal` layout
 
-A child and grandchild page of this page use the minimal layout. This differs from the default layout by omitting the sidebar -- and thereby also the navigation panel. To navigate between pages with the minimal layout, you can use the breadcrumbs and the tables of contents.
+A child and grandchild page of this page use the minimal layout. This differs from the default layout by omitting the sidebar---and thereby also the navigation panel. To navigate between pages with the minimal layout, you can use the breadcrumbs and the tables of contents.
+
+## Selectively hiding or showing the sidebar
+
+[Jekyll's front matter defaults] can be used to apply the `minimal` layout for many pages. But there are also other variables that can control the page layout. In `_config.yml`, you can set `nav_enabled: false` to disable the sidebar navigation panel across the entire site. This can then be selectively enabled on a page-by-page basis by assigning the `nav_enabled: true` page [front matter] variable. For instance, this could be used to enable sidebar navigation on a home page while all other pages have sidebar navigation disabled.
+
+```yaml
+---
+layout: default
+title: Home
+nav_enabled: true
+---
+
+```
 
 ## Other layouts
 

docs/layout/minimal/default-child.md

@@ -1,8 +1,10 @@
 ---
 title: Default layout child page
 layout: default
-parent: A minimal layout page 
+parent: A minimal layout page
 grand_parent: Layout
 ---
 
-This is a child page that uses the same minimal layout as its parent page.
+# Default layout child page
+
+This is a child page that uses the `default` layout as compared to its parent page (which uses the `minimal` layout).

docs/layout/minimal/minimal-child.md

@@ -5,4 +5,6 @@ parent: A minimal layout page
 grand_parent: Layout
 ---
 
+# Minimal layout child page
+
 This is a child page that uses the same minimal layout as its parent page.

docs/layout/minimal/minimal.md

@@ -2,7 +2,6 @@
 title: A minimal layout page
 layout: minimal
 parent: Layout
-has_children: true
 ---
 
 # A minimal layout page

docs/minimal-test.md

@@ -4,6 +4,8 @@ title: Minimal layout test
 nav_exclude: true
 ---
 
+# Minimal Layout Test Page
+
 [Return to main website]({{site.baseurl}}/).
 
 This page demonstrates the packaged `minimal` layout, which does not render the sidebar or header. It can be used for standalone pages. It is also an example of using the new modular site components to define custom layouts; see ["Custom layouts and includes" in the customization docs]({{site.baseurl}}/docs/customization/#custom-layouts-and-includes) for more information.

docs/navigation-structure.md

@@ -1,364 +0,0 @@
----
-layout: default
-title: Navigation Structure
-nav_order: 5
----
-
-# Navigation Structure
-{: .no_toc }
-
-<details open markdown="block">
-  <summary>
-    Table of contents
-  </summary>
-  {: .text-delta }
-- TOC
-{:toc}
-</details>
-
----
-
-## Main navigation
-
-The main navigation for your Just the Docs site is on the left side of the page on large screens and on the top (behind a tap) on small screens. The main navigation can be structured to accommodate a multi-level menu system (pages with children and grandchildren).
-
-By default, all pages will appear as top level pages in the main nav unless a parent page is defined (see [Pages with Children](#pages-with-children)).
-
----
-
-## Ordering pages
-
-To specify a page order, you can use the `nav_order` parameter in your pages' YAML front matter.
-
-### Example (ordering pages)
-{: .no_toc }
-
-```yaml
----
-layout: default
-title: Customization
-nav_order: 4
----
-
-```
-
-The parameter values determine the order of the top-level pages, and of child pages with the same parent. You can reuse the same parameter values (e.g., integers starting from 1) for the child pages of different parents.
-
-The parameter values can be numbers (integers, floats) and/or strings. Pages with numerical `nav_order` parameters always come before those with string `nav_order` parameters. When you omit `nav_order` parameters, they default to the titles of the pages. If you want to make the page order independent of the page titles, you can set explicit `nav_order` parameters on all pages. All pages with explicit `nav_order` parameters
-come before all pages ordered by their `title` values.
-
-By default, all Capital letters come before all lowercase letters; you can add `nav_sort: case_insensitive` in the configuration file to ignore the case. Enclosing strings in (single or double) quotation marks is optional. Numeric values are not enclosed in quotation marks, e.g., `42`, `-1.0`; numbers in quotation marks are lexicographically ordered, so `"10"` comes before `"2"`, for example.
-
----
-
-## Excluding pages
-
-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 (excluding pages)
-{: .no_toc }
-
-```yaml
----
-layout: default
-title: 404
-nav_exclude: true
----
-
-```
-
-The `nav_exclude` parameter does not affect the [auto-generating list of child pages](#auto-generating-table-of-contents), which you can use to access pages excluded from the main navigation.
-
-Pages with no `title` are automatically excluded from the main navigation.
-
----
-
-## Pages with children
-
-Sometimes you will want to create a page with many children (a section). First, it is recommended that you keep pages that are related in a directory together... For example, in these docs, we keep all of the written documentation in the `./docs` directory and each of the sections in subdirectories like `./docs/ui-components` and `./docs/utilities`. This gives us an organization like:
-
-```
-+-- ..
-|-- (Jekyll files)
-|
-|-- docs
-|   |-- ui-components
-|   |   |-- index.md  (parent page)
-|   |   |-- buttons.md
-|   |   |-- code.md
-|   |   |-- labels.md
-|   |   |-- tables.md
-|   |   +-- typography.md
-|   |
-|   |-- utilities
-|   |   |-- index.md      (parent page)
-|   |   |-- color.md
-|   |   |-- layout.md
-|   |   |-- responsive-modifiers.md
-|   |   +-- typography.md
-|   |
-|   |-- (other md files, pages with no children)
-|   +-- ..
-|
-|-- (Jekyll files)
-+-- ..
-```
-
-On the parent pages, add this YAML front matter parameter:
-
-- `has_children: true` (tells us that this is a parent page)
-
-### Example (parent pages)
-{: .no_toc }
-
-```yaml
----
-layout: default
-title: UI Components
-nav_order: 2
-has_children: true
----
-
-```
-
-Here we're setting up the UI Components landing page that is available at `/docs/ui-components`, which has children and is ordered second in the main nav.
-
-### Child pages
-
-{: .text-gamma }
-
-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 (child pages)
-{: .no_toc }
-
-```yaml
----
-layout: default
-title: Buttons
-parent: UI Components
-nav_order: 2
----
-
-```
-
-The Buttons page appears as a child of UI Components and appears second in the UI Components section.
-
-### Ordering child pages
-{: .d-inline-block }
-
-New (v0.4.0)
-{: .label .label-green }
-
-You can optionally add the following to the YAML front matter to reverse the default sort order of child pages:
-
-- `child_nav_order: reversed`
-
-#### Example (ordering child pages)
-{: .no_toc }
-```yaml
----
-layout: default
-title: Reversed Child Pages
-child_nav_order: reversed
----
-```
-
-### Auto-generating Table of Contents
-
-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 (auto-generating Table of Contents)
-{: .no_toc }
-
-```yaml
----
-layout: default
-title: UI Components
-nav_order: 2
-has_children: true
-has_toc: false
----
-
-```
-
-### Children with children
-
-{: .text-gamma }
-
-Child pages can also have children (grandchildren). This is achieved by using a similar pattern on the child and grandchild pages.
-
-1. Add the `has_children` attribute to the child
-1. Add the `parent` and `grand_parent` attribute to the grandchild
-
-##### Example (children within children)
-{: .no_toc }
-
-```yaml
----
-layout: default
-title: Buttons
-parent: UI Components
-nav_order: 2
-has_children: true
----
-
-```
-
-```yaml
----
-layout: default
-title: Buttons Child Page
-parent: Buttons
-grand_parent: UI Components
-nav_order: 1
----
-
-```
-
-This would create the following navigation structure:
-
-```
-+-- ..
-|
-|-- UI Components
-|   |-- ..
-|   |
-|   |-- Buttons
-|   |   |-- Button Child Page
-|   |
-|   |-- ..
-|
-+-- ..
-```
-
-{: .note }
-Currently, the navigation structure is limited to 3 levels: grandchild pages cannot themselves have child pages.
-
----
-
-## 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 (auxiliary links)
-{: .no_toc }
-
-```yaml
-# Aux links for the upper right navigation
-aux_links:
-  "Just the Docs on GitHub":
-    - "//github.com/just-the-docs/just-the-docs"
-```
-
----
-
-## External Navigation Links
-{: .d-inline-block }
-
-New (v0.4.0)
-{: .label .label-green }
-
-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 (external navigation links)
-{: .no_toc }
-
-```yaml
-# External navigation links
-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 (in-page navigation with Table of Contents)
-{: .no_toc }
-
-```markdown
-# Navigation Structure
-{: .no_toc }
-
-## Table of contents
-{: .no_toc .text-delta }
-
-1. TOC
-{:toc}
-```
-
-This example skips the page name heading (`#`) from the TOC, as well as the heading for the Table of Contents itself (`##`) because it is redundant, followed by the table of contents itself. To get an unordered list, replace `1. TOC` above by `- TOC`.
-
-### Collapsible Table of Contents
-
-The Table of Contents can be made collapsible using the `<details>` and `<summary>` elements, as in the following example. The attribute `open` (expands the Table of Contents by default) and the styling with `{: .text-delta }` are optional.
-
-```markdown
-<details open markdown="block">
-  <summary>
-    Table of contents
-  </summary>
-  {: .text-delta }
-1. TOC
-{:toc}
-</details>
-```
-
-The result is shown at [the top of this page](#navigation-structure) (`{:toc}` can be used only once on each page).

docs/navigation/auxiliary.md

@@ -0,0 +1,20 @@
+---
+title: Auxiliary Links
+parent: Navigation
+nav_order: 2
+---
+
+# Auxiliary Links
+
+You can add a list of auxiliary links to your site, shown at the top right on all pages. You do this by including the `aux_links` [configuration option]({% link docs/configuration.md %}#aux-links) in your site's `_config.yml` file.
+
+## Example Auxiliary Link
+{: .text-delta }
+
+This website has an auxiliary link: "Just the Docs on GitHub". It is rendered with the following code:
+
+```yaml
+aux_links:
+  Just the Docs on GitHub:
+    - https://github.com/just-the-docs/just-the-docs
+```

docs/navigation/children.md

@@ -0,0 +1,22 @@
+---
+title: Child Pages
+parent: Navigation
+nav_order: 4
+---
+
+# Child Pages
+
+By default, all parent pages will automatically have a so-called 'Table of Contents' at the bottom, showing links to all their child pages.
+
+To disable this automatic list, set `has_toc: false` in the parent page's front matter.
+
+## Example: disabling table of contents
+{: .text-delta }
+
+```yaml
+---
+title: UI Components
+nav_order: 3
+has_toc: false
+---
+```

docs/navigation/in-page.md

@@ -0,0 +1,96 @@
+---
+title: In-Page Navigation
+parent: Navigation
+nav_order: 5
+---
+
+# In-Page Navigation
+{: .no_toc }
+
+## Table of Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+To support in-page navigation, you can generate a *Table of Contents* (TOC) with links to headings, like the one shown above, as well as a link to the top of the page.
+
+## Generating Table of Contents
+
+To generate a *Table of Contents* in a page, you use Kramdown's `{:toc}` method, immediately after the start of a list. This will automatically generate a list of anchor links to various sections of the page, based on headings and heading levels.
+
+{: .note }
+`{:toc}` can be used only once on each page.
+
+You **must** have a list immediately preceding the table of contents. The type of list determines the style of your table of contents.
+
+For an *ordered* table of contents, use the following markdown code:
+
+```md
+1. TOC
+{:toc}
+```
+
+The `{:toc}` line *must* follow the `1. TOC` line, which begins a list.
+
+For an *unordered* table of contents, instead use the following markdown code:
+
+```
+- TOC
+{:toc}
+```
+
+## Omitting Heading from Table of Contents
+
+If you want to omit a particular heading from the TOC, follow it immediately by `{: .no_toc }` (possibly together with other CSS class names).
+
+```markdown
+# In-Page Navigation
+{: .no_toc }
+
+## Table of Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+```
+
+This example omits the top-level heading (`In-Page Navigation`) from the TOC, as well as the heading for the *Table of Contents* itself.
+
+## Collapsible Table of Contents (with `<details>` and `<summary>`)
+
+You can make the Table of Contents collapsible using the `<details>` and `<summary>` elements, as in the following example.
+
+```markdown
+<details open markdown="block">
+  <summary>
+    Table of contents
+  </summary>
+  {: .text-delta }
+1. TOC
+{:toc}
+</details>
+```
+
+The attribute `open` (which expands the Table of Contents by default) and the styling (here with `text-delta`) are optional.
+
+## Back to Top {#back-to-top-doc}
+
+{: .warning }
+The default id for a section with heading "Back to Top" is `"back-to-top"`.
+To avoid invalid HTML, sites that set the `back_to_top` configuration variable
+should override the default id for such sections. The Markdown source file for
+the current page uses `## Back to Top {#back-to-top-doc}`.
+
+You can add a link from the bottom of each page to its top. You do this by including the `back_to_top` configuration option in your site's `_config.yml` file, together with `back_to_top_text` for the anchor link.
+
+### Example
+{: .no_toc }
+
+```yaml
+back_to_top: true
+back_to_top_text: "Back to top"
+```
+
+{: .warning }
+Back-to-top links currently appear only when *other* configuration options require footer generation!

docs/navigation/index.md

@@ -0,0 +1,16 @@
+---
+title: Navigation
+nav_order: 5
+---
+
+# Navigation
+
+The default page layout supports various navigation features:
+
+* a **main navigation** panel, highlighting the currently selected page;
+* a list of **auxiliary** links, shown on all pages;
+* lists of **breadcrumbs**, shown on all except top level pages;
+* optional lists of links to **child pages** (so-called 'tables of contents'); and
+* section heading links for **in-page navigation**, with an optional **back-to-top** link.
+
+See the following pages for how to specify these features, with illustrative examples.

docs/navigation/main/ancestry.md

@@ -0,0 +1,52 @@
+---
+title: Ancestry
+parent: Main Navigation
+nav_order: 4
+---
+
+# Ancestry
+
+If no two pages on your website have the same `title`, you only need to set the `parent` titles to fix the hierarchy. You can also have the same `title` on pages that have no children, provided that they have different parent pages.
+
+If two parents have the same `title`, but different grandparents, you can set their `grand_parent` titles to distinguish between their parents. The `grand_parent` title needs to be the same as the `parent` of the `parent`.
+
+## Example: distinguishing parents with `grand_parent`
+{: .text-delta }
+
+```yaml
+---
+title: T
+parent: S
+grand_parent: X
+---
+```
+
+```yaml
+---
+title: T
+parent: S
+grand_parent: Y
+---
+```
+
+The `ancestor` field of a page generalizes `grand_parent` to higher levels.
+
+The following pages illustrate `parent` disambiguation using `grand_parent` and `ancestor` titles. Some descendants of both [Page X][X] and [Page Y][Y] have the same title, so references to those descendants as `parent` always require disambiguation.
+
+- [X][X] is a parent page
+- [S][XS] is the only child of [X][X]. The `parent` reference to [X][X] is unambiguous.
+- [T][XT] is the only child of [S][XS]. Its `parent` is disambiguated by its `grand_parent`.
+- [U][XU] is the only child of [T][XT]. Its `parent` is disambiguated by its `ancestor`.
+- [Y][Y] is a sibling of [X][X].
+- [S][YS] is the only child of [Y][Y]. The `parent` reference to [Y][Y] is unambiguous.
+- [T][YT] is the only child of [S][YS]. Its `parent` is disambiguated by its `ancestor`
+- [U][YU] is the only child of [T][YT]. Its `parent` is disambiguated by its `ancestor`.
+
+[X]: {% link docs/navigation/main/x.md %}
+[XS]: {% link docs/navigation/main/xs.md %}
+[XT]: {% link docs/navigation/main/xt.md %}
+[XU]: {% link docs/navigation/main/xu.md %}
+[Y]: {% link docs/navigation/main/y.md %}
+[YS]: {% link docs/navigation/main/ys.md %}
+[YT]: {% link docs/navigation/main/yt.md %}
+[YU]: {% link docs/navigation/main/yu.md %}

docs/navigation/main/collections.md

@@ -0,0 +1,69 @@
+---
+title: Collections
+parent: Main Navigation
+nav_order: 5
+---
+
+# Collections
+
+By default, the navigation includes only [normal pages](https://jekyllrb.com/docs/pages/).
+However, you can configure Just the Docs to include also pages from [Jekyll collections](https://jekyllrb.com/docs/collections/).
+
+{: .note }
+> You store collection pages in directories that start with an underscore (`_`), e.g., `_tests`. You won't see your `tests` collection pages in the navigation if you store them in a `tests` directory![^1]
+
+[^1]: You can optionally specify a directory to store all your collections. For example, if you specify `collections_dir: my_collections` in `_config.yml`, you should then store the pages of the `tests` collection in the `my_collections/_tests` directory.
+
+## Example: defining custom collections
+{: .text-delta }
+
+To define a Jekyll `tests` collection named `Tests` in your main navigation, store its pages in the `_tests` directory, and add the following to `_config.yml`:
+
+```yaml
+collections:
+  tests:
+    output: true
+
+just_the_docs:
+  collections:
+    tests:
+      name: Tests
+```
+
+Together with the `name` to be used for a collection in the navigation, you can configure the following options:
+
+* `nav_exclude: true` to exclude the entire collection from the main navigation
+* `nav_fold: true` to fold the collection, instead of showing links to all its top-level pages[^2]
+* `search_exclude: true` to exclude all the collection pages from search results
+
+[^2]:
+    When JavaScript is disabled in the browser, all folded collections are automatically expanded,
+    since clicking expander symbols has no effect.
+
+The main navigation for all your normal pages (if any) is displayed before those in collections. When *all* your pages are in a single collection, its name is not displayed.
+
+## Example: multiple collections
+{: .text-delta }
+
+You can configure multiple collections. This creates categories in the main navigation with the configured names.
+
+```yaml
+collections:
+  tests:
+    output: true
+  tutorials:
+    output: true
+
+just_the_docs:
+  collections:
+    tests:
+      name: Tests
+      search_exclude: true
+    tutorials:
+      name: Tutorials
+      nav_fold: true
+```
+
+The navigation for each collection is a separate name space for page titles: a page in one collection cannot be the `parent` of a page in a different collection, nor of a normal page.
+
+----

docs/navigation/main/exclude.md

@@ -0,0 +1,30 @@
+---
+title: Excluding Pages
+parent: Main Navigation
+nav_order: 2
+---
+
+# Excluding Pages
+
+For specific pages that you do not wish to include in the main navigation (e.g., a 404 page or a landing page) set `nav_exclude: true` in their front matter.
+
+## Example: using `nav_exclude`
+{: .text-delta }
+
+```yaml
+---
+layout: default
+title: 404
+nav_exclude: true
+permalink: /404
+---
+```
+
+The `nav_exclude` parameter does not affect the [breadcrumbs]({% link docs/navigation/parents.md %}), nor the [lists of child pages]({% link docs/navigation/children.md %}), which you can use to access pages excluded from the main navigation.
+
+Pages with no `title` are automatically excluded from the main navigation, except when they are in collections (where Jekyll provides default titles based on file names).
+
+Child pages are automatically excluded from the main navigation when their parent page is excluded.
+
+{: .warning }
+It is currently possible to exclude all the child pages of a page from the main navigation by setting `has_children: false` in its front matter. However, the `has_children` parameter may be ignored altogether in a future release, so it is better to use the `nav_exclude` parameter on each child page.

docs/navigation/main/external.md

@@ -0,0 +1,34 @@
+---
+title: External Links
+parent: Main Navigation
+nav_order: 6
+---
+
+# External Links
+
+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: external links
+{: .text-delta }
+
+```yaml
+# External navigation links
+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
+
+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.

docs/navigation/main/index.md

@@ -0,0 +1,41 @@
+---
+title: Main Navigation
+parent: Navigation
+nav_order: 1
+---
+
+# Main Navigation
+
+The main navigation for your Just the Docs site is at the left side of the page on large screens, and at the top (behind a tap) on small screens.
+
+You need to specify the `title` of each page in its front matter. Page titles are independent of file names and directory structure. The navigation uses the title of the page as an anchor for links to the page.
+
+By default, links to all pages appear in the main navigation at the top level, ordered alphabetically by their titles. By adding further fields to the front matter of individual pages, you can [change their order]({% link docs/navigation/main/order.md %}), [exclude pages]({% link docs/navigation/main/exclude.md %}), and change their [parent pages]({% link docs/navigation/main/levels.md %}).
+
+{: .new-title }
+> New (v0.10.0)
+>
+> The main navigation can be structured as a multi-level menu of unlimited depth:
+> pages can always have child pages.
+
+For the construction of the navigation display to work (and to avoid potential confusion when browsing) ***the page titles on your site need to satisfy the following requirements:***
+
+* Top-level pages must have different titles.
+* Pages with the same parent must have different titles.
+* The title of each page must be different from the titles of all its child pages, and from the titles of their child pages, etc.
+
+{: .new-title }
+> New (v0.10.0)
+>
+> If *all* the pages of your site have different titles, you need only to specify the `title` of each page, and the `parent` title of each lower-level page.[^1]
+
+[^1]: Previous versions of Just the Docs restricted the navigation to three levels. You also needed to specify `has_children: true` on all parent pages, and a `grand_parent` title on all grandchild pages. The `has_children` parameter is now redundant, and the `grand_parent` parameter can usually be omitted.
+
+If your site has pages with the same title, you need to avoid confusion when you reference that title as `parent` on other pages. When the pages with the same title have different `parent` pages, you can distinguish between them using the `grand_parent` parameter.
+
+{: .new-title }
+> New (v0.10.0)
+>
+> For deeper navigation structures, you can specify the title of a grandparent or higher level page as an `ancestor` title.
+
+----

docs/navigation/main/levels.md

@@ -0,0 +1,126 @@
+---
+title: Page Levels
+parent: Main Navigation
+nav_order: 3
+---
+
+# Page Levels
+
+Sometimes you will want to create a page with many children. First, it is recommended that you store related pages together in a directory. For example, in these docs, we keep all of the written documentation pages in the `./docs` directory, and each of the sections in subdirectories like `./docs/ui-components` and `./docs/utilities`. This gives us an organization like this:
+
+{: .lh-0 }
+```
+┌─ ...
+├─ (Jekyll files)
+├─ docs
+    ├─ configuration.md
+    ├─ ui-components
+        ├─ index.md (parent page)
+        ├─ buttons.md
+        ├─ callouts.md
+        ├─ code
+            ├─ index.md (parent page)
+            └─ line-numbers.md
+        ├─ labels.md
+        ├─ tables.md
+        └─ typography.md
+    ├─ ...
+    └─ MIGRATION.md
+├─ index.md (home page)
+├─ (Jekyll files)
+└─ ...
+```
+
+## Example: page with no parents
+{: .text-delta }
+
+```yaml
+---
+title: UI Components
+nav_order: 3
+---
+```
+
+Here we're setting up the UI Components landing page that is available at URL `/docs/ui-components`, which is ordered second in the main navigation.
+
+The navigation links for all pages with children come with an expander. When you click the expander, the display of the children is toggled, so you can expand or collapse all the children displays, regardless of which page is currently active.
+
+## Child Pages
+
+On child pages, simply set the `parent` front matter to the parent page's `title`, and set a navigation order (relative to pages having the same parent).
+
+### Example: creating a child page
+{: .text-delta }
+
+```yaml
+---
+title: Buttons
+parent: UI Components
+nav_order: 2
+---
+```
+
+The Buttons page appears as a child of UI Components and appears second in the UI Components pages.
+
+{: .new-title }
+> New (v0.10.0)
+>
+> The `has_children` field is now redundant (and ignored, except when significant for backwards compatibility).
+
+## Multi-level Child Pages
+
+Child pages can themselves have children, to any number of levels.
+
+### Example: pages with (recursive) children
+{: .text-delta }
+
+```yaml
+---
+title: Main Navigation
+parent: Navigation
+nav_order: 1
+---
+```
+
+```yaml
+---
+title: Ancestry
+parent: Main Navigation
+nav_order: 4
+---
+```
+
+```yaml
+---
+title: X
+parent: Ancestry
+---
+```
+
+```yaml
+---
+title: Y
+parent: Ancestry
+---
+```
+
+This creates the following navigation structure:
+
+{: .lh-0 }
+```
+┌─ ...
+├─ ...
+├─ Navigation
+    ├─ ...
+    ├─ Main Navigation
+        ├─ ...
+        ├─ Ancestry
+            ├─ X
+            └─ Y
+        ├─ ...
+        └─ ...
+    ├─ ...
+    └─ ...
+├─ ...
+└─ ...
+```

docs/navigation/main/order.md

@@ -0,0 +1,36 @@
+---
+title: Ordering Pages
+parent: Main Navigation
+nav_order: 1
+---
+
+# Ordering Pages
+
+To specify a page order, you can use the `nav_order` parameter in the front matter of the pages.
+
+## Example: using `nav_order`
+{: .text-delta }
+
+```yaml
+---
+title: Customization
+nav_order: 6
+---
+```
+
+The parameter values determine the order of the top-level pages, and of child pages with the same parent. You can reuse the same parameter values (e.g., integers starting from 1) for the child pages of different parents.
+
+The parameter values can be numbers (integers, floats[^floats]) and/or strings. When you omit `nav_order` parameters, they default to the titles of the pages, which are ordered alphabetically. Pages with numerical `nav_order` parameters always come before those with strings or default `nav_order` parameters. If you want to make the page order independent of the page titles, you can set explicit `nav_order` parameters on all pages.
+
+{: .warning }
+The order of pages with equal `nav_order` parameters is unstable: it may change with each build.
+
+By default, all Capital letters come before all lowercase letters; you can add `nav_sort: case_insensitive` in the configuration file to ignore the case.[^case-insensitive]
+
+Enclosing strings in quotation marks in front matter is optional, unless they contain "`[`", "`]`", "`{`", "`}`", "`,`", "`: `", or "` #`". Boolean, integer, and float values are treated as strings when enclosed in quotation marks.
+
+----
+
+[^floats]: Jekyll treats each integer *N* as equal to the corresponding float *N.0*.
+
+[^case-insensitive]: *Note for users of previous versions of Just the Docs:* The option `nav_sort: case_insensitive` previously affected the ordering of numerical `nav_order` parameters: e.g., `10` came before `2`. Also, all pages with explicit `nav_order` parameters previously came before all pages with default parameters. Both were potentially confusing, and they have now been eliminated.

docs/navigation/main/x.md

@@ -0,0 +1,10 @@
+---
+title: X
+parent: Ancestry
+---
+# X
+
+```yaml
+title: X
+parent: Ancestry
+```

docs/navigation/main/xs.md

@@ -0,0 +1,10 @@
+---
+title: S
+parent: X
+---
+# S
+
+```yaml
+title: S
+parent: X
+```

docs/navigation/main/xt.md

@@ -0,0 +1,12 @@
+---
+title: T
+parent: S
+grand_parent: X
+---
+# T
+
+```yaml
+title: T
+parent: S
+grand_parent: X
+```

docs/navigation/main/xu.md

@@ -0,0 +1,12 @@
+---
+title: U
+parent: T
+ancestor: X
+---
+# U
+
+```yaml
+title: U
+parent: T
+ancestor: X
+```

docs/navigation/main/y.md

@@ -0,0 +1,10 @@
+---
+title: Y
+parent: Ancestry
+---
+# Y
+
+```yaml
+title: Y
+parent: Ancestry
+```

docs/navigation/main/ys.md

@@ -0,0 +1,10 @@
+---
+title: S
+parent: Y
+---
+# S
+
+```yaml
+title: S
+parent: Y
+```

docs/navigation/main/yt.md

@@ -0,0 +1,12 @@
+---
+title: T
+parent: S
+ancestor: Y
+---
+# T
+
+```yaml
+title: T
+parent: S
+ancestor: Y
+```

docs/navigation/main/yu.md

@@ -0,0 +1,12 @@
+---
+title: U
+parent: T
+ancestor: Y
+---
+# U
+
+```yaml
+title: U
+parent: T
+ancestor: Y
+```

docs/navigation/parents.md

@@ -0,0 +1,11 @@
+---
+title: Breadcrumbs
+parent: Navigation 
+nav_order: 3
+---
+
+# Breadcrumbs
+
+When using the default layout, all pages except top-level pages will automatically have a list of 'breadcrumbs' at the top, linking to the parent page and to any higher-level ancestors.
+
+The default layout does not provide an option to suppress the list of breadcrumbs. To do that, you would need to define a new layout, or override the file `_includes/components/breadcrumbs.html` (e.g., with an empty file).

docs/search.md

@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Search
 nav_order: 7
 ---
@@ -114,8 +113,6 @@ Will make <kbd>Ctrl</kbd> + <kbd>K</kbd> focus the search bar for Windows users
 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.
 To exclude a page from search, add the `search_exclude: true` parameter to the page's YAML front matter:
 
-#### Example
-
 {: .no_toc }
 
 ```yaml
@@ -159,7 +156,8 @@ By default, the search feature indexes a page's `.content`, `.title`, and *some*
 2. Add a new file named `_includes/lunr/custom-data.json`. Insert custom Liquid code that reads your data (e.g. the page object at `include.page`) then generates custom Javascript fields that hold the custom data you want to index. Verify these fields in the generated `assets/js/search-data.json`.
 3. Add a new file named `_includes/lunr/custom-index.js`. Insert custom Javascript code that reads your custom Javascript fields and inserts them into the search index. You may want to inspect `assets/js/just-the-docs.js` to better understand the code.
 
-#### Example
+### Example: adding custom `usage` and `examples` fields
+{: .text-delta }
 
 This example adds front matter `usage` and `examples` fields to the search index.
 

docs/ui-components/buttons.md

@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Buttons
 parent: UI Components
 nav_order: 2

docs/ui-components/callouts.md

@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Callouts
 parent: UI Components
 nav_order: 7
@@ -23,8 +22,8 @@ When you have [configured]({% link docs/configuration.md %}#callouts) the  `colo
 [^postfix]:
     You can put the callout markup either before or after its content.
 
-#### An untitled callout
-{: .no_toc }
+## An untitled callout
+{: .no_toc .text-delta }
 
 ```markdown
 {: .highlight }
@@ -35,8 +34,8 @@ A paragraph
 A paragraph
 
 
-#### A single paragraph callout
-{: .no_toc }
+## A single paragraph callout
+{: .no_toc .text-delta }
 
 ```markdown
 {: .note }
@@ -58,8 +57,8 @@ A paragraph
 >
 > A paragraph with a custom title callout
 
-#### A multi-paragraph callout
-{: .no_toc }
+## A multi-paragraph callout
+{: .no_toc .text-delta }
 
 ```markdown
 {: .important }
@@ -97,8 +96,8 @@ A paragraph
 >
 > The last paragraph
 
-#### An indented callout
-{: .no_toc }
+## An indented callout
+{: .no_toc .text-delta }
 
 ```markdown
 > {: .highlight }
@@ -108,8 +107,8 @@ A paragraph
 > {: .highlight }
   A paragraph
 
-#### Indented multi-paragraph callouts
-{: .no_toc }
+## Indented multi-paragraph callouts
+{: .no_toc .text-delta }
 
 ```markdown
 > {: .new }
@@ -128,8 +127,8 @@ A paragraph
 > > The last paragraph
 
 
-#### Nested callouts
-{: .no_toc }
+## Nested callouts
+{: .no_toc .text-delta }
 
 ```markdown
 {: .important }
@@ -141,8 +140,8 @@ A paragraph
 > {: .warning }
 > A paragraph
 
-#### Opaque background
-{: .no_toc }
+## Opaque background
+{: .no_toc .text-delta }
 
 ```markdown
 {: .important }

docs/ui-components/code/index.md

@@ -1,8 +1,6 @@
 ---
-layout: default
 title: Code
 parent: UI Components
-has_children: true
 nav_order: 6
 ---
 
@@ -58,7 +56,7 @@ 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 %}).
+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/code/line-numbers.md %}).
 
 ---
 
@@ -131,6 +129,8 @@ Once mermaid is installed, it can be used in markdown files. The markdown for a
 {% highlight markdown %}
 ```mermaid
 graph TD;
+    accTitle: the diamond pattern
+    accDescr: a graph with four nodes: A points to B and C, while B and C both point to D
     A-->B;
     A-->C;
     B-->D;
@@ -142,6 +142,8 @@ which renders:
 
 ```mermaid
 graph TD;
+    accTitle: the diamond pattern
+    accDescr: a graph with four nodes: A points to B and C, while B and C both point to D
     A-->B;
     A-->C;
     B-->D;
@@ -179,6 +181,8 @@ By default, AsciiDoc generates HTML markup that mermaid cannot properly parse. T
 ++++
 <pre class="language-mermaid">
 graph TD;
+    accTitle: the diamond pattern
+    accDescr: a graph with four nodes: A points to B and C, while B and C both point to D
     A-->B;
     A-->C;
     B-->D;

docs/ui-components/code/line-numbers.md

@@ -1,15 +1,11 @@
 ---
-layout: default
-title: Code with line numbers
+title: Line Numbers
 parent: Code
-grand_parent: UI Components
-permalink: /docs/ui-components/code/line-numbers/
 ---
 
-# Code snippets with 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

docs/ui-components/index.md

@@ -1,9 +1,6 @@
 ---
-layout: default
 title: UI Components
 nav_order: 3
-has_children: true
-permalink: /docs/ui-components
 ---
 
 # UI Components

docs/ui-components/labels.md

@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Labels
 parent: UI Components
 nav_order: 3

docs/ui-components/lists.md

@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Lists
 parent: UI Components
 nav_order: 5

docs/ui-components/tables.md

@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Tables
 parent: UI Components
 nav_order: 4

docs/ui-components/typography.md

@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Typography
 parent: UI Components
 nav_order: 1

docs/utilities/color.md

@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Color
 parent: Utilities
 ---

docs/utilities/index.md

@@ -1,9 +1,6 @@
 ---
-layout: default
 title: Utilities
 nav_order: 4
-has_children: true
-permalink: docs/utilities
 ---
 
 # Utilities

docs/utilities/layout.md

@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Layout
 parent: Utilities
 ---
@@ -19,7 +18,7 @@ parent: Utilities
 
 These spacers are available to use for margins and padding with responsive utility classes. Combine these prefixes with a screen size and spacing scale to use them responsively.
 
-| Classname prefix | What it does                  |
+| Classname prefix | Related CSS Property          |
 |:-----------------|:------------------------------|
 | `.m-`            | `margin`                      |
 | `.mx-`           | `margin-left`, `margin-right` |
@@ -29,7 +28,7 @@ These spacers are available to use for margins and padding with responsive utili
 | `.mb-`           | `margin-bottom`               |
 | `.ml-`           | `margin-left`                 |
 
-| Classname prefix | What it does                    |
+| Classname prefix | Related CSS Property            |
 |:-----------------|:--------------------------------|
 | `.p-`            | `padding`                       |
 | `.px-`           | `padding-left`, `padding-right` |
@@ -55,8 +54,8 @@ Spacing values are based on a `1rem = 16px` spacing scale, broken down into thes
 
 Use `mx-auto` to horizontally center elements.
 
-#### Examples
-{: .no_toc }
+### Applying Spacing Utilities with `{: }`
+{: .no_toc .text-delta }
 
 In Markdown, use the `{: }` wrapper to apply custom classes:
 
@@ -70,7 +69,7 @@ This paragraph will have 2rem/32px of padding on the right and left at all scree
 
 ## Horizontal Alignment
 
-| Classname               | What it does                     |
+| CSS Class               | Applied CSS Declaration          |
 |:------------------------|:---------------------------------|
 | `.float-left`           | `float: left`                    |
 | `.float-right`          | `float: right`                   |
@@ -83,7 +82,7 @@ _Note: any of the `flex-` classes must be used on a parent element that has `d-f
 
 ## Vertical Alignment
 
-| Classname              | What it does                    |
+| CSS Class              | Applied CSS Declaration         |
 |:-----------------------|:--------------------------------|
 | `.v-align-baseline`    | `vertical-align: baseline`      |
 | `.v-align-bottom`      | `vertical-align: bottom`        |
@@ -96,7 +95,7 @@ _Note: any of the `flex-` classes must be used on a parent element that has `d-f
 
 Display classes aid in adapting the layout of the elements on a page:
 
-| Class             |                         |
+| CSS Class         | Applied CSS Declaration |
 |:------------------|:------------------------|
 | `.d-block`        | `display: block`        |
 | `.d-flex`         | `display: flex`         |
@@ -106,8 +105,8 @@ Display classes aid in adapting the layout of the elements on a page:
 
 Use these classes in conjunction with the responsive modifiers.
 
-#### Examples
-{: .no_toc }
+### Applying Display Utilities with `{: }`
+{: .no_toc .text-delta }
 
 In Markdown, use the `{: }` wrapper to apply custom classes:
 

docs/utilities/responsive-modifiers.md

@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Responsive Modifiers
 parent: Utilities
 ---

docs/utilities/typography.md

@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Typography
 parent: Utilities
 ---

fixtures/Gemfile-jekyll-3.9

@@ -2,10 +2,15 @@ source "https://rubygems.org"
 
 gem "jekyll", "~> 3.9"
 
+gem "base64"
+gem "bigdecimal"
+gem "csv"
+
 gem "jekyll-seo-tag", ">= 2.0"
 gem "rake", ">= 12.3.1"
 
 gem "jekyll-include-cache", group: :jekyll_plugins
+gem "jekyll-sitemap", group: :jekyll_plugins
 
 # required for Jekyll 3
 gem "webrick", "~> 1.7"

fixtures/Gemfile-jekyll-4.3

@@ -2,10 +2,14 @@ source "https://rubygems.org"
 
 gem "jekyll", "~> 4.3"
 
+gem "base64"
+gem "csv"
+
 gem "jekyll-seo-tag", ">= 2.0"
 gem "rake", ">= 12.3.1"
 
 gem "jekyll-include-cache", group: :jekyll_plugins
+gem "jekyll-sitemap", group: :jekyll_plugins
 
 # docs-only
 gem "jekyll-github-metadata", ">= 2.15"

index.md

@@ -1,6 +1,6 @@
 ---
-layout: default
 title: Home
+layout: home
 nav_order: 1
 description: "Just the Docs is a responsive Jekyll theme with built-in search that is easily customizable and hosted on GitHub Pages."
 permalink: /

just-the-docs.gemspec

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

lib/tasks/search.rake

@@ -9,6 +9,7 @@ namespace :search do
 
     File.open('assets/js/zzzz-search-data.json', 'w') do |f|
       f.puts '---
+layout: null
 permalink: /assets/js/search-data.json
 ---
 {

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.2.5",
-    "stylelint": "^15.11.0",
-    "stylelint-config-standard-scss": "^11.1.0"
+    "prettier": "^3.5.3",
+    "stylelint": "^16.16.0",
+    "stylelint-config-standard-scss": "^14.0.0"
   },
   "scripts": {
     "lint": "npm-run-all --parallel --continue-on-error lint:*",
@@ -22,8 +22,7 @@
     "ignoreFiles": [
       "assets/css/just-the-docs-default.scss",
       "assets/css/just-the-docs-light.scss",
-      "assets/css/just-the-docs-dark.scss",
-      "_sass/vendor/**/*.scss"
+      "assets/css/just-the-docs-dark.scss"
     ],
     "extends": [
       "stylelint-config-standard-scss"