0.8.0

This PR uses the cached site-nav to determine the position of each page in the navigation hierarchy. [Profiling](https://just-the-docs.github.io/just-the-docs-tests/tests/profiles/index/) shows that it significantly reduces the v0.7.0 build time for larger sites – especially with Jekyll 3. The improvement is due mainly to the elimination of loops and filters that depended on the entire site. 

For example:

- [endoflife.date](https://just-the-docs.github.io/just-the-docs-tests/tests/profiles/endoflife.date/index/) drops from 32s to 11s
- [machinetranslate.org](https://just-the-docs.github.io/just-the-docs-tests/tests/profiles/machinetranslate.org/index/) drops from 267s to ~~73s~~ 56s

### Testing

[Just the Docs Tests](https://just-the-docs.github.io/just-the-docs-tests/) is currently built using this PR branch. With JS disabled, the highlighting and unfolding of the navigation panel should be as with v0.7.0.

A diff of the tests site built with this PR branch compared to v0.7.0 should report no significant changes. For more rigorous testing, diffs of variants of the tests site should also be inspected.

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+github: just-the-docs
+open_collective: just-the-docs

.github/release-drafter.yml

@@ -1,35 +0,0 @@
-references:
-  - v+
-  - main
-name-template: "v$RESOLVED_VERSION 🌈"
-tag-template: "v$RESOLVED_VERSION"
-categories:
-  - title: "🚀 Features"
-    labels:
-      - "feature"
-      - "enhancement"
-  - title: "🐛 Bug Fixes"
-    labels:
-      - "fix"
-      - "bugfix"
-      - "bug"
-  - title: "🧰 Maintenance"
-    label:
-      - "chore"
-      - "dependencies"
-change-template: "- $TITLE @$AUTHOR (#$NUMBER)"
-version-resolver:
-  major:
-    labels:
-      - "next-major-release"
-  minor:
-    labels:
-      - "next-minor-release"
-  patch:
-    labels:
-      - "patch"
-  default: minor
-template: |
-  ## Changes
-
-  $CHANGES

.github/workflows/ci.yml

@@ -5,24 +5,90 @@ on:
   pull_request:
     branches:
       - main
-      - 'v**'
 
 name: CI
 
 jobs:
   jekyll-build:
-    name: Build Jekyll site
+    name: Build (jekyll gem)
-    runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
-        jekyll-version: [3.8.5, latest]
+        jekyll-version: [3.9, 4.3]
+        os: [ ubuntu-latest, macos-latest, windows-latest ]
+        ruby-version: ["3.0", "3.1", "3.2"]
+    runs-on: ${{ matrix.os }}
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
-    - name: Build the site in the jekyll/jekyll container
+    - name: Setup Ruby ${{ matrix.ruby-version }}
-      run: |
+      uses: ruby/setup-ruby@v1
-        docker run --rm \
+      with:
-        --volume="${{ github.workspace }}:/srv/jekyll" \
+        ruby-version: ${{ matrix.ruby-version }}
-        jekyll/jekyll:${{ matrix.jekyll-version }} /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && bundle install && bundle exec jekyll build && bundle exec rake search:init"
+        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
+
+  validate:
+    name: Validate HTML
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ["3.2"]
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Ruby ${{ matrix.ruby-version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          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: Cache HTMLProofer
+        id: cache-htmlproofer
+        uses: actions/cache@v3
+        with:
+          path: tmp/.htmlproofer
+          key: ${{ runner.os }}-htmlproofer
+      - name: Build Site
+        run: bundle exec jekyll build
+      - name: Test with Nu Validator
+        uses: Cyb3r-Jak3/html5validator-action@2a593a9f2c10593cbac84791a6fc4c47e9a106c8
+        with:
+          config: fixtures/html5validator-config.yml
+      - name: Test with html-proofer
+        run: bundle exec htmlproofer _site --ignore-urls "/github.com/,/web.archive.org/"
+        env:
+          NOKOGIRI_USE_SYSTEM_LIBRARIES: true
 
   assets:
     name: Test CSS and JS
@@ -30,12 +96,12 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [16.x]
+        node-version: [18.x]
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v1
+      uses: actions/setup-node@v3
       with:
         node-version: ${{ matrix.node-version }}
     - run: npm install

.github/workflows/deploy.yml

@@ -0,0 +1,62 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+# Sample workflow for building and deploying a Jekyll site to GitHub Pages
+name: Deploy Jekyll site to Pages
+
+on:
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.2"
+          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
+        id: pages
+        uses: actions/configure-pages@v3
+      - name: Build with Jekyll
+        # Outputs to the './_site' directory by default
+        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
+        env:
+          JEKYLL_ENV: production
+      - name: Upload artifact
+        # Automatically uploads an artifact from the './_site' directory by default
+        uses: actions/upload-pages-artifact@v2
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.github/workflows/publish-gem.yml

@@ -9,11 +9,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
-    - name: Set up Ruby 2.6
+    - name: Setup Ruby 3.2
-      uses: actions/setup-ruby@v1
+      uses: ruby/setup-ruby@v1
       with:
-        ruby-version: 2.6.x
+        ruby-version: "3.2"
 
     - name: Publish to GPR
       run: |
@@ -27,13 +27,14 @@ jobs:
         GEM_HOST_API_KEY: "Bearer ${{secrets.GITHUB_TOKEN}}"
         OWNER: ${{ github.repository_owner }}
 
-    - name: Publish to RubyGems
+    # Disabled as this does not handle 2FA
-      run: |
+    # - name: Publish to RubyGems
-        mkdir -p $HOME/.gem
+    #   run: |
-        touch $HOME/.gem/credentials
+    #     mkdir -p $HOME/.gem
-        chmod 0600 $HOME/.gem/credentials
+    #     touch $HOME/.gem/credentials
-        printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
+    #     chmod 0600 $HOME/.gem/credentials
-        gem build *.gemspec
+    #     printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
-        gem push *.gem
+    #     gem build *.gemspec
-      env:
+    #     gem push *.gem
-        GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"
+    #   env:
+    #     GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"

.github/workflows/update_jekyll-anchor-heading.yml

@@ -0,0 +1,43 @@
+name: Update Vendor plugin - jekyll-anchor-headings
+on:
+  # schedule:
+  #   # once per week
+  #   - cron: "0 15 * * 0"
+  workflow_dispatch:
+jobs:
+  update-deps:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Get latest release information
+        id: latest-release
+        uses: pozetroninc/github-action-get-latest-release@master
+        with:
+          owner: allejo
+          repo: jekyll-anchor-headings
+          excludes: prerelease, draft
+
+      - name: Update jekyll-anchor-headings
+        id: update
+        uses: suisei-cn/actions-download-file@v1.3.0
+        with:
+          url: "https://github.com/allejo/jekyll-anchor-headings/releases/download/${{ steps.latest-release.outputs.release }}/anchor_headings.html"
+          target: _includes/vendor/
+
+      - name: Create PR
+        uses: peter-evans/create-pull-request@v4
+        with:
+          commit-message: "chore[dependency]: Update `jekyll-anchor-headings` to `${{ steps.latest-release.outputs.release }}`"
+          title: "auto: Update `jekyll-anchor-headings` to `${{ steps.latest-release.outputs.release }}`"
+          body: |
+            Update `jekyll-anchor-headings` to `${{ steps.latest-release.outputs.release }}`
+            This is an automated pull request.
+          branch: update/vendor/jekyll-anchor-headings
+          delete-branch: true
+          labels: |
+            kind/update
+            area/dependency
+          add-paths: |
+            _includes/vendor/anchor_headings.html
+          token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -1,8 +1,30 @@
+# Not sure what a .gitignore is?
+# See: https://git-scm.com/docs/gitignore
+
+# The first files are directly copied from Jekyll's first-party docs on `.gitignore` files:
+# https://jekyllrb.com/tutorials/using-jekyll-with-bundler/#commit-to-source-control
+
+# Ignore the default location of the built site, and caches and metadata generated by Jekyll
+_site/
+.sass-cache/
+.jekyll-cache/
+.jekyll-metadata
+
+# Ignore folders generated by Bundler
+.bundle/
+vendor/
+
+# These next files are used by Just the Docs developers. They are not necessary for end users of the theme, only developers.
+
+# We use Stylelint and Prettier, JavaScript tools, to lint and format our own code.
+# We use Node.js as our runtime, so we ignore node_modules
+node_modules
+
+# .DS_Store is a macOS-only metadata file about directories. Convention is to not commit them.
+# See: https://en.wikipedia.org/wiki/.DS_Store
+.DS_Store
+
+# These are legacy globs that typically target Ruby theme developers. We may change these at a later date.
 *.gem
 .bundle
 .ruby-version
-.jekyll-cache
-.sass-cache
-_site
-Gemfile.lock
-node_modules

.prettierignore

@@ -1,4 +1,3 @@
-package.json
 package-lock.json
 _site
 assets/css/just-the-docs-default.scss
@@ -6,5 +5,7 @@ assets/css/just-the-docs-light.scss
 assets/css/just-the-docs-dark.scss
 assets/js/vendor/lunr.min.js
 assets/js/search-data.json
+assets/js/zzzz-search-data.json
 assets/js/just-the-docs.js
 *.md
+_includes/mermaid_config.js

.prettierrc

@@ -1,7 +0,0 @@
-{
-  "endOfLine": "lf",
-  "semi": false,
-  "singleQuote": false,
-  "tabWidth": 2,
-  "trailingComma": "es5"
-}

.stylelintrc.json

@@ -1,21 +0,0 @@
-{
-  "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"
-  ],
-  "extends": [
-    "stylelint-config-standard-scss",
-    "stylelint-config-prettier-scss"
-  ],
-  "plugins": ["stylelint-prettier"],
-  "rules": {
-    "prettier/prettier": true,
-    "alpha-value-notation": null,
-    "color-function-notation": null,
-    "declaration-block-no-redundant-longhand-properties": null,
-    "no-descending-specificity": null,
-    "scss/no-global-function-names": null
-  }
-}

Gemfile

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

Gemfile.lock

@@ -0,0 +1,152 @@
+PATH
+  remote: .
+  specs:
+    just-the-docs (0.8.0)
+      jekyll (>= 3.8.5)
+      jekyll-include-cache
+      jekyll-seo-tag (>= 2.0)
+      rake (>= 12.3.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    Ascii85 (1.1.0)
+    addressable (2.8.6)
+      public_suffix (>= 2.0.2, < 6.0)
+    afm (0.2.2)
+    async (2.6.3)
+      console (~> 1.10)
+      fiber-annotation
+      io-event (~> 1.1)
+      timers (~> 4.1)
+    base64 (0.2.0)
+    colorator (1.1.0)
+    concurrent-ruby (1.2.2)
+    console (1.23.2)
+      fiber-annotation
+      fiber-local
+    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)
+    fiber-annotation (0.2.0)
+    fiber-local (1.0.0)
+    forwardable-extended (2.6.0)
+    google-protobuf (3.25.1-arm64-darwin)
+    google-protobuf (3.25.1-x86_64-linux)
+    hashery (2.1.2)
+    html-proofer (5.0.8)
+      addressable (~> 2.3)
+      async (~> 2.1)
+      nokogiri (~> 1.13)
+      pdf-reader (~> 2.11)
+      rainbow (~> 3.0)
+      typhoeus (~> 1.3)
+      yell (~> 2.0)
+      zeitwerk (~> 2.5)
+    http_parser.rb (0.8.0)
+    i18n (1.14.1)
+      concurrent-ruby (~> 1.0)
+    io-event (1.2.3)
+    jekyll (4.3.3)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 1.0)
+      jekyll-sass-converter (>= 2.0, < 4.0)
+      jekyll-watch (~> 2.0)
+      kramdown (~> 2.3, >= 2.3.1)
+      kramdown-parser-gfm (~> 1.0)
+      liquid (~> 4.0)
+      mercenary (>= 0.3.6, < 0.5)
+      pathutil (~> 0.9)
+      rouge (>= 3.0, < 5.0)
+      safe_yaml (~> 1.0)
+      terminal-table (>= 1.8, < 4.0)
+      webrick (~> 1.7)
+    jekyll-github-metadata (2.16.1)
+      jekyll (>= 3.4, < 5.0)
+      octokit (>= 4, < 7, != 4.4.0)
+    jekyll-include-cache (0.2.1)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-sass-converter (3.0.0)
+      sass-embedded (~> 1.54)
+    jekyll-seo-tag (2.8.0)
+      jekyll (>= 3.8, < 5.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    kramdown (2.4.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    liquid (4.0.4)
+    listen (3.8.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)
+      racc (~> 1.4)
+    nokogiri (1.16.2-x86_64-linux)
+      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)
+      afm (~> 0.2.1)
+      hashery (~> 2.0)
+      ruby-rc4
+      ttfunk
+    public_suffix (5.0.4)
+    racc (1.7.3)
+    rainbow (3.1.1)
+    rake (13.1.0)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rexml (3.2.6)
+    rouge (4.2.0)
+    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)
+    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)
+      ethon (>= 0.9.0)
+    unicode-display_width (2.5.0)
+    webrick (1.8.1)
+    yell (2.2.2)
+    zeitwerk (2.6.11)
+
+PLATFORMS
+  arm64-darwin
+  x86_64-linux
+
+DEPENDENCIES
+  bundler (>= 2.3.5)
+  html-proofer (~> 5.0)
+  jekyll-github-metadata (>= 2.15)
+  jekyll-include-cache
+  just-the-docs!
+
+BUNDLED WITH
+   2.4.13

MIGRATION.md

@@ -0,0 +1,521 @@
+---
+title: Migration and Upgrading
+layout: default
+---
+
+# Migrating and Upgrading
+
+Summary
+:   A site that uses `just-the-docs` (as a theme or as a remote theme) automatically
+    switches to a new release, unless it is pinned to a previous version.
+
+    This migration guide draws attention to:
+
+    - changes that might break your site,
+    - features added in the latest release, and
+    - features that have become deprecated (and are likely to be removed in a future release).
+
+This document contains instructions on how to migrate and upgrade Just the Docs sites from every minor or major version bump, starting from `v0.3.3` to `v0.4.0`.
+
+<details open markdown="block">
+  <summary>
+    Table of contents
+  </summary>
+  {: .text-delta }
+- TOC
+{:toc}
+</details>
+
+{::options toc_levels="2..4" /}
+
+{: .warning }
+> If your configuration states `remote_theme: just-the-docs/just-the-docs`, your
+> website is built using the current `main` branch of the theme, which may include
+> changes made after the latest release; see the [CHANGELOG].
+>
+> If your configuration states `theme: just_the_docs` and your `Gemfile` specifies
+> `gem "just-the-docs"`, your website is always built using the latest release.
+
+{: .note }
+> If you have cloned/forked and customised the theme repo,
+> and pull the changes of a new release to your clone,
+> you may need to resolve merge conflicts.
+
+[CHANGELOG]: {{ site.baseurl }}{% link CHANGELOG.md %}
+
+## v0.6.x - v0.7.0
+
+### POTENTIALLY-BREAKING CHANGES in v0.7.0
+
+There are some *very minor* potentially-breaking changes for users in version `v0.7.0`. **They do not affect the vast majority of users**; however, this may affect users of (undocumented) internal theme structure. They concern:
+
+1. the movement of `_includes/nav.html`, which has moved to `_includes/components/nav.html`
+  - **explicit migration only necessary if users have overridden `_includes/nav.html`**
+2. the addition of `<script>` tags with `id`s `jtd-nav-activation` and `jtd-head-nav-stylesheet`
+  - **explicit migration only necessary if users have existing elements with those IDs**
+
+#### Moved Include
+
+Version `v0.7.0` has moved (and changed the contents of) `_includes/nav.html`; it is now in `_includes/components/nav.html`. This means that user overrides for the component will *no longer be loaded*, reverting to the Just the Docs default.
+
+Users who have overridden this `_includes` should:
+
+1. copy in the new upstream `_includes/components/nav.html` into their site
+2. port over any changes from their custom `_includes/nav.html`
+
+No other changes are necessary.
+
+#### New Script IDs
+
+Version `v0.7.0` adds the `id`s `jtd-nav-activation` and `jtd-head-nav-stylesheet` to some existing script tags. This will cause errors for users that have their own custom components with those IDs.
+
+Users who have elements with those `id`s should rename their elements to avoid a collision.
+
+## v0.5.x - v0.6.0
+
+### POTENTIALLY-BREAKING CHANGES in v0.6.0
+
+There are some *very minor* potentially-breaking changes for users in version `v0.6.0`. **They do not affect the vast majority of users**; however, this may affect users of (undocumented) internal theme structure. They concern:
+
+1. the addition of new `_includes/favicon.html`, `_includes/head_nav.html`, and `_includes/css/activation.scss.liquid`
+  - **explicit migration only necessary if users have defined a custom file with the same name**
+2. removing `id="main-content-wrap` from wrapper `div` elements in default layouts
+  - **explicit migration only necessary if users have written code that depends on `#main-content-wrap`**
+3. loading the new `$color-scheme` variable (from the light scheme by default)
+  - **explicit migration only necessary if users have overridden the base light theme**
+4. caching the favicon for the entire site
+  - **explicit migration only necessary if users have different favicons for different pages**
+
+#### New Includes
+
+Version `v0.6.0` introduces three new `_includes` files:
+
+- `_includes/favicon.html`, which now contains logic previously in `_includes/head.html`: loading `favicon.ico` if no favicon is specified
+- `_includes/head_nav.html`, which generates CSS used for the new efficient navigation implementation
+- `_includes/css/activation.scss.liquid`, which is used by `head_nav` for navigation implementation
+
+If users have existing `_includes` files with this name, they should be renamed (and imported with their new name) prior to upgrading to `0.6.0`. No other change is necessary.
+
+#### Removed `#main-content-wrap`
+
+In `_layouts/default.html` and `_layouts/minimal.html`, the `id="main-content-wrap"` has been removed from the wrapper div (in part due to a bug with multiple `id`s on one element). Internally, our theme *does not use* these `id`s; for most users, this does not require any action.
+
+However, code that relies on this `id` must be changed. Each of the related elements still has the unique class `.main-content-wrap`, and can be selected with this class. For example, in CSS:
+
+```css
+/* OLD */
+#main-content-wrap { /* ... */ }
+
+/* NEW */
+.main-content-wrap { /* ... */ }
+```
+
+Or in JS:
+
+```js
+// OLD
+document.getElementById("main-content-wrap");
+
+// NEW
+document.getElementsByClassName("main-content-wrap")[0];
+```
+
+#### New `$color-scheme` variable
+
+The theme now properly sets the `color-scheme` property. To do so, the new `$color-scheme` SCSS variable has been created. The variable has been added to the default `light` scheme, which is *always* loaded by Just the Docs.
+
+Migration is only needed if:
+
+- the packaged `light` scheme has been *overridden* (this is *not* the same as using a custom scheme)
+- or, the scheme logic to always load `light` has been changed
+
+(neither of these behaviours are recommended by Just the Docs)
+
+In either of these cases, users should add a `$color-scheme` SCSS variable to their active scheme with the appropriate value (see: [MDN docs on `color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme)).
+
+```scss
+$color-scheme: light !default;
+```
+
+#### Cached favicon
+
+Version `v0.6.0` adds a new `_include` that caches the favicon for the entire site. This significantly improves page build times for large sites.
+
+However, some users may load different favicons for each page (and/or dynamically change the first favicon load). In this case, they should override the logic in `_includes/favicon.html` by **replacing** it with an empty file (this is *different* from deleting it). No further migration is necessary.
+
+## v0.4.x - v0.5.0
+
+### POTENTIALLY-BREAKING CHANGES in v0.5.0
+
+There is one potentially-breaking change for users migrating from `v0.4.2` to `v0.5.0` concerning `setup.scss`. To provide context:
+
+1. `setup.scss` was introduced in `v0.4.0`
+2. in `v0.4.0` and `v0.4.1`, `setup.scss` was imported *before* color scheme SCSS code
+3. in `v0.4.2`, we adjusted the order to import `setup.scss` *after* color scheme SCSS code
+4. in `v0.5.0`, we have reverted the previous change: `setup.scss` is now again imported *before* color scheme SCSS code
+
+This does not affect most users. Users who did not migrate to `v0.4.2` or who do not have a custom `setup.scss` are guaranteed no breaking changes.
+
+Explicit migration steps are only needed if:
+
+1. a custom `setup.scss` has been defined,
+2. **and** the `setup.scss` depends on variables or functions defined in color scheme SCSS code; this change was only possible on `v0.4.2`
+
+For those users, we suggest moving those variables and functions to each relevant color scheme.
+## v0.3.3 … v0.4.x
+
+### REPOSITORY CHANGES
+
+#### Just the Docs
+
+The theme repo is now at <https://github.com/just-the-docs/just-the-docs>.
+The name of its default branch is now `main`.
+
+The theme docs website is now published at <https://just-the-docs.github.io/just-the-docs>. We've also retroactively published the theme docs website for version `v0.3.3` at <https://v0-3-3-docs.just-the-docs.com/>.
+
+GitHub provides access to previous versions of the theme repo.
+You can browse [previous versions of the theme docs website] on the [Internet Archive].
+
+[previous versions of the theme docs website]: https://web.archive.org/web/20220000000000*/https://just-the-docs.github.io/just-the-docs
+[Internet Archive]: https://web.archive.org/
+
+The [README] page on the theme repo repeats much of the information from the [home page],
+formatted for browsing on GitHub.
+It also explains how to install the theme as a Ruby Gem, without creating a new site.
+
+[README]: https://github.com/just-the-docs/just-the-docs/blob/main/README.md
+[home page]: https://just-the-docs.com
+
+#### Deploy previews
+
+When a PR builds successfully, Netlify provides a preview of how the theme docs website will look if the PR is merged.
+You can find links to the preview near the bottom of the Conversation tab of the PR.
+
+#### Just the Docs Template
+
+The template at <https://github.com/just-the-docs/just-the-docs-template>
+creates a repo with the minimal source files for a Just the Docs website.
+After configuring the relevant parameters, you can build and serve the website
+both locally and on GitHub Pages – using either Jekyll 3 or Jekyll 4!
+
+#### Just the Docs Tests
+
+The tests website at <https://just-the-docs.github.io/just-the-docs-tests>
+consists mainly of regression tests for bug fixes and new features.
+
+The test source files at <https://github.com/just-the-docs/just-the-docs-tests>
+illustrate the use of many Markdown and Jekyll features,
+including some that are not included in the theme docs.
+
+For example, see how to add support for rendering TeX/LaTeX [math formulas] with KaTeX and MathJax.
+
+[math formulas]: https://just-the-docs.github.io/just-the-docs-tests/components/math/index/
+
+### POTENTIALLY-BREAKING CHANGES in v0.4.0
+
+If switching to a new release of the theme breaks your website,
+check that you don't have any files in the `_includes`, `_layouts`, and `_sass`
+directories with the same names as files provided by the theme.
+
+If your repo has a customised copy of `_layouts/default.html` from a previous release,
+try removing it, or replace it by a fresh copy of the theme file.
+
+{: .warning }
+The following changes made in v0.4.0 *might* break or adversely affect your website
+when you next rebuild it, unless you have pinned it!
+
+#### New includes and SCSS
+
+Version 0.4.0 introduces many new `_includes` files. If you already have an existing include with the same name as a new addition, you will need to migrate or update that include. The new files are (relative to the `_includes` folder):
+
+- `mermaid_config.js`
+- `nav_footer_custom`
+- `search_placeholder_custom`
+- `toc_heading_custom`
+- the entire `components/` folder:
+  - `aux_nav`, `breadcrumbs`, `children_nav`, `footer`, `header`, `mermaid`, `search_footer`, `search_header`, `sidebar`
+- the entire `icons/` folder
+  - `code_copy`, `document`, `expand`, `external_link`, `icons`, `link`, `menu`, `search`
+- the entire `lunr/` folder
+  - `custom-data.json`, `custom-index.js`
+
+We have removed some code in `_sass/vendor` and added a new file at `_sass/custom/setup.scss`.
+
+#### favicons
+
+The file `_includes/favicon.html` is now ignored by the theme.
+If you're using it, your website's favicon is no longer displayed by browsers.
+
+To fix: Move the content of `_includes/favicon.html` to `_includes/head_custom.html`.
+
+#### Custom callout colors
+
+The file `_sass/custom/custom.scss` is now imported last: _after_ the configuration of callouts.
+If you've defined custom color variables for callouts in `_sass/custom/custom.scss`
+(and used them when configuring your callouts in `_config.yml`)
+you will not be able to rebuild your website.
+
+To fix: Move custom color variables for callouts in `_sass/custom/custom.scss` to `_sass/custom/variables.scss`.
+
+#### Pages and collections
+
+Links to ordinary pages now appear in the navigation on sites that use collections.
+You might want the navigation of your site to consist entirely of collections.
+
+To fix: Add the front matter `nav_exclude: true` to pages that the navigation should not display.
+
+#### Relative URLs
+
+All generated URLs are now relative.
+This is a bug fix, and unlikely to break any site.
+
+Relative links to pages within a website support deployment to different servers.
+
+#### Navigation order
+
+The order in which the navigation panel lists pages has been simplified.
+All pages with `nav_order` values now come before all pages that are ordered by `title`.
+
+If your website has a group of *sibling* pages where some siblings have `nav_order`
+string values, and others are ordered by numerical `title` values,
+the former now come before the latter.
+
+To fix: Add numerical `nav_order` values to the pages with numerical `title` values.
+
+### DEPRECATIONS
+
+{: .warning }
+The following features are deprecated, and to be removed in a future release.
+
+#### Jekyll 3
+
+You can still use Jekyll 3 (3.8.5 or later) to build websites using v0.4.0 of the theme.
+However, future releases of the theme may require the use of Jekyll 4.
+
+You can already use Jekyll 4 to build your website *locally*.
+It should look exactly the same as when built with Jekyll 3.[^Jekyll4]
+
+[^Jekyll4]:
+    Jekyll 4 depends on more recent versions of other gems than Jekyll 3,
+    and the differences between those versions may affect the files of your built site.
+
+To use Jekyll 4 when building your website *on GitHub Pages*, you need to run GitHub Actions.
+The simplest way of setting that up in a new repo is to create the repo using the Just the Docs template.
+To start running Jekyll 4 to build an existing repo on GitHub Pages,
+you can create a new repo with the template, then copy its `.github/workflows` directory,
+and update your repo settings to use Actions.
+
+#### Footer content configuration
+
+Currently, if your configuration sets `footer_content` to some text,
+the theme displays that text at the bottom of the main section of each page.
+
+The file `_includes/footer_custom.html` provides a more general way of customizing
+not only the text but also the markup for the page footer area.
+
+You can replicate the current display of `TEXT` in the footer using the following markup:
+
+```html
+<p class="text-small text-grey-dk-100 mb-0">TEXT</p>
+```
+
+### THEME WEBSITE CHANGES
+
+The website now uses *callouts*[^callouts] to draw attention to important information.
+
+[^callouts]:
+    The theme website configuration defines the callout titles and colors used there.
+    Websites that use the theme have to configure their own callout titles and colors.
+
+The theme uses [semantic versioning].
+A normal version number takes the form X.Y.Z,
+where X is the major version, Y is the minor version, and Z is the patch version.
+The theme uses version X.Y.Z.rcN for pre-release N of version X.Y.Z.
+When referring to version numbers on GitHub, we usually prefix them by 'v'.
+
+[semantic versioning]: https://semver.org
+
+Major version zero (0.Y.Z) is for initial development, where anything *may* change at any time.
+In practice, we increment the patch version Z for bug fixes and backwards compatible changes;
+we increment the minor version Y for changes that could break websites using the theme
+without pinning it to a specific version.
+
+The label `NEW` in the theme website indicates a feature that has been changed or added
+since the release of the previous *minor* version.
+For example, after the release of v0.4.Z, the theme website should label `NEW` all features that
+we have changed or added since v0.3.0 – not just since v0.3.3.
+When we release v0.5.0, we will remove all those labels, and add labels on features since v0.4.0.
+
+The theme docs website is not itself versioned.
+It changes incrementally, independently of theme releases.
+
+#### Home page
+
+The theme home page now focuses on the simplest ways of using the theme.
+It also notes the different behaviour of `theme` and `remote_theme` in connection
+with interim versions of the theme, such as pre-releases.
+
+#### CHANGELOG
+
+The CHANGELOG page lists the changes made in all previous releases and pre-releases of new versions of the theme gem.
+
+It also lists changes made to the `main` branch of the theme since the latest release or pre-release.
+
+For changes since v0.3.3, the log usually references the merged PR that made the change and its author.
+
+### NON-BREAKING CHANGES (OUTLINE ONLY)
+
+#### Accessibility
+
+- Skip to main content: the first keyboard-navigatable item is now a link to skip over the sidebar and header to the main content of the page. PR: [#949].
+- Aria-labels: improved `aria-label`s have been added to various site elements. PRs: [#950], ...
+- Other general improvements: gradual changes have improved tab focusability, contrast, and semantic elements. More work still to come. PRs: [#498], [#846]
+
+#### 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.
+- Multiple Google Analytics tags are now supported. PR: [#1029]
+
+#### Customization
+
+- all user-facing text is now customizable; previously, several elements (ex search placeholder) were hardwired into the theme. Now, users can blend custom includes and layouts to internationalize their sites.
+- we've clarified the role of `custom.scss` to be imported last; to allow users to define custom or override variables, we've added a new file `setup.scss`. PR: [#1135]
+
+#### Custom Includes
+
+We've added several custom `_includes` to provide users with more customization options for different site elements. We've also added a section to [Configuration]({% link docs/customization.md %}#override-includes) to outline these.
+
+All of these are opt-in by default; however, **these may be breaking if you have existing `_includes` with the same name**.
+
+Each item is listed with the relevant file and PR.
+
+- TOC heading: `toc_heading_custom.html`, PR: [#980]
+- Navigation panel footer: `nav_footer_custom.html`, PR: [#474]
+- Search placeholder: `search_placeholder_custom.html`, PR: [#613]
+- Modular site components: `components/` and `icons/`, PR: [#1058]
+- Custom search indices: `lunr/`, PR: [#1068]
+
+In a future (version 1) release, we may rename the custom include files.
+
+#### Modular Components
+
+We've broken up the default layout (`_layouts/default.html`) into multiple reusable components. This should have no impact on most users; however, it should make it easier to implement custom layouts.
+
+For more, see [Custom layouts and includes]({% link docs/customization.md %}#custom-layouts-and-includes). PR: [#1058].
+
+#### Navigation
+
+- Collections: nav panel shows links to ordinary pages before collections
+- Collection folding; part of "Combination". PR: [#578]
+- Scrolling to show link to selected page. PR: [#639]
+- External nav links are now supported. PR: [#876]
+- Child nav order: sort navigation pages with `child_nav_order`. PR: [#726]
+- Order when mixing different ways of specifying nav order
+
+#### Search
+
+In addition to customizing the search placeholder, we've also added the ability to provide custom content to the search index. for more, see [Custom content for search index]({% link docs/search.md %}#custom-content-for-search-index). PR: [#1068].
+
+#### Styling
+
+- Code copying: code blocks now allow users to easily copy their contents. PR: [#945]
+- Blockquote: shows vertical bar on left. PR: [#965]
+- Links wrap. PR: [#905]
+- Callouts: a new component similar to alerts or banners. See [UI Components - Callouts]({% link docs/ui-components/callouts.md %}). PR: [#466]
+
+----
+
+[#856]: https://github.com/just-the-docs/just-the-docs/pull/856
+[#806]: https://github.com/just-the-docs/just-the-docs/pull/806
+[#555]: https://github.com/just-the-docs/just-the-docs/pull/555
+[#814]: https://github.com/just-the-docs/just-the-docs/pull/814
+[#778]: https://github.com/just-the-docs/just-the-docs/pull/778
+[#221]: https://github.com/just-the-docs/just-the-docs/pull/221
+[#782]: https://github.com/just-the-docs/just-the-docs/pull/782
+[#549]: https://github.com/just-the-docs/just-the-docs/pull/549
+[#554]: https://github.com/just-the-docs/just-the-docs/pull/554
+[#499]: https://github.com/just-the-docs/just-the-docs/pull/499
+[#473]: https://github.com/just-the-docs/just-the-docs/pull/473
+[#835]: https://github.com/just-the-docs/just-the-docs/pull/835
+[#891]: https://github.com/just-the-docs/just-the-docs/pull/891
+[#906]: https://github.com/just-the-docs/just-the-docs/pull/906
+
+[#578]: https://github.com/just-the-docs/just-the-docs/pull/578
+[#463]: https://github.com/just-the-docs/just-the-docs/pull/463
+[#448]: https://github.com/just-the-docs/just-the-docs/pull/448
+[#466]: https://github.com/just-the-docs/just-the-docs/pull/466
+[#477]: https://github.com/just-the-docs/just-the-docs/pull/477
+[#495]: https://github.com/just-the-docs/just-the-docs/pull/495
+[#496]: https://github.com/just-the-docs/just-the-docs/pull/496
+[#498]: https://github.com/just-the-docs/just-the-docs/pull/498
+[#494]: https://github.com/just-the-docs/just-the-docs/pull/494
+[#639]: https://github.com/just-the-docs/just-the-docs/pull/639
+[#544]: https://github.com/just-the-docs/just-the-docs/pull/544
+[#364]: https://github.com/just-the-docs/just-the-docs/pull/364
+[#498]: https://github.com/just-the-docs/just-the-docs/pull/498
+[#613]: https://github.com/just-the-docs/just-the-docs/pull/613
+[#726]: https://github.com/just-the-docs/just-the-docs/pull/726
+[#474]: https://github.com/just-the-docs/just-the-docs/pull/474
+[#829]: https://github.com/just-the-docs/just-the-docs/pull/829
+[#857]: https://github.com/just-the-docs/just-the-docs/pull/857
+[#876]: https://github.com/just-the-docs/just-the-docs/pull/876
+[#909]: https://github.com/just-the-docs/just-the-docs/pull/909
+[#519]: https://github.com/just-the-docs/just-the-docs/pull/519
+[#855]: https://github.com/just-the-docs/just-the-docs/pull/855
+[#686]: https://github.com/just-the-docs/just-the-docs/pull/686
+[#495]: https://github.com/just-the-docs/just-the-docs/pull/495
+[#846]: https://github.com/just-the-docs/just-the-docs/pull/846
+[#727]: https://github.com/just-the-docs/just-the-docs/pull/727
+[#889]: https://github.com/just-the-docs/just-the-docs/pull/889
+[#893]: https://github.com/just-the-docs/just-the-docs/pull/893
+[#905]: https://github.com/just-the-docs/just-the-docs/pull/905
+[#898]: https://github.com/just-the-docs/just-the-docs/pull/898
+
+[#950]: https://github.com/just-the-docs/just-the-docs/pull/950
+[#944]: https://github.com/just-the-docs/just-the-docs/pull/944
+[#939]: https://github.com/just-the-docs/just-the-docs/pull/939
+[#949]: https://github.com/just-the-docs/just-the-docs/pull/949
+[#941]: https://github.com/just-the-docs/just-the-docs/pull/941
+[#956]: https://github.com/just-the-docs/just-the-docs/pull/956
+[#935]: https://github.com/just-the-docs/just-the-docs/pull/935
+[#940]: https://github.com/just-the-docs/just-the-docs/pull/940
+[#951]: https://github.com/just-the-docs/just-the-docs/pull/951
+[#955]: https://github.com/just-the-docs/just-the-docs/pull/955
+[#937]: https://github.com/just-the-docs/just-the-docs/pull/937
+
+[#965]: https://github.com/just-the-docs/just-the-docs/pull/965
+[#960]: https://github.com/just-the-docs/just-the-docs/pull/960
+[#962]: https://github.com/just-the-docs/just-the-docs/pull/962
+[#964]: https://github.com/just-the-docs/just-the-docs/pull/964
+[#967]: https://github.com/just-the-docs/just-the-docs/pull/967
+[#974]: https://github.com/just-the-docs/just-the-docs/pull/974
+[#980]: https://github.com/just-the-docs/just-the-docs/pull/980
+[#985]: https://github.com/just-the-docs/just-the-docs/pull/985
+[#986]: https://github.com/just-the-docs/just-the-docs/pull/986
+[#992]: https://github.com/just-the-docs/just-the-docs/pull/992
+
+[#945]: https://github.com/just-the-docs/just-the-docs/pull/945
+[#999]: https://github.com/just-the-docs/just-the-docs/pull/999
+[#1000]: https://github.com/just-the-docs/just-the-docs/pull/1000
+[#1001]: https://github.com/just-the-docs/just-the-docs/pull/1001
+[#1010]: https://github.com/just-the-docs/just-the-docs/pull/1010
+[#1015]: https://github.com/just-the-docs/just-the-docs/pull/1015
+[#1018]: https://github.com/just-the-docs/just-the-docs/pull/1018
+[#1019]: https://github.com/just-the-docs/just-the-docs/pull/1019
+[#1021]: https://github.com/just-the-docs/just-the-docs/pull/1021
+[#1027]: https://github.com/just-the-docs/just-the-docs/pull/1027
+[#1029]: https://github.com/just-the-docs/just-the-docs/pull/1029
+[#1040]: https://github.com/just-the-docs/just-the-docs/pull/1040
+[#1061]: https://github.com/just-the-docs/just-the-docs/pull/1061
+[#1065]: https://github.com/just-the-docs/just-the-docs/pull/1065
+[#1071]: https://github.com/just-the-docs/just-the-docs/pull/1071
+[#1074]: https://github.com/just-the-docs/just-the-docs/pull/1074
+[#1076]: https://github.com/just-the-docs/just-the-docs/pull/1076
+[#1077]: https://github.com/just-the-docs/just-the-docs/pull/1077
+[#1090]: https://github.com/just-the-docs/just-the-docs/pull/1090
+[#1091]: https://github.com/just-the-docs/just-the-docs/pull/1091
+[#1092]: https://github.com/just-the-docs/just-the-docs/pull/1092
+[#1095]: https://github.com/just-the-docs/just-the-docs/pull/1095
+
+[#1068]: https://github.com/just-the-docs/just-the-docs/pull/1068
+[#1135]: https://github.com/just-the-docs/just-the-docs/pull/1135

README.md

@@ -5,26 +5,38 @@
 <p align="center">
     <h1 align="center">Just the Docs</h1>
     <p align="center">A modern, highly customizable, and responsive Jekyll theme for documentation with built-in search.<br>Easily hosted on GitHub Pages with few dependencies.</p>
-    <p align="center"><strong><a href="https://just-the-docs.github.io/just-the-docs/">See it in action!</a></strong></p>
+    <p align="center"><strong><a href="https://just-the-docs.com/">See it in action!</a></strong></p>
     <br><br><br>
 </p>
 
-![jtd](https://user-images.githubusercontent.com/896475/47384541-89053c80-d6d5-11e8-98dc-dba16e192de9.gif)
+<p align="center">A video walkthrough of various Just the Docs features</p>
+
+https://user-images.githubusercontent.com/85418632/211225192-7e5d1116-2f4f-4305-bb9b-437fe47df071.mp4
 
 ## Installation
 
-### via GitHub Pages remote theme
+### Use the template
 
-The quickiest way to use Just The Docs is to use GitHub pages [remote theme](https://blog.github.com/2017-11-29-use-any-theme-with-github-pages/) feature in your `_config.yml` file:
+The [Just the Docs Template] provides the simplest, quickest, and easiest way to create a new website that uses the Just the Docs theme. To get started with creating a site, just click "[use the template]"!
 
-```yaml
+Note: To use the theme, you do ***not*** need to clone or fork the [Just the Docs repo]! You should do that only if you intend to browse the theme docs locally, contribute to the development of the theme, or develop a new theme based on Just the Docs.
-remote_theme: just-the-docs/just-the-docs
-```
-### via RubyGems:
 
-Alternatively you can install it as a Ruby Gem.
+You can easily set the site created by the template to be published on [GitHub Pages] – the [template README] file explains how to do that, along with other details.
 
-Add this line to your Jekyll site's Gemfile:
+If [Jekyll] is installed on your computer, you can also build and preview the created site *locally*. This lets you test changes before committing them, and avoids waiting for GitHub Pages.[^2] And you will be able to deploy your local build to a different platform than GitHub Pages.
+
+More specifically, the created site:
+
+- uses a gem-based approach, i.e. uses a `Gemfile` and loads the `just-the-docs` gem
+- uses the [GitHub Pages / Actions workflow] to build and publish the site on GitHub Pages
+
+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
+
+Alternatively, you can install the theme as a Ruby Gem, without creating a new site.
+
+Add this line to your Jekyll site's `Gemfile`:
 
 ```ruby
 gem "just-the-docs"
@@ -50,18 +62,20 @@ Alternatively, you can run it inside Docker while developing your site
 
 ## Usage
 
-[View the documentation](https://just-the-docs.github.io/just-the-docs/) for usage information.
+[View the documentation][Just the Docs] for usage information.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/just-the-docs/just-the-docs. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports, proposals of new features, and pull requests are welcome on GitHub at https://github.com/just-the-docs/just-the-docs. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ### Submitting code changes:
 
+- Submit an [Issue](https://github.com/just-the-docs/just-the-docs/issues) that motivates the changes, using the appropriate template
+- Discuss the proposed changes with other users and the maintainers
 - Open a [Pull Request](https://github.com/just-the-docs/just-the-docs/pulls)
 - Ensure all CI tests pass
+- Provide instructions to check the effect of the changes
 - Await code review
-- Bump the version number in `just-the-docs.gemspec` and `package.json` according to [semantic versioning](https://semver.org/).
 
 ### Design and development principles of this theme:
 
@@ -72,14 +86,25 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/just-t
 
 ## Development
 
-To set up your environment to develop this theme, run `bundle install`.
+To set up your environment to develop this theme: fork this repo, the run `bundle install` from the root directory.
 
 A modern [devcontainer configuration](https://code.visualstudio.com/docs/remote/containers) for VSCode is included.
 
 Your theme is set up just like a normal Jekyll site! To test your theme, run `bundle exec jekyll serve` and open your browser at `http://localhost:4000`. This starts a Jekyll server using your theme. Add pages, documents, data, etc. like normal to test your theme's contents. As you make modifications to your theme and to your content, your site will regenerate and you should see the changes in the browser after a refresh, just like normal.
 
-When the theme is released, only the files in `_layouts`, `_includes`, and `_sass` tracked with Git will be released.
+When this theme is released, only the files in `_layouts`, `_includes`, and `_sass` tracked with Git will be included in the gem.
 
 ## License
 
 The theme is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+[^2]: [It can take up to 10 minutes for changes to your site to publish after you push the changes to GitHub](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll#creating-your-site).
+
+[Jekyll]: https://jekyllrb.com
+[Just the Docs Template]: https://just-the-docs.github.io/just-the-docs-template/
+[Just the Docs]: https://just-the-docs.com
+[Just the Docs repo]: https://github.com/just-the-docs/just-the-docs
+[GitHub Pages]: https://pages.github.com/
+[Template README]: https://github.com/just-the-docs/just-the-docs-template/blob/main/README.md
+[GitHub Pages / Actions workflow]: https://github.blog/changelog/2022-07-27-github-pages-custom-github-actions-workflows-beta/
+[use the template]: https://github.com/just-the-docs/just-the-docs-template/generate

_config.yml

@@ -15,11 +15,39 @@
 # in the templates via {{ site.myvariable }}.
 title: Just the Docs
 description: A Jekyll theme for documentation
-baseurl: "/just-the-docs" # the subpath of your site, e.g. /blog
+baseurl: "" # the subpath of your site, e.g. /blog
-url: "https://just-the-docs.github.io" # the base hostname & protocol for your site, e.g. http://example.com
+url: "https://just-the-docs.com" # the base hostname & protocol for your site, e.g. http://example.com
+repository: just-the-docs/just-the-docs # for github-metadata
 
 permalink: pretty
-exclude: ["node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json",  "script/", "LICENSE.txt", "lib/", "bin/", "README.md", "Rakefile"]
+
+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/
 
 # Set a path/url to a logo that will be displayed instead of the title
 #logo: "/assets/images/just-the-docs.png"
@@ -50,15 +78,25 @@ search:
   # Enable or disable the search button that appears in the bottom right corner of every page
   # Supports true or false (default)
   button: false
+  # Focus the search input by pressing `ctrl + focus_shortcut_key` (or `cmd + focus_shortcut_key` on macOS)
+  focus_shortcut_key: 'k'
 
-# To enable support for mermaid diagrams (https://mermaid-js.github.io/mermaid/),
+# For copy button on code
-# uncomment the `mermaid` and `version` keys below
+enable_copy_code_button: true
-# mermaid:
+
-#   # Version of mermaid library
+# By default, consuming the theme as a gem leaves mermaid disabled; it is opt-in
-#   # Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/
+mermaid:
-#   version: "9.1.3"
+  # Version of mermaid library
-#   # Put any additional configuration, such as setting the theme, in _includes/mermaid_config.js
+  # Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/
-#   # See also docs/ui-components/code
+  version: "9.1.6"
+  # Put any additional configuration, such as setting the theme, in _includes/mermaid_config.js
+  # See also docs/ui-components/code
+  # To load mermaid from a local library, also use the `path` key to specify the location of the library; e.g.
+  # for (v10+):
+  # path: "/assets/js/mermaid.esm.min.mjs"
+  # for (<v10):
+  # path: "/assets/js/mermaid.min.js"
+  # Note: copy both `mermaid.esm.min.mjs` (v10+) or `mermaid.min.js` (<v10) and the associated `.map` file from the specified version of `mermaid/dist` to `/assets/js/`.
 
 # Enable or disable heading anchors
 heading_anchors: true
@@ -66,7 +104,7 @@ heading_anchors: true
 # Aux links for the upper right navigation
 aux_links:
   "Just the Docs on GitHub":
-    - "//github.com/just-the-docs/just-the-docs"
+    - "https://github.com/just-the-docs/just-the-docs"
 
 # Makes Aux links open in a new tab. Default is false
 aux_links_new_tab: false
@@ -106,13 +144,33 @@ gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into t
 # Color scheme currently only supports "dark", "light"/nil (default), or a custom scheme that you define
 color_scheme: nil
 
+callouts_level: quiet # or loud
+callouts:
+  highlight:
+    color: yellow
+  important:
+    title: Important
+    color: blue
+  new:
+    title: New
+    color: green
+  note:
+    title: Note
+    color: purple
+  warning:
+    title: Warning
+    color: red
+
 # Google Analytics Tracking (optional)
-# e.g, UA-1234567-89
+# Supports a CSV of tracking ID strings (eg. "UA-1234567-89,G-1AB234CDE5")
-ga_tracking: UA-2709176-10
+# Note: the main Just the Docs site does *not* use Google Analytics.
-ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true/nil by default)
+# ga_tracking: UA-2709176-10,G-5FG1HLH3XQ
+# ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true/nil by default)
 
 plugins:
   - jekyll-seo-tag
+  - jekyll-github-metadata
+  - jekyll-include-cache
 
 kramdown:
   syntax_highlighter_opts:

_includes/components/aux_nav.html

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

_includes/components/breadcrumbs.html

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

_includes/components/children_nav.html

@@ -0,0 +1,33 @@
+{%- comment -%}
+  Include as: {%- include components/children_nav.html -%}
+  Depends on: page, site.
+  Results in: HTML for the children-navigation component.
+  Includes:
+    sorted_pages.html
+    toc_heading_custom.html
+  Overwrites:
+    child_pages.
+{%- endcomment -%}
+
+{%- if page.has_children == true and page.has_toc != false -%}
+  {%- assign child_pages = site[page.collection]
+        | default: site.html_pages
+        | where: "parent", page.title
+        | where: "grand_parent", page.parent -%}
+
+  {%- include sorted_pages.html pages = child_pages -%}
+
+  {%- if page.child_nav_order == 'desc' or page.child_nav_order == 'reversed' -%}
+    {%- assign sorted_pages = sorted_pages | reverse -%}
+  {%- endif -%}
+{%- endif -%}
+
+<hr>
+{% include toc_heading_custom.html %}
+<ul>
+{% for child in sorted_pages %}
+  <li>
+    <a href="{{ child.url | relative_url }}">{{ child.title }}</a>{% if child.summary %} - {{ child.summary }}{% endif %}
+  </li>
+{% endfor %}
+</ul>

_includes/components/footer.html

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

_includes/components/header.html

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

_includes/components/mermaid.html

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

_includes/components/nav.html

@@ -0,0 +1,75 @@
+{%- 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/search_footer.html

@@ -0,0 +1,7 @@
+{% if site.search.button %}
+<button id="search-button" class="search-button btn-reset" aria-label="Focus on search">
+  <svg viewBox="0 0 24 24" class="icon" aria-hidden="true"><use xlink:href="#svg-search"></use></svg>
+</button>
+{% endif %}
+
+<div class="search-overlay"></div>

_includes/components/search_header.html

@@ -0,0 +1,9 @@
+{% capture search_placeholder %}{% include search_placeholder_custom.html %}{% endcapture %}
+
+<div class="search" role="search">
+  <div class="search-input-wrap">
+    <input type="text" id="search-input" class="search-input" tabindex="0" placeholder="{{ search_placeholder | strip_html | strip }}" aria-label="{{ search_placeholder | strip_html| strip }}" autocomplete="off">
+    <label for="search-input" class="search-label"><svg viewBox="0 0 24 24" class="search-icon"><use xlink:href="#svg-search"></use></svg></label>
+  </div>
+  <div id="search-results" class="search-results"></div>
+</div>

_includes/components/sidebar.html

@@ -0,0 +1,32 @@
+{%- comment -%}
+  Include as: {%- include components/sidebar.html -%}
+  Depends on: page(?), site.
+  Results in: HTML for the side bar.
+  Includes:
+    title.html, components/site_nav.html, nav_footer_custom.html
+  Overwrites:
+    nav_footer_custom.
+  Should not be cached, because nav_footer_custom.html might depend on page.
+{%- endcomment -%}
+
+<div class="side-bar">
+  <div class="site-header" role="banner">
+    <a href="{{ '/' | relative_url }}" class="site-title lh-tight">{% include title.html %}</a>
+    <button id="menu-button" class="site-button btn-reset" aria-label="Toggle menu" aria-pressed="false">
+      <svg viewBox="0 0 24 24" class="icon" aria-hidden="true"><use xlink:href="#svg-menu"></use></svg>
+    </button>
+  </div>
+
+  {% include_cached components/site_nav.html %}
+
+  {% capture nav_footer_custom %}
+    {%- include nav_footer_custom.html -%}
+  {% endcapture %}
+  {% if nav_footer_custom != "" %}
+    {{ nav_footer_custom }}
+  {% else %}
+    <footer class="site-footer">
+      This site uses <a href="https://github.com/just-the-docs/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll.
+    </footer>
+  {% endif %}
+</div>

_includes/components/site_nav.html

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

_includes/css/activation.scss.liquid

@@ -0,0 +1,332 @@
+{%- comment -%}
+  Include as: {%- include css/activation.scss.liquid -%}
+  Depends on: page.
+  Results in: page-dependent CSS rules for inclusion in a style element,
+    which needs to be disabled when JS is enabled.
+  Includes: components/site_nav.html.
+  Overwrites: 
+    activation_no_nav_link, nav_list_link, site_nav,
+    nav_list, nav_list_end, nav_list_item, nav_category_list,
+    nav_list_link_prefix, nav_splits, nav_split, nav_levels,
+    nav_list_less, nav_list_count, nav_end_less, nav_end_count,
+    nav_index, nav_slice_size,
+    activation_collection_prefix, activation_other_collection_prefix.
+  Should not be cached, because it depends on page.
+{%- endcomment -%}
+
+{%- comment -%}
+  The CSS rules in activation_no_nav_link are for use on pages excluded from the main navigation.
+  - The first rule ensures that no nav-link has a background image.
+  - The other two rules ensure that all folding collections are expanded.
+{%- endcomment -%}
+
+{%- capture activation_no_nav_link %}
+.site-nav ul li a {
+  background-image: none;
+}
+
+{%- if site.just_the_docs.collections %}
+.site-nav > ul.nav-category-list > li > button svg {
+  transform: rotate(-90deg);
+}
+.site-nav > ul.nav-category-list > li.nav-list-item > ul.nav-list {
+  display: block;
+}
+{%- endif %}
+{% endcapture -%}
+
+{%- capture nav_list_link -%}
+<a href="{{ page.url | relative_url }}" class="nav-list-link">
+{%- endcapture -%}
+
+{%- capture site_nav -%}
+{%- include_cached components/site_nav.html -%}
+{%- endcapture -%}
+
+{%- if site_nav contains nav_list_link -%}
+
+{%- capture nav_list -%}
+<ul class="nav-list
+{%- endcapture -%}
+
+{%- assign nav_list_end = "</ul>" -%}
+
+{%- capture nav_list_item -%}
+<li class="nav-list-item
+{%- endcapture -%}
+
+{%- capture nav_category_list -%}
+<ul class="nav-list nav-category-list">
+{%- endcapture -%}
+
+{%- assign nav_list_link_prefix =
+      site_nav | split: nav_list_link | first | append: nav_list_link -%}
+
+{%- assign nav_splits =
+      nav_list_link_prefix | split: nav_list_item | pop -%}
+
+{%- assign nav_levels = "" | split: "" | push: 1 -%}
+
+{%- comment -%}
+  The pattern of occurrences of list and list-item tags in the site_nav string
+  is included in the language defined by the following context-free grammar:
+  
+    site_nav = PAGES? EXTERNALS? COLLECTION*
+
+    PAGES = nav_list (nav_list_item PAGES?)+ nav_list_end
+
+    EXTERNALS = nav_list nav_list_item+ nav_list_end
+
+    COLLECTION = nav_list (nav_list_item PAGES?)* nav_list_end
+               | nav_category_list 
+                   nav_list_item nav_list (nav_list_item PAGES?)* nav_list_end
+                 nav_list_end
+  
+  To determine the path in the site_nav to the nav_list_link for the current page,
+  the prefix of nav_list_link in site_nav is split at each nav_list_item to give
+  an array of nav_splits.
+  
+  In site_nav, occurrences of nav_list must be separated by at least one
+  nav_list_item or nav_list_end. Moreover, when a nav_list_end is followed by a
+  nav_list without an intervening nav_list_item, that nav_list must start either
+  a list of external links or a collection. And when a nav_list is followed by a
+  nav_list_end without an intervening nav_list_item, they form an empty collection.
+  
+  nav_levels is the path determined by the previously inspected nav_splits.
+  How many times nav_list and nav_list_end occur in the current nav_split 
+  determines how to update the path.
+  
+  A nav_split can contain any number of empty non-foldable collections.
+  The path element produced by the outer nav_list of a foldable collection is
+  irrelevant; it is set to zero and subsequently removed.
+    
+  The number of occurrences of a string in a nav_split is computed by removing
+  them all, then dividing the resulting size difference by the length of the string.
+  
+  Case analysis on (nav_list_count, nav_list_end_count):
+  
+  - when (0, 0), the nav_split was between two nav_list_items at the same level;
+  
+  - when (0, N+1), all the nav_list_ends in the nav_split are in PAGES or in one
+    COLLECTION;
+    
+  - when (M+1, 0), M must be 0 (because two nav_lists in the same nav_split must
+    be separated by at least one nav_list_end);
+    
+  - when (M+1, N+1), the nav_split must contain either:
+    - the end of PAGES followed by the start of EXTERNALS, or
+    - the end of PAGES followed by the start of a COLLECTION, or
+    - the end of EXTERNALS followed by the start of a COLLECTION, or
+    - the end of one COLLECTION followed by the start of another, or
+    - (in the first nav_split) one or more empty non-foldable COLLECTIONS
+      followed by the start of a COLLECTION.
+    In general, nav_levels[0] here needs to be incremented by nav_list_count.
+    However, a nav_split that contains the end of an empty foldable collection
+    followed by the just the start of a collection has two occurrences of nav_list,
+    and the increment needs to be one less; similarly when the first nav_split
+    starts with an empty non-foldable collection.
+{%- endcomment %}
+
+{%- for nav_split in nav_splits -%}
+
+  {%- assign nav_list_less = nav_split | remove: nav_list -%}
+  {%- assign nav_list_count =
+        nav_split.size | minus: nav_list_less.size | 
+        divided_by: nav_list.size -%}
+
+  {%- assign nav_list_end_less = nav_split | remove: nav_list_end -%}
+  {%- assign nav_list_end_count =
+        nav_split.size | minus: nav_list_end_less.size | 
+        divided_by: nav_list_end.size -%}
+
+  {%- if nav_list_count == 0 and nav_list_end_count == 0 -%}
+
+    {%- assign nav_index = nav_levels[-1] | plus: 1 -%}
+    {%- assign nav_levels = nav_levels | pop | push: nav_index -%}
+
+  {%- elsif nav_list_count == 0 and nav_list_end_count >= 1 -%}
+
+    {%- assign nav_slice_size = nav_levels.size | minus: nav_list_end_count -%}
+    {%- assign nav_levels = nav_levels | slice: 0, nav_slice_size -%}
+    {%- assign nav_index = nav_levels[-1] | plus: 1 -%}
+    {%- assign nav_levels = nav_levels | pop | push: nav_index -%}
+
+  {%- elsif nav_list_count == 1 and nav_list_end_count == 0 -%}
+
+    {%- if nav_split contains nav_category_list -%}
+      {%- assign nav_levels = nav_levels | push: 0 -%}
+    {%- else -%}
+      {%- assign nav_levels = nav_levels | push: 1 -%}
+    {%- endif -%}
+
+  {%- elsif nav_list_count >= 1 and nav_list_end_count >= 1 -%}
+
+    {%- assign nav_index = nav_levels[0] | plus: nav_list_count -%}
+    {%- if nav_levels[-1] == 0 or forloop.first -%}
+      {%- assign nav_index = nav_index | minus: 1 -%}
+    {%- endif -%}
+    {%- assign nav_levels = nav_levels | slice: 0, 0 | push: nav_index -%}
+    {%- if nav_split contains nav_category_list -%}
+      {%- assign nav_levels = nav_levels | push: 0 -%}
+    {%- else -%}
+      {%- assign nav_levels = nav_levels | push: 1 -%}
+    {%- endif -%}
+
+  {%- endif -%}
+
+{%- endfor -%}
+
+{%- assign nav_levels = nav_levels | where_exp: "item", "item >= 1" -%}
+
+{%- endif -%}
+
+{%- comment -%}
+  The generated CSS depends on the position of the current page in each level in
+  the navigation.
+{%- endcomment -%}
+
+{%- if nav_levels[1] == nil -%}
+
+{{ activation_no_nav_link }}
+
+{%- else -%}
+
+{%- if nav_levels[2] == nil and nav_levels[3] -%}
+
+{{ activation_no_nav_link }}
+
+{%- else -%}
+
+{%- comment -%}
+  The site-nav is:
+  - an optional ul.nav-list with li.nav-list-items for non-collection top-level pages
+  - an optional ul.nav-list with li.nav-list-item.externals
+  - any number of just-the-docs.collections
+  
+  A non-foldable collection is:
+  - a div.nav-category with the collection name, followed by:
+  - a ul.nav-list with li.nav-list-items for its top-level pages
+  
+  A foldable collection is:
+  - a ul.nav-list.nav-category-list with a single li.nav-list-item containing:
+    - an optional button with the expander svg
+    - a div.nav-category with the collection name
+    - a ul.nav-list with li.nav-list-items for its top-level pages
+  
+  The generated CSS uses:
+  - activation_collection_prefix, to select the site-nav > ul.nav-list for the page
+  - activation_other_collection_prefix, to select all the other site-nav > ul.nav-lists
+{%- endcomment -%}
+
+{%- if page.collection == nil -%}
+
+  {%- capture activation_collection_prefix -%}
+  .site-nav > ul.nav-list:first-child
+  {%- endcapture -%}
+
+  {%- capture activation_other_collection_prefix -%}
+  .site-nav > ul.nav-list:not(:first-child)
+  {%- endcapture -%}
+
+{%- 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 -%}
+
+{%- endif -%}
+
+{%- comment -%}
+  The required background image of the link to the current page may involve SCSS.
+  To avoid page-dependent SCSS, all nav links initially have that background image.
+  The following rule removes the image from the links to all parents, siblings,
+  and children of the current page.
+{%- endcomment %}
+
+{% if nav_levels[3] -%}
+
+{{ activation_collection_prefix }} > li > a,
+{{ activation_collection_prefix }} > li > ul > li > a,
+{{ activation_collection_prefix }} > li > ul > li > ul > li:not(:nth-child({{ nav_levels[3] }})) > a {
+  background-image: none;
+}
+
+{%- elsif nav_levels[2] -%}
+
+{{ activation_collection_prefix }} > li > a,
+{{ activation_collection_prefix }} > li > ul > li:not(:nth-child({{ nav_levels[2] }})) > a,
+{{ activation_collection_prefix }} > li > ul > li > ul > li > a {
+  background-image: none;
+}
+
+{%- 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;
+}
+
+{%- endif %}
+
+{%- comment -%}
+  The following rule removes the image from the links to pages in other collections.
+{%- endcomment %}
+
+{{ activation_other_collection_prefix }} a,
+.site-nav li.external a {
+  background-image: none;
+}
+
+{%- comment -%}
+  The following rule styles the link to the current page.
+{%- endcomment %}
+
+{{ activation_collection_prefix }} > li:nth-child({{ nav_levels[1] }})
+{%- if nav_levels[2] %} > ul > li:nth-child({{ nav_levels[2] }})
+{%- if nav_levels[3] %} > ul > li:nth-child({{ nav_levels[3] }})
+{%- endif -%}
+{%- endif %} > a {
+  font-weight: 600;
+  text-decoration: none;
+}
+
+{%- comment -%}
+  The following rules unfold all collections, and display the links to any children
+  of the current page.
+  
+  To avoid dependence on the SCSS variable nav-list-expander-right, the direction
+  of the rotation of the expander icon is fixed, and corresponds to the appearance
+  when nav-list-expander-right is true. This results in a minor visual difference
+  between the appearance of active expander icons when JS is enabled/disabled and
+  nav-list-expander-right is false, which seems unavoidable.
+{%- endcomment %}
+
+{%- if site.just_the_docs.collections %}
+.site-nav > ul.nav-category-list > li > button svg,
+{% endif -%}
+{{ activation_collection_prefix }} > li:nth-child({{ nav_levels[1] }}) > button svg
+{%- if nav_levels[2] -%},
+{{ activation_collection_prefix }} > li:nth-child({{ nav_levels[1] }}) > ul > li:nth-child({{ nav_levels[2] }}) > button svg
+{%- endif %} {
+  transform: rotate(-90deg);
+}
+
+{%- if site.just_the_docs.collections %}
+.site-nav > ul.nav-category-list > li.nav-list-item > ul.nav-list,
+{% endif -%}
+{{ activation_collection_prefix }} > li.nav-list-item:nth-child({{ nav_levels[1] }}) > ul.nav-list
+{%- if nav_levels[2] %},
+{{ activation_collection_prefix }} > li.nav-list-item:nth-child({{ nav_levels[1] }}) > ul.nav-list > li.nav-list-item:nth-child({{ nav_levels[2] }}) > ul.nav-list
+{%- endif %} {
+  display: block;
+}
+
+{%- endif -%}
+{%- endif -%}

_includes/css/just-the-docs.scss.liquid

@@ -2,7 +2,11 @@
 $logo: "{{ site.logo | relative_url }}";
 {% endif %}
 @import "./support/support";
+@import "./custom/setup";
+@import "./color_schemes/light";
+{% unless include.color_scheme == "light" %}
 @import "./color_schemes/{{ include.color_scheme }}";
+{% endunless %}
 @import "./modules";
-{% include css/custom.scss.liquid %}
 {% include css/callouts.scss.liquid color_scheme = include.color_scheme %}
+{% include css/custom.scss.liquid %}

_includes/favicon.html

@@ -1 +1,23 @@
-<link rel="shortcut icon" href="{{ 'favicon.ico' | relative_url }}" type="image/x-icon">
+{%- comment -%}
+  Include as: {%- include_cached favicon.html -%}
+  Depends on: site.static_files.
+  Results in: HTML for a link to an existing `favicon.ico` file.
+  Overwrites: 
+    file.
+  
+  The endoflife.date site has 226 pages and 3410 static files. @marcwrobel pointed
+  out that the time taken by evaluating the code in this file on every page when
+  building that site was significant, and suggested making it optional. As it is
+  page-independent, it can easily be cached. Doing that reduced the time taken by
+  rendering `_includes/head.html` from 15.294s to 10.760s, thereby reducing the
+  total build time from 26.074s to 21.656s -- a saving of about 17%.
+{%- endcomment -%}
+
+{% for file in site.static_files %}
+  {% if file.path == site.favicon_ico or file.path == '/favicon.ico' %}
+    {% assign favicon = true %}
+  {% endif %}
+{% endfor %}
+{% if favicon %}
+  <link rel="icon" href="{{ site.favicon_ico | default: '/favicon.ico' | relative_url }}" type="image/x-icon">
+{% endif %}

_includes/fix_linenos.html

@@ -1,18 +1,26 @@
 {%- comment -%}
-This file can be used to fix the HTML produced by Jekyll for highlighted
+This file was previously used to "fix" the HTML produced by Jekyll for
-code with line numbers.
+highlighted code with line numbers. While it often resolves layout issues
+from the missing HTML tags, it still generates invalid HTML (by placing
+a `<table>` element within a `<code>` block). As such, we no longer
+recommend using this workaround. For more information, see the
+"Code snippets with line numbers" docs page:
+https://just-the-docs.com/docs/ui-components/code/line-numbers/
+(or, docs/ui-components/line-nos.md/)
 
-It works with `{% highlight some_language linenos %}...{% endhighlight %}`
+The next portion of this file, including the comments and the workaround,
-and with the Kramdown option to add line numbers to fenced code.
+are preserved for backwards comptability.
+
+ACKNOWLEDGEMENTS
 
 The implementation was derived from the workaround provided by
 Dmitry Hrabrov (DeXP) at
 https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-188144901
 
-EXPLANATION
+EXPLANATION (OLD)
 
-The HTML produced by Rouge highlighting with lie numbers is of the form
+The HTML produced by Rouge highlighting with line numbers is of the form
-`code table`. Jekyll (<= 4.1.1) always wraps the highlighted HTML
+`code table`. Jekyll always wraps the highlighted HTML
 with `pre`. This wrapping is not only unnecessary, but also transforms
 the conforming HTML produced by Rouge to non-conforming HTML, which
 results in HTML validation error reports.

_includes/head.html

@@ -1,43 +1,51 @@
+{%- comment -%}
+  Include as: {%- include head.html -%}
+  Depends on: site.ga_tracking, site.ga_tracking_anonymize_ip,
+    site.search_enabled, site.static_files, site.favicon_ico.
+  Results in: HTML for the head element.
+  Includes:
+    css/activation.scss.liquid, head_custom.html.
+  Overwrites:
+    ga_tracking_ids, ga_property, file, favicon.
+  Should not be cached, because included files depend on page.
+{%- endcomment -%}
+
 <head>
   <meta charset="UTF-8">
   <meta http-equiv="X-UA-Compatible" content="IE=Edge">
 
-  {% unless site.plugins contains "jekyll-seo-tag" %}
-    <title>{{ page.title }} - {{ site.title }}</title>
-
-    {% if page.description %}
-      <meta name="Description" content="{{ page.description }}">
-    {% endif %}
-  {% endunless %}
-
-  {% include favicon.html %}
-
   <link rel="stylesheet" href="{{ '/assets/css/just-the-docs-default.css' | relative_url }}">
 
+  <link rel="stylesheet" href="{{ '/assets/css/just-the-docs-head-nav.css' | relative_url }}" id="jtd-head-nav-stylesheet">
+
+  <style id="jtd-nav-activation">
+  {% include css/activation.scss.liquid %}
+  </style>
+
   {% if site.ga_tracking != nil %}
-    <script async src="https://www.googletagmanager.com/gtag/js?id={{ site.ga_tracking }}"></script>
+    {% assign ga_tracking_ids = site.ga_tracking | split: "," %}
+    <script async src="https://www.googletagmanager.com/gtag/js?id={{ ga_tracking_ids.first }}"></script>
     <script>
       window.dataLayer = window.dataLayer || [];
       function gtag(){dataLayer.push(arguments);}
       gtag('js', new Date());
 
-      gtag('config', '{{ site.ga_tracking }}'{% unless site.ga_tracking_anonymize_ip == nil %}, { 'anonymize_ip': true }{% endunless %});
+      {% for ga_property in ga_tracking_ids %}
+        gtag('config', '{{ ga_property }}'{% unless site.ga_tracking_anonymize_ip == nil %}, { 'anonymize_ip': true }{% endunless %});
+      {% endfor %}
     </script>
-
   {% endif %}
 
   {% if site.search_enabled != false %}
-    <script type="text/javascript" src="{{ '/assets/js/vendor/lunr.min.js' | relative_url }}"></script>
+    <script src="{{ '/assets/js/vendor/lunr.min.js' | relative_url }}"></script>
   {% endif %}
 
-  {% if site.mermaid %}
+  <script src="{{ '/assets/js/just-the-docs.js' | relative_url }}"></script>
-    <script src="https://cdn.jsdelivr.net/npm/mermaid@{{ site.mermaid.version }}/dist/mermaid.min.js"></script>
-  {% endif %}
-
-  <script type="text/javascript" src="{{ '/assets/js/just-the-docs.js' | relative_url }}"></script>
 
   <meta name="viewport" content="width=device-width, initial-scale=1">
 
+  {% include_cached favicon.html %}
+
   {% seo %}
 
   {% include head_custom.html %}

_includes/icons/code_copy.html

@@ -0,0 +1,15 @@
+<!-- Bootstrap Icons. MIT License: https://github.com/twbs/icons/blob/main/LICENSE.md -->
+<symbol id="svg-copy" viewBox="0 0 16 16">
+  <title>Copy</title>
+  <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-clipboard" viewBox="0 0 16 16">
+    <path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1h1a1 1 0 0 1 1 1V14a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3.5a1 1 0 0 1 1-1h1v-1z"/>
+    <path d="M9.5 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3zm-3-1A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3z"/>
+  </svg>
+</symbol>
+<symbol id="svg-copied" viewBox="0 0 16 16">
+  <title>Copied</title>
+  <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-clipboard-check-fill" viewBox="0 0 16 16">
+    <path d="M6.5 0A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3Zm3 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3Z"/>
+    <path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1A2.5 2.5 0 0 1 9.5 5h-3A2.5 2.5 0 0 1 4 2.5v-1Zm6.854 7.354-3 3a.5.5 0 0 1-.708 0l-1.5-1.5a.5.5 0 0 1 .708-.708L7.5 10.793l2.646-2.647a.5.5 0 0 1 .708.708Z"/>
+  </svg>
+</symbol>

_includes/icons/document.html

@@ -0,0 +1,6 @@
+<symbol id="svg-doc" viewBox="0 0 24 24">
+  <title>Document</title>
+  <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-file">
+    <path d="M13 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9z"></path><polyline points="13 2 13 9 20 9"></polyline>
+  </svg>
+</symbol>

_includes/icons/expand.html

@@ -0,0 +1,6 @@
+<symbol id="svg-arrow-right" viewBox="0 0 24 24">
+  <title>Expand</title>
+  <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-chevron-right">
+    <polyline points="9 18 15 12 9 6"></polyline>
+  </svg>
+</symbol>

_includes/icons/icons.html

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" class="d-none">
+  {% include icons/link.html %}
+  {% include icons/menu.html %}
+  {% include icons/expand.html %}
+  {% include icons/external_link.html %}
+  {% if site.search_enabled != false %}
+    {% include icons/document.html %}
+    {% include icons/search.html %}
+  {% endif %}
+  {% if site.enable_copy_code_button != false %}
+    {% include icons/code_copy.html %}
+  {% endif %}
+</svg>

_includes/icons/link.html

@@ -0,0 +1,6 @@
+<symbol id="svg-link" viewBox="0 0 24 24">
+  <title>Link</title>
+  <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link">
+    <path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path>
+  </svg>
+</symbol>

_includes/icons/menu.html

@@ -0,0 +1,6 @@
+<symbol id="svg-menu" viewBox="0 0 24 24">
+  <title>Menu</title>
+  <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-menu">
+    <line x1="3" y1="12" x2="21" y2="12"></line><line x1="3" y1="6" x2="21" y2="6"></line><line x1="3" y1="18" x2="21" y2="18"></line>
+  </svg>
+</symbol>

_includes/icons/search.html

@@ -0,0 +1,6 @@
+<symbol id="svg-search" viewBox="0 0 24 24">
+  <title>Search</title>
+  <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-search">
+    <circle cx="11" cy="11" r="8"></circle><line x1="21" y1="21" x2="16.65" y2="16.65"></line>
+  </svg>
+</symbol>

_includes/nav.html

@@ -1,142 +0,0 @@
-<ul class="nav-list">
-  {%- assign titled_pages = include.pages
-        | where_exp:"item", "item.title != nil" -%}
-
-  {%- comment -%}
-    The values of `title` and `nav_order` can be numbers or strings.
-    Jekyll gives build failures when sorting on mixtures of different types,
-    so numbers and strings need to be sorted separately.
-
-    Here, numbers are sorted by their values, and come before all strings.
-    An omitted `nav_order` value is equivalent to the page's `title` value
-    (except that a numerical `title` value is treated as a string).
-
-    The case-sensitivity of string sorting is determined by `site.nav_sort`.
-  {%- endcomment -%}
-  
-  {%- assign string_ordered_pages = titled_pages
-        | where_exp:"item", "item.nav_order == nil" -%}
-  {%- assign nav_ordered_pages = titled_pages
-        | where_exp:"item", "item.nav_order != nil"  -%}
-
-  {%- comment -%}
-    The nav_ordered_pages have to be added to number_ordered_pages and
-    string_ordered_pages, depending on the nav_order value.
-    The first character of the jsonify result is `"` only for strings.
-  {%- endcomment -%}
-  {%- assign nav_ordered_groups = nav_ordered_pages
-        | group_by_exp:"item", "item.nav_order | jsonify | slice: 0" -%}
-  {%- assign number_ordered_pages = "" | split:"X" -%}
-  {%- for group in nav_ordered_groups -%}
-    {%- if group.name == '"' -%}
-      {%- assign string_ordered_pages = string_ordered_pages | concat: group.items -%}
-    {%- else -%}
-      {%- assign number_ordered_pages = number_ordered_pages | concat: group.items -%}
-    {%- endif -%}
-  {%- endfor -%}
-  
-  {%- assign sorted_number_ordered_pages = number_ordered_pages | sort:"nav_order" -%}
-  
-  {%- comment -%}
-    The string_ordered_pages have to be sorted by nav_order, and otherwise title
-    (where appending the empty string to a numeric title converts it to a string).
-    After grouping them by those values, the groups are sorted, then the items
-    of each group are concatenated.
-  {%- endcomment -%}
-  {%- assign string_ordered_groups = string_ordered_pages
-        | group_by_exp:"item", "item.nav_order | default: item.title | append:''" -%}
-  {%- if site.nav_sort == 'case_insensitive' -%}
-    {%- assign sorted_string_ordered_groups = string_ordered_groups | sort_natural:"name" -%}
-  {%- else -%}
-    {%- assign sorted_string_ordered_groups = string_ordered_groups | sort:"name" -%}
-  {%- endif -%}
-  {%- assign sorted_string_ordered_pages = "" | split:"X" -%}
-  {%- for group in sorted_string_ordered_groups -%}
-    {%- assign sorted_string_ordered_pages = sorted_string_ordered_pages | concat: group.items -%}
-  {%- endfor -%}
-
-  {%- assign pages_list = sorted_number_ordered_pages | concat: sorted_string_ordered_pages -%}
-  
-  {%- for node in pages_list -%}
-    {%- if node.parent == nil -%}
-      {%- unless node.nav_exclude -%}
-      <li class="nav-list-item{% if page.collection == include.key and page.url == node.url or page.parent == node.title or page.grand_parent == node.title %} active{% endif %}">
-        {%- if node.has_children -%}
-          <a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a>
-        {%- endif -%}
-        <a href="{{ node.url | relative_url }}" class="nav-list-link{% if page.url == node.url %} active{% endif %}">{{ node.title }}</a>
-        {%- if node.has_children -%}
-          {%- if node.child_nav_order == 'desc' -%}
-            {%- assign children_list = pages_list | where: "parent", node.title | where_exp:"item", "item.grand_parent == nil" | reverse -%}
-          {%- else -%}
-            {%- assign children_list = pages_list | where: "parent", node.title | where_exp:"item", "item.grand_parent == nil" -%}
-          {%- endif -%}
-          <ul class="nav-list ">
-          {%- for child in children_list -%}
-            {%- unless child.nav_exclude -%}
-            <li class="nav-list-item {% if page.url == child.url or page.parent == child.title %} active{% endif %}">
-              {%- if child.has_children -%}
-                <a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a>
-              {%- endif -%}
-              <a href="{{ child.url | relative_url }}" class="nav-list-link{% if page.url == child.url %} active{% endif %}">{{ child.title }}</a>
-              {%- if child.has_children -%}
-                {%- if node.child_nav_order == 'desc' -%}
-                {%- assign grand_children_list = pages_list | where: "parent", child.title | where: "grand_parent", node.title | reverse -%}
-                {%- else -%}
-                {%- assign grand_children_list = pages_list | where: "parent", child.title | where: "grand_parent", node.title -%}
-                {%- endif -%}
-                <ul class="nav-list">
-                {%- for grand_child in grand_children_list -%}
-                  {%- unless grand_child.nav_exclude -%}
-                  <li class="nav-list-item {% if page.url == grand_child.url %} active{% endif %}">
-                    <a href="{{ grand_child.url | relative_url }}" class="nav-list-link{% if page.url == grand_child.url %} active{% endif %}">{{ grand_child.title }}</a>
-                  </li>
-                  {%- endunless -%}
-                {%- endfor -%}
-                </ul>
-              {%- endif -%}
-            </li>
-            {%- endunless -%}
-          {%- endfor -%}
-          </ul>
-        {%- endif -%}
-      </li>
-      {%- endunless -%}
-    {%- endif -%}
-  {%- endfor -%}
-  {%- assign nav_external_links = site.nav_external_links -%}
-  {%- for node in nav_external_links -%}
-    <li class="nav-list-item external">
-      <a href="{{ node.url | absolute_url }}" class="nav-list-link external">
-        {{ node.title }}
-        {% unless node.hide_icon %}<svg viewBox="0 0 24 24" aria-labelledby="svg-external-link-title"><use xlink:href="#svg-external-link"></use></svg>{% endunless %}
-      </a>
-    </li>
-  {%- endfor -%}
-</ul>
-
-{%- if page.collection == include.key -%}
-
-  {%- for node in pages_list -%}
-    {%- if node.parent == nil -%}
-      {%- if page.grand_parent == node.title or page.parent == node.title and page.grand_parent == nil -%}
-        {%- assign first_level_url = node.url | relative_url -%}
-      {%- endif -%}
-      {%- if node.has_children -%}
-        {%- assign children_list = pages_list | where: "parent", node.title -%}
-        {%- for child in children_list -%}
-          {%- if child.has_children -%}
-            {%- if page.url == child.url or page.parent == child.title and page.grand_parent == child.parent -%}
-              {%- assign second_level_url = child.url | relative_url -%}
-            {%- endif -%}
-          {%- endif -%}
-        {%- endfor -%}
-      {%- endif -%}
-    {%- endif -%}
-  {%- endfor -%}
-
-  {% if page.has_children == true and page.has_toc != false %}
-    {%- assign toc_list = pages_list | where: "parent", page.title | where: "grand_parent", page.parent -%}
-  {%- endif -%}
-
-{%- endif -%}

_includes/sorted_pages.html

@@ -0,0 +1,109 @@
+{%- comment -%}
+  Include as: {%- include sorted_pages.html pages=array_of_pages -%}
+  Depends on: include.pages.
+  Assigns to: sorted_pages.
+  Overwrites: 
+    nav_order_pages, title_order_pages, double_quote, empty_array,
+    nav_number_pages, nav_string_pages, nav_order_groups, group,
+    title_number_pages, title_string_pages, title_order_groups.
+{%- endcomment -%}
+
+{%- comment -%}
+  The `nav_order` values of pages affect the order in which they are shown in
+  the navigation panel and in the automatically generated tables of contents.
+  Sibling pages with the same `nav_order` value may be shown in any order.
+  Sibling pages with no `nav_order` value are shown after all pages that have
+  explicit `nav_order` values, ordered by their `title` values.
+  
+  The `nav_order` and `title` values can be numbers or strings. To avoid build
+  failures, we sort numbers and strings separately. We sort numbers by their
+  values, and strings lexicographically. The case-sensitivity of string sorting
+  is determined by the configuration setting of `nav_sort`. Pages with no `title`
+  value are excluded from the navigation.
+
+  Note: Numbers used as `title` or `nav_order` values should not be in quotes,
+  unless you intend them to be lexicographically ordered. Numbers are written
+  without spaces or thousands-separators. Negative numbers are preceded by `-`.
+  Floats are written with the integral and fractional parts separated by `.`.
+  (Bounds on the magnitude and precision are presumably the same as in Liquid.)
+{%- endcomment -%}
+
+{%- assign nav_order_pages = include.pages
+      | where_exp: "item", "item.nav_order != nil" -%}
+{%- assign title_order_pages = include.pages
+      | where_exp: "item", "item.nav_order == nil" -%}
+
+{%- comment -%}
+  First, filter `nav_order_pages` and `title_order_pages` according to the type
+  of value to be used for sorting.
+  
+  The first character of the result of filtering with `jsonify` is `"` only for
+  strings. Removing `"` from its `slice : 0` has size 0 for strings and 1 for
+  numbers, so grouping the pages gives at most two groups.
+{%- endcomment -%}
+
+{%- assign double_quote = '"' -%}
+{%- assign empty_array = "" | split: "" -%}
+
+{%- assign nav_string_pages = empty_array -%}
+{%- assign nav_number_pages = empty_array -%}
+{%- unless nav_order_pages == empty -%}
+  {%- assign nav_order_groups = nav_order_pages
+        | group_by_exp: "item",
+            "item.nav_order | jsonify | slice: 0 | remove: double_quote | size" -%}
+  {%- for group in nav_order_groups -%}
+    {%- if group.name == 0 -%}
+      {%- assign nav_string_pages = group.items -%}
+    {%- elsif group.name == 1 -%}
+      {%- assign nav_number_pages = group.items -%}
+    {%- endif -%}
+  {%- endfor -%}
+{%- endunless -%}
+
+{%- assign title_string_pages = empty_array -%}
+{%- assign title_number_pages = empty_array -%}
+{%- unless title_order_pages == empty -%}
+  {%- assign title_order_groups = title_order_pages
+        | group_by_exp: "item",
+            "item.title | jsonify | slice: 0 | remove: double_quote | size" -%}
+  {%- for group in title_order_groups -%}
+    {%- if group.name == 0 -%}
+      {%- assign title_string_pages = group.items -%}
+    {%- elsif group.name == 1 -%}
+      {%- assign title_number_pages = group.items -%}
+    {%- endif -%}
+  {%- endfor -%}
+{%- endunless -%}
+
+{%- comment -%}
+  Now sort each array of pages separately, then concatenate the sorted arrays.
+{%- endcomment -%}
+
+{%- unless nav_number_pages == empty -%}
+  {%- assign nav_number_pages = nav_number_pages | sort: "nav_order" -%}
+{%- endunless -%}
+
+{%- unless nav_string_pages == empty -%}
+  {%- if site.nav_sort == 'case_insensitive' -%}
+    {%- assign nav_string_pages = nav_string_pages | sort_natural: "nav_order" -%}
+  {%- else -%}
+    {%- assign nav_string_pages = nav_string_pages | sort: "nav_order" -%}
+  {%- endif -%}
+{%- endunless -%}
+
+{%- unless title_number_pages == empty -%}
+  {%- assign title_number_pages = title_number_pages | sort: "title" -%}
+{%- endunless -%}
+
+{%- unless title_string_pages == empty -%}
+  {%- if site.nav_sort == 'case_insensitive' -%}
+    {%- assign title_string_pages = title_string_pages | sort_natural: "title" -%}
+  {%- else -%}
+    {%- assign title_string_pages = title_string_pages | sort: "title" -%}
+  {%- endif -%}
+{%- endunless -%}
+
+{%- assign sorted_pages = nav_number_pages
+      | concat: nav_string_pages
+      | concat: title_number_pages
+      | concat: title_string_pages -%}

_includes/title.html

@@ -1,5 +1,5 @@
 {% if site.logo %}
-  <div class="site-logo"></div>
+  <div class="site-logo" role="img" aria-label="{{ site.title }}"></div>
 {% else %}
   {{ site.title }}
 {% endif %}

_includes/toc_heading_custom.html

@@ -0,0 +1 @@
+<h2 class="text-delta">Table of contents</h2>

_includes/vendor/anchor_headings.html

@@ -24,7 +24,7 @@
     OTHER DEALINGS IN THE SOFTWARE.
   {% endcomment %}
   {% comment %}
-    Version 1.0.7
+    Version 1.0.12
       https://github.com/allejo/jekyll-anchor-headings
 
     "Be the pull request you wish to see in the world." ~Ben Balter
@@ -37,6 +37,8 @@
 
     Optional Parameters:
       * beforeHeading (bool)   : false  - Set to true if the anchor should be placed _before_ the heading's content
+      * headerAttrs   (string) :  ''    - Any custom HTML attributes that will be added to the heading tag; you may NOT use `id`;
+                                          the `%heading%` and `%html_id%` placeholders are available
       * anchorAttrs   (string) :  ''    - Any custom HTML attributes that will be added to the `<a>` tag; you may NOT use `href`, `class` or `title`;
                                           the `%heading%` and `%html_id%` placeholders are available
       * anchorBody    (string) :  ''    - The content that will be placed inside the anchor; the `%heading%` placeholder is available
@@ -46,6 +48,7 @@
       * h_max         (int)    :  6     - The maximum header level to build an anchor for; any header greater than this value will be ignored
       * bodyPrefix    (string) :  ''    - Anything that should be inserted inside of the heading tag _before_ its anchor and content
       * bodySuffix    (string) :  ''    - Anything that should be inserted inside of the heading tag _after_ its anchor and content
+      * generateId    (true)   :  false - Set to true if a header without id should generate an id to use.
 
     Output:
       The original HTML with the addition of anchors inside of all of the h1-h6 headings.
@@ -54,6 +57,7 @@
   {% assign minHeader = include.h_min | default: 1 %}
   {% assign maxHeader = include.h_max | default: 6 %}
   {% assign beforeHeading = include.beforeHeading %}
+  {% assign headerAttrs = include.headerAttrs %}
   {% assign nodes = include.html | split: '<h' %}
 
   {% capture edited_headings %}{% endcapture %}
@@ -84,17 +88,41 @@
 
     {% capture _closingTag %}</h{{ headerLevel }}>{% endcapture %}
     {% assign _workspace = node | split: _closingTag %}
-    {% assign _idWorkspace = _workspace[0] | split: 'id="' %}
-    {% assign _idWorkspace = _idWorkspace[1] | split: '"' %}
-    {% assign html_id = _idWorkspace[0] %}
-
     {% capture _hAttrToStrip %}{{ _workspace[0] | split: '>' | first }}>{% endcapture %}
     {% assign header = _workspace[0] | replace: _hAttrToStrip, '' %}
+    {% assign escaped_header = header | strip_html | strip %}
+
+    {% assign _classWorkspace = _workspace[0] | split: 'class="' %}
+    {% assign _classWorkspace = _classWorkspace[1] | split: '"' %}
+    {% assign _html_class = _classWorkspace[0] %}
+
+    {% if _html_class contains "no_anchor" %}
+      {% assign skip_anchor = true %}
+    {% else %}
+      {% assign skip_anchor = false %}
+    {% endif %}
+
+    {% assign _idWorkspace = _workspace[0] | split: 'id="' %}
+    {% if _idWorkspace[1] %}
+      {% assign _idWorkspace = _idWorkspace[1] | split: '"' %}
+      {% assign html_id = _idWorkspace[0] %}
+    {% elsif include.generateId %}
+      <!-- If the header did not have an id we create one. -->
+      {% assign html_id = escaped_header | slugify %}
+      {% if html_id == "" %}
+        {% assign html_id = false %}
+      {% endif %}
+      {% capture headerAttrs %}{{ headerAttrs }} id="%html_id%"{% endcapture %}
+    {% endif %}
 
     <!-- Build the anchor to inject for our heading -->
     {% capture anchor %}{% endcapture %}
 
-    {% if html_id and headerLevel >= minHeader and headerLevel <= maxHeader %}
+    {% if skip_anchor == false and html_id and headerLevel >= minHeader and headerLevel <= maxHeader %}
+      {% if headerAttrs %}
+        {% capture _hAttrToStrip %}{{ _hAttrToStrip | split: '>' | first }} {{ headerAttrs | replace: '%heading%', escaped_header | replace: '%html_id%', html_id }}>{% endcapture %}
+      {% endif %}
+
       {% capture anchor %}href="#{{ html_id }}"{% endcapture %}
 
       {% if include.anchorClass %}
@@ -102,14 +130,14 @@
       {% endif %}
 
       {% if include.anchorTitle %}
-        {% capture anchor %}{{ anchor }} title="{{ include.anchorTitle | replace: '%heading%', header }}"{% endcapture %}
+        {% capture anchor %}{{ anchor }} title="{{ include.anchorTitle | replace: '%heading%', escaped_header }}"{% endcapture %}
       {% endif %}
 
       {% if include.anchorAttrs %}
-        {% capture anchor %}{{ anchor }} {{ include.anchorAttrs | replace: '%heading%', header | replace: '%html_id%', html_id }}{% endcapture %}
+        {% capture anchor %}{{ anchor }} {{ include.anchorAttrs | replace: '%heading%', escaped_header | replace: '%html_id%', html_id }}{% endcapture %}
       {% endif %}
 
-      {% capture anchor %}<a {{ anchor }}>{{ include.anchorBody | replace: '%heading%', header | default: '' }}</a>{% endcapture %}
+      {% capture anchor %}<a {{ anchor }}>{{ include.anchorBody | replace: '%heading%', escaped_header | default: '' }}</a>{% endcapture %}
 
       <!-- In order to prevent adding extra space after a heading, we'll let the 'anchor' value contain it -->
       {% if beforeHeading %}

_layouts/default.html

@@ -7,147 +7,15 @@ layout: table_wrappers
 <html lang="{{ site.lang | default: 'en-US' }}">
 {% include head.html %}
 <body>
-  <svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+  <a class="skip-to-main" href="#main-content">Skip to main content</a>
-    <symbol id="svg-link" viewBox="0 0 24 24">
+  {% include icons/icons.html %}
-      <title>Link</title>
+  {% include components/sidebar.html %}
-      <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link">
-        <path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path>
-      </svg>
-    </symbol>
-    <symbol id="svg-search" viewBox="0 0 24 24">
-      <title>Search</title>
-      <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-search">
-        <circle cx="11" cy="11" r="8"></circle><line x1="21" y1="21" x2="16.65" y2="16.65"></line>
-      </svg>
-    </symbol>
-    <symbol id="svg-menu" viewBox="0 0 24 24">
-      <title>Menu</title>
-      <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-menu">
-        <line x1="3" y1="12" x2="21" y2="12"></line><line x1="3" y1="6" x2="21" y2="6"></line><line x1="3" y1="18" x2="21" y2="18"></line>
-      </svg>
-    </symbol>
-    <symbol id="svg-arrow-right" viewBox="0 0 24 24">
-      <title>Expand</title>
-      <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-chevron-right">
-        <polyline points="9 18 15 12 9 6"></polyline>
-      </svg>
-    </symbol>
-    <symbol id="svg-doc" viewBox="0 0 24 24">
-      <title>Document</title>
-      <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-file">
-        <path d="M13 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9z"></path><polyline points="13 2 13 9 20 9"></polyline>
-      </svg>
-    </symbol>
-    {% include icons/external_link.html %}
-  </svg>
-
-  <div class="side-bar">
-    <div class="site-header">
-      <a href="{{ '/' | relative_url }}" class="site-title lh-tight">{% include title.html %}</a>
-      <a href="#" id="menu-button" class="site-button">
-        <svg viewBox="0 0 24 24" class="icon"><use xlink:href="#svg-menu"></use></svg>
-      </a>
-    </div>
-    <nav role="navigation" aria-label="Main" id="site-nav" class="site-nav">
-      {% assign pages_top_size = site.html_pages
-          | where_exp:"item", "item.title != nil"
-          | where_exp:"item", "item.parent == nil"
-          | where_exp:"item", "item.nav_exclude != true"
-          | size %}
-      {% if pages_top_size > 0 %}
-        {% include nav.html pages=site.html_pages key=nil %}
-      {% endif %}
-      {% if site.just_the_docs.collections %}
-        {% assign collections_size = site.just_the_docs.collections | size %}
-        {% for collection_entry in site.just_the_docs.collections %}
-          {% assign collection_key = collection_entry[0] %}
-          {% assign collection_value = collection_entry[1] %}
-          {% assign collection = site[collection_key] %}
-          {% if collection_value.nav_exclude != true %}
-            {% if collections_size > 1 or pages_top_size > 0 %}
-              {% if collection_value.nav_fold == true %}
-                <ul class="nav-list nav-category-list">
-                  <li class="nav-list-item{% if page.collection == collection_key %} active{% endif %}">
-                    {%- if collection.size > 0 -%}
-                    <a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a>
-                    {%- endif -%}
-                    <div class="nav-category">{{ collection_value.name }}</div>
-                    {% include nav.html pages=collection key=collection_key %}
-                  </li>
-                </ul>
-              {% else %}
-                <div class="nav-category">{{ collection_value.name }}</div>
-                {% include nav.html pages=collection key=collection_key %}
-              {% endif %}
-            {% else %}
-              {% include nav.html pages=collection key=collection_key %}
-            {% endif %}
-          {% endif %}
-        {% endfor %}
-      {% endif %}
-    </nav>
-
-    {% capture nav_footer_custom %}
-      {%- include nav_footer_custom.html -%}
-    {% endcapture %}
-    {% if nav_footer_custom != "" %}
-      {{ nav_footer_custom }}
-    {% else %}
-      <footer class="site-footer">
-        This site uses <a href="https://github.com/just-the-docs/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll.
-      </footer>
-    {% endif %}
-  </div>
   <div class="main" id="top">
-    <div id="main-header" class="main-header">
+    {% include components/header.html %}
-      {% if site.search_enabled != false %}
+    <div class="main-content-wrap">
-
+      {% include components/breadcrumbs.html %}
-        {% capture search_placeholder %}{% include search_placeholder_custom.html %}{% endcapture %}
+      <div id="main-content" class="main-content">
-
+        <main>
-        <div class="search">
-          <div class="search-input-wrap">
-            <input type="text" id="search-input" class="search-input" tabindex="0" placeholder="{{ search_placeholder | strip_html | strip }}" aria-label="{{ search_placeholder | strip_html| strip }}" autocomplete="off">
-            <label for="search-input" class="search-label"><svg viewBox="0 0 24 24" class="search-icon"><use xlink:href="#svg-search"></use></svg></label>
-          </div>
-          <div id="search-results" class="search-results"></div>
-        </div>
-      {% endif %}
-      {% include header_custom.html %}
-      {% if site.aux_links %}
-        <nav aria-label="Auxiliary" class="aux-nav">
-          <ul class="aux-nav-list">
-            {% for link in site.aux_links %}
-              <li class="aux-nav-list-item">
-                <a href="{{ link.last }}" class="site-button"
-                  {% if site.aux_links_new_tab %}
-                  target="_blank" rel="noopener noreferrer"
-                  {% endif %}
-                >
-                  {{ link.first }}
-                </a>
-              </li>
-            {% endfor %}
-          </ul>
-        </nav>
-      {% endif %}
-    </div>
-    <div id="main-content-wrap" class="main-content-wrap">
-      {% unless page.url == "/" %}
-        {% if page.parent %}
-          <nav aria-label="Breadcrumb" class="breadcrumb-nav">
-            <ol class="breadcrumb-nav-list">
-              {% if page.grand_parent %}
-                <li class="breadcrumb-nav-list-item"><a href="{{ first_level_url }}">{{ page.grand_parent }}</a></li>
-                <li class="breadcrumb-nav-list-item"><a href="{{ second_level_url }}">{{ page.parent }}</a></li>
-              {% else %}
-                <li class="breadcrumb-nav-list-item"><a href="{{ first_level_url }}">{{ page.parent }}</a></li>
-              {% endif %}
-              <li class="breadcrumb-nav-list-item"><span>{{ page.title }}</span></li>
-            </ol>
-          </nav>
-        {% endif %}
-      {% endunless %}
-      <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 %}
@@ -155,71 +23,19 @@ layout: table_wrappers
           {% endif %}
 
           {% if page.has_children == true and page.has_toc != false %}
-          <hr>
+            {% include components/children_nav.html %}
-          <h2 class="text-delta">Table of contents</h2>
-          <ul>
-            {% for child in toc_list %}
-              <li>
-                <a href="{{ child.url | relative_url }}">{{ child.title }}</a>{% if child.summary %} - {{ child.summary }}{% endif %}
-              </li>
-            {% endfor %}
-          </ul>
           {% endif %}
-
+        </main>
-        {% capture footer_custom %}
+        {% include components/footer.html %}
-          {%- include footer_custom.html -%}
-        {% endcapture %}
-        {% if footer_custom != "" or site.last_edit_timestamp or site.gh_edit_link %}
-          <hr>
-          <footer>
-            {% if site.back_to_top %}
-              <p><a href="#top" id="back-to-top">{{ site.back_to_top_text }}</a></p>
-            {% endif %}
-
-            {{ footer_custom }}
-
-            {% if site.last_edit_timestamp or site.gh_edit_link %}
-              <div class="d-flex mt-2">
-                {% if site.last_edit_timestamp and site.last_edit_time_format and page.last_modified_date %}
-                  <p class="text-small text-grey-dk-000 mb-0 mr-2">
-                    Page last modified: <span class="d-inline-block">{{ page.last_modified_date | date: site.last_edit_time_format }}</span>.
-                  </p>
-                {% endif %}
-                {% if
-                  site.gh_edit_link and
-                  site.gh_edit_link_text and
-                  site.gh_edit_repository and
-                  site.gh_edit_branch and
-                  site.gh_edit_view_mode
-                %}
-                  <p class="text-small text-grey-dk-000 mb-0">
-                    <a href="{{ site.gh_edit_repository }}/{{ site.gh_edit_view_mode }}/{{ site.gh_edit_branch }}{% if site.gh_edit_source %}/{{ site.gh_edit_source }}{% endif %}{% if page.collection and site.collections_dir %}/{{ site.collections_dir }}{% endif %}/{{ page.path }}" id="edit-this-page">{{ site.gh_edit_link_text }}</a>
-                  </p>
-                {% endif %}
-              </div>
-            {% endif %}
-          </footer>
-        {% endif %}
-
       </div>
     </div>
-
     {% if site.search_enabled != false %}
-      {% if site.search.button %}
+      {% include components/search_footer.html %}
-        <a href="#" id="search-button" class="search-button">
-          <svg viewBox="0 0 24 24" class="icon"><use xlink:href="#svg-search"></use></svg>
-        </a>
-      {% endif %}
-
-      <div class="search-overlay"></div>
     {% endif %}
   </div>
-</body>
+
   {% if site.mermaid %}
-  <script>
+    {% include components/mermaid.html %}
-    var config = {% include mermaid_config.js %};
-    mermaid.initialize(config);
-    window.mermaid.init(undefined, document.querySelectorAll('.language-mermaid'));
-  </script>
   {% endif %}
+</body>
 </html>

_layouts/minimal.html

@@ -0,0 +1,34 @@
+---
+layout: table_wrappers
+---
+
+<!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>

_sass/base.scss

@@ -1,13 +1,12 @@
 // Base element style overrides
 // stylelint-disable selector-no-type, selector-max-type, selector-max-specificity, selector-max-id
 
-* {
+:root {
-  box-sizing: border-box;
+  color-scheme: $color-scheme;
 }
 
-::selection {
+* {
-  color: $white;
+  box-sizing: border-box;
-  background: $link-color;
 }
 
 html {
@@ -65,18 +64,12 @@ a {
 }
 
 a:not([class]) {
-  text-decoration: none;
+  text-decoration: underline;
-  background-image: linear-gradient($border-color 0%, $border-color 100%);
+  text-decoration-color: $border-color;
-  background-repeat: repeat-x;
+  text-underline-offset: 2px;
-  background-position: 0 100%;
-  background-size: 1px 1px;
 
   &:hover {
-    background-image: linear-gradient(
+    text-decoration-color: rgba($link-color, 0.45);
-      rgba($link-color, 0.45) 0%,
-      rgba($link-color, 0.45) 100%
-    );
-    background-size: 1px 1px;
   }
 }
 
@@ -107,3 +100,14 @@ hr {
   background-color: $border-color;
   border: 0;
 }
+
+// adds a GitHub-style sidebar to blockquotes
+blockquote {
+  margin: 10px 0;
+
+  // resets user-agent stylesheets for blockquotes
+  margin-block-start: 0;
+  margin-inline-start: 0;
+  padding-left: 1rem;
+  border-left: 3px solid $border-color;
+}

_sass/buttons.scss

@@ -4,10 +4,7 @@
 .btn {
   display: inline-block;
   box-sizing: border-box;
-  padding-top: 0.3em;
+  padding: 0.3em 1em;
-  padding-right: 1em;
-  padding-bottom: 0.3em;
-  padding-left: 1em;
   margin: 0;
   font-family: inherit;
   font-size: inherit;
@@ -20,7 +17,9 @@
   background-color: $base-button-color;
   border-width: 0;
   border-radius: $border-radius;
-  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
+  box-shadow:
+    0 1px 2px rgba(0, 0, 0, 0.12),
+    0 3px 10px rgba(0, 0, 0, 0.08);
   appearance: none;
 
   &:focus {
@@ -90,7 +89,9 @@
   &:focus {
     text-decoration: none;
     outline: none;
-    box-shadow: inset 0 0 0 2px $grey-dk-100, 0 0 0 3px rgba(blue, 0.25);
+    box-shadow:
+      inset 0 0 0 2px $grey-dk-100,
+      0 0 0 3px rgba(blue, 0.25);
   }
 
   &:focus:hover,
@@ -114,3 +115,13 @@
 .btn-green {
   @include btn-color($white, $green-100);
 }
+
+.btn-reset {
+  background: none;
+  border: none;
+  margin: 0;
+  text-align: inherit;
+  font: inherit;
+  border-radius: 0;
+  appearance: none;
+}

_sass/code.scss

@@ -3,13 +3,16 @@
 
 // {% raw %}
 
-code {
+// This instruction applies to all queues not within 'pre' or 'figure', avoiding 'code' generated by the highlight.
+:not(pre, figure) {
+  & > code {
     padding: 0.2em 0.15em;
     font-weight: 400;
     background-color: $code-background-color;
     border: $border $border-color;
     border-radius: $border-radius;
   }
+}
 
 // Avoid appearance of dark border around visited code links in Safari
 a:visited code {
@@ -47,19 +50,84 @@ a:visited code {
 // Kramdown line_numbers = true: fences have a wider gutter than with Liquid?
 
 // ```[LANG]...```
+// or in AsciiDoc:
+//
+//     ----
+//     ...
+//     ----
+
+// the code may appear with 3 different types:
+// container \ case:  default case,          code with line number,   code with html rendering
+// top level:         div.highlighter-rouge, figure.highlight,        figure.highlight
+// second level:      div.highlight,         div.table-wrapper,       pre.highlight
+// third level:       pre.highlight,         td.code,                 absent
+// last level:        code,                  pre,                     code (optionality)
+// highlighter level: span,                  span,                    span
+// the spacing are only in the second level for case 1, 3 and in the third level for case 2
+// in AsciiDoc, there is a parent container that contains optionally a title and the content.
+
+// select top level container
 div.highlighter-rouge,
-div.listingblock {
+div.listingblock > div.content,
-  padding: $sp-3;
+figure.highlight {
   margin-top: 0;
   margin-bottom: $sp-3;
-  overflow-x: auto;
   background-color: $code-background-color;
   border-radius: $border-radius;
   box-shadow: none;
   -webkit-overflow-scrolling: touch;
+  position: relative;
+  padding: 0;
 
-  div.highlight,
+  // copy button (or other button)
-  pre.highlight,
+  // the button appear only when there is a hover on the code or focus on button
+  > button {
+    width: $sp-3;
+    opacity: 0;
+    position: absolute;
+    top: 0;
+    right: 0;
+    border: $sp-3 solid $code-background-color;
+    background-color: $code-background-color;
+    color: $body-text-color;
+    box-sizing: content-box;
+
+    svg {
+      fill: $body-text-color;
+    }
+
+    &:active {
+      text-decoration: none;
+      outline: none;
+      opacity: 1;
+    }
+
+    &:focus {
+      opacity: 1;
+    }
+  }
+
+  // the button can be seen by doing a simple hover in the code, there is no need to go over the location of the button
+  &:hover {
+    > button {
+      cursor: copy;
+      opacity: 1;
+    }
+  }
+}
+
+// setting the spacing and scrollbar on the second level for the first case
+// remove all space on the second and third level
+// this is a mixin to accommodate for the slightly different structures generated via Markdown vs AsciiDoc
+@mixin scroll-and-spacing($code-div, $pre-select) {
+  #{$code-div} {
+    overflow-x: auto;
+    padding: $sp-3;
+    margin: 0;
+    border: 0;
+  }
+
+  #{$pre-select},
   code {
     padding: 0;
     margin: 0;
@@ -67,21 +135,30 @@ div.listingblock {
   }
 }
 
-// {% highlight LANG %}...{% endhighlight %},
+// for Markdown
-// {% highlight LANG linenos %}...{% endhighlight %}:
+div.highlighter-rouge {
-figure.highlight {
+  @include scroll-and-spacing("div.highlight", "pre.highlight");
-  padding: $sp-3;
+}
+
+// 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;
-  overflow-x: auto;
+}
-  background-color: $code-background-color;
-  border-radius: $border-radius;
-  box-shadow: none;
-  -webkit-overflow-scrolling: touch;
 
+// {% highlight LANG %}...{% endhighlight %},
+// {% highlight LANG linenos %}...{% endhighlight %}:
+
+// setting the spacing and scrollbar on the second level for the thirt case
+// the css rule are apply only to the last code enviroment
+// setting the scroolbar
+figure.highlight {
   pre,
-  code {
+  :not(pre) > code {
-    padding: 0;
+    overflow-x: auto;
+    padding: $sp-3;
     margin: 0;
     border: 0;
   }
@@ -89,8 +166,10 @@ figure.highlight {
 
 // ```[LANG]...```, kramdown line_numbers = true,
 // {% highlight LANG linenos %}...{% endhighlight %}:
+
+// setting the spacing and scrollbar on the thirt level for the second case
 .highlight .table-wrapper {
-  padding: 0;
+  padding: $sp-3 0;
   margin: 0;
   border: 0;
   box-shadow: none;
@@ -106,7 +185,9 @@ figure.highlight {
   }
 
   td.gl {
+    width: 1em;
     padding-right: $sp-3;
+    padding-left: $sp-3;
   }
 
   pre {
@@ -115,11 +196,9 @@ figure.highlight {
   }
 }
 
-//
+// Code examples: html render of a code
-// Code examples (rendered)
+.code-example,
-//
+.listingblock > .title {
-
-.code-example {
   padding: $sp-3;
   margin-bottom: $sp-3;
   overflow: auto;
@@ -128,6 +207,7 @@ figure.highlight {
 
   + .highlighter-rouge,
   + .sectionbody .listingblock,
+  + .content,
   + figure.highlight {
     position: relative;
     margin-top: -$sp-4;
@@ -146,4 +226,21 @@ code.language-mermaid {
   border: 0;
 }
 
+// Override OneDarkJekyll Colors for Code Blocks
+.highlight,
+pre.highlight {
+  background: $code-background-color; // Code Background
+  // For Backwards Compatibility Before $code-linenumber-color was added
+  @if variable-exists(code-linenumber-color) {
+    color: $code-linenumber-color; // Code Line Numbers
+  } @else {
+    color: $body-text-color; // Code Line Numbers
+  }
+}
+
+// Override OneDarkJekyll Colors for Code Blocks
+.highlight pre {
+  background: $code-background-color; // Code Background
+}
+
 // {% endraw %}

_sass/color_schemes/dark.scss

@@ -1,28 +1,18 @@
+$color-scheme: dark;
 $body-background-color: $grey-dk-300;
-$sidebar-color: $grey-dk-300;
-$border-color: $grey-dk-200;
-$body-text-color: $grey-lt-300;
 $body-heading-color: $grey-lt-000;
-$nav-child-link-color: $grey-dk-000;
+$body-text-color: $grey-lt-300;
-$search-result-preview-color: $grey-dk-000;
 $link-color: $blue-000;
-$btn-primary-color: $blue-200;
+$nav-child-link-color: $grey-dk-000;
+$sidebar-color: $grey-dk-300;
 $base-button-color: $grey-dk-250;
-$search-background-color: $grey-dk-250;
+$btn-primary-color: $blue-200;
-$table-background-color: $grey-dk-250;
+$code-background-color: #31343f; // OneDarkJekyll default for syntax-one-dark-vivid
+$code-linenumber-color: #dee2f7; // OneDarkJekyll .nf for syntax-one-dark-vivid
 $feedback-color: darken($sidebar-color, 3%);
+$table-background-color: $grey-dk-250;
+$search-background-color: $grey-dk-250;
+$search-result-preview-color: $grey-dk-000;
+$border-color: $grey-dk-200;
 
-// The following highlight theme is more legible than that used for the light color scheme
+@import "./vendor/OneDarkJekyll/syntax"; // this is the one-dark-vivid atom syntax theme
-
-// @import "./vendor/OneDarkJekyll/syntax-one-dark";
-// $code-background-color: #282c34;
-
-@import "./vendor/OneDarkJekyll/syntax-one-dark-vivid";
-
-$code-background-color: #31343f;
-
-// @import "./vendor/OneDarkJekyll/syntax-firewatch";
-// $code-background-color: #282c34;
-
-// @import "./vendor/OneDarkJekyll/syntax-firewatch-green";
-// $code-background-color: #282c34;

_sass/color_schemes/legacy_light.scss

@@ -0,0 +1,208 @@
+// Moved from _sass/code.scss
+
+.highlight .c {
+  color: #586e75;
+} // comment //
+.highlight .err {
+  color: #93a1a1;
+} // error //
+.highlight .g {
+  color: #93a1a1;
+} // generic //
+.highlight .k {
+  color: #859900;
+} // keyword //
+.highlight .l {
+  color: #93a1a1;
+} // literal //
+.highlight .n {
+  color: #93a1a1;
+} // name //
+.highlight .o {
+  color: #859900;
+} // operator //
+.highlight .x {
+  color: #cb4b16;
+} // other //
+.highlight .p {
+  color: #93a1a1;
+} // punctuation //
+.highlight .cm {
+  color: #586e75;
+} // comment.multiline //
+.highlight .cp {
+  color: #859900;
+} // comment.preproc //
+.highlight .c1 {
+  color: #586e75;
+} // comment.single //
+.highlight .cs {
+  color: #859900;
+} // comment.special //
+.highlight .gd {
+  color: #2aa198;
+} // generic.deleted //
+.highlight .ge {
+  font-style: italic;
+  color: #93a1a1;
+} // generic.emph //
+.highlight .gr {
+  color: #dc322f;
+} // generic.error //
+.highlight .gh {
+  color: #cb4b16;
+} // generic.heading //
+.highlight .gi {
+  color: #859900;
+} // generic.inserted //
+.highlight .go {
+  color: #93a1a1;
+} // generic.output //
+.highlight .gp {
+  color: #93a1a1;
+} // generic.prompt //
+.highlight .gs {
+  font-weight: bold;
+  color: #93a1a1;
+} // generic.strong //
+.highlight .gu {
+  color: #cb4b16;
+} // generic.subheading //
+.highlight .gt {
+  color: #93a1a1;
+} // generic.traceback //
+.highlight .kc {
+  color: #cb4b16;
+} // keyword.constant //
+.highlight .kd {
+  color: #268bd2;
+} // keyword.declaration //
+.highlight .kn {
+  color: #859900;
+} // keyword.namespace //
+.highlight .kp {
+  color: #859900;
+} // keyword.pseudo //
+.highlight .kr {
+  color: #268bd2;
+} // keyword.reserved //
+.highlight .kt {
+  color: #dc322f;
+} // keyword.type //
+.highlight .ld {
+  color: #93a1a1;
+} // literal.date //
+.highlight .m {
+  color: #2aa198;
+} // literal.number //
+.highlight .s {
+  color: #2aa198;
+} // literal.string //
+.highlight .na {
+  color: #555;
+} // name.attribute //
+.highlight .nb {
+  color: #b58900;
+} // name.builtin //
+.highlight .nc {
+  color: #268bd2;
+} // name.class //
+.highlight .no {
+  color: #cb4b16;
+} // name.constant //
+.highlight .nd {
+  color: #268bd2;
+} // name.decorator //
+.highlight .ni {
+  color: #cb4b16;
+} // name.entity //
+.highlight .ne {
+  color: #cb4b16;
+} // name.exception //
+.highlight .nf {
+  color: #268bd2;
+} // name.function //
+.highlight .nl {
+  color: #555;
+} // name.label //
+.highlight .nn {
+  color: #93a1a1;
+} // name.namespace //
+.highlight .nx {
+  color: #555;
+} // name.other //
+.highlight .py {
+  color: #93a1a1;
+} // name.property //
+.highlight .nt {
+  color: #268bd2;
+} // name.tag //
+.highlight .nv {
+  color: #268bd2;
+} // name.variable //
+.highlight .ow {
+  color: #859900;
+} // operator.word //
+.highlight .w {
+  color: #93a1a1;
+} // text.whitespace //
+.highlight .mf {
+  color: #2aa198;
+} // literal.number.float //
+.highlight .mh {
+  color: #2aa198;
+} // literal.number.hex //
+.highlight .mi {
+  color: #2aa198;
+} // literal.number.integer //
+.highlight .mo {
+  color: #2aa198;
+} // literal.number.oct //
+.highlight .sb {
+  color: #586e75;
+} // literal.string.backtick //
+.highlight .sc {
+  color: #2aa198;
+} // literal.string.char //
+.highlight .sd {
+  color: #93a1a1;
+} // literal.string.doc //
+.highlight .s2 {
+  color: #2aa198;
+} // literal.string.double //
+.highlight .se {
+  color: #cb4b16;
+} // literal.string.escape //
+.highlight .sh {
+  color: #93a1a1;
+} // literal.string.heredoc //
+.highlight .si {
+  color: #2aa198;
+} // literal.string.interpol //
+.highlight .sx {
+  color: #2aa198;
+} // literal.string.other //
+.highlight .sr {
+  color: #dc322f;
+} // literal.string.regex //
+.highlight .s1 {
+  color: #2aa198;
+} // literal.string.single //
+.highlight .ss {
+  color: #2aa198;
+} // literal.string.symbol //
+.highlight .bp {
+  color: #268bd2;
+} // name.builtin.pseudo //
+.highlight .vc {
+  color: #268bd2;
+} // name.variable.class //
+.highlight .vg {
+  color: #268bd2;
+} // name.variable.global //
+.highlight .vi {
+  color: #268bd2;
+} // name.variable.instance //
+.highlight .il {
+  color: #2aa198;
+} // literal.number.integer.long //

_sass/color_schemes/light.scss

@@ -1,208 +1,16 @@
-// Moved from _sass/code.scss
+$color-scheme: light !default;
+$body-background-color: $white !default;
+$body-heading-color: $grey-dk-300 !default;
+$body-text-color: $grey-dk-100 !default;
+$link-color: $purple-000 !default;
+$nav-child-link-color: $grey-dk-100 !default;
+$sidebar-color: $grey-lt-000 !default;
+$base-button-color: #f7f7f7 !default;
+$btn-primary-color: $purple-100 !default;
+$code-background-color: $grey-lt-000 !default;
+$feedback-color: darken($sidebar-color, 3%) !default;
+$table-background-color: $white !default;
+$search-background-color: $white !default;
+$search-result-preview-color: $grey-dk-000 !default;
 
-.highlight .c {
+@import "./vendor/OneLightJekyll/syntax";
-  color: #586e75;
-} // comment //
-.highlight .err {
-  color: #93a1a1;
-} // error //
-.highlight .g {
-  color: #93a1a1;
-} // generic //
-.highlight .k {
-  color: #859900;
-} // keyword //
-.highlight .l {
-  color: #93a1a1;
-} // literal //
-.highlight .n {
-  color: #93a1a1;
-} // name //
-.highlight .o {
-  color: #859900;
-} // operator //
-.highlight .x {
-  color: #cb4b16;
-} // other //
-.highlight .p {
-  color: #93a1a1;
-} // punctuation //
-.highlight .cm {
-  color: #586e75;
-} // comment.multiline //
-.highlight .cp {
-  color: #859900;
-} // comment.preproc //
-.highlight .c1 {
-  color: #586e75;
-} // comment.single //
-.highlight .cs {
-  color: #859900;
-} // comment.special //
-.highlight .gd {
-  color: #2aa198;
-} // generic.deleted //
-.highlight .ge {
-  font-style: italic;
-  color: #93a1a1;
-} // generic.emph //
-.highlight .gr {
-  color: #dc322f;
-} // generic.error //
-.highlight .gh {
-  color: #cb4b16;
-} // generic.heading //
-.highlight .gi {
-  color: #859900;
-} // generic.inserted //
-.highlight .go {
-  color: #93a1a1;
-} // generic.output //
-.highlight .gp {
-  color: #93a1a1;
-} // generic.prompt //
-.highlight .gs {
-  font-weight: bold;
-  color: #93a1a1;
-} // generic.strong //
-.highlight .gu {
-  color: #cb4b16;
-} // generic.subheading //
-.highlight .gt {
-  color: #93a1a1;
-} // generic.traceback //
-.highlight .kc {
-  color: #cb4b16;
-} // keyword.constant //
-.highlight .kd {
-  color: #268bd2;
-} // keyword.declaration //
-.highlight .kn {
-  color: #859900;
-} // keyword.namespace //
-.highlight .kp {
-  color: #859900;
-} // keyword.pseudo //
-.highlight .kr {
-  color: #268bd2;
-} // keyword.reserved //
-.highlight .kt {
-  color: #dc322f;
-} // keyword.type //
-.highlight .ld {
-  color: #93a1a1;
-} // literal.date //
-.highlight .m {
-  color: #2aa198;
-} // literal.number //
-.highlight .s {
-  color: #2aa198;
-} // literal.string //
-.highlight .na {
-  color: #555;
-} // name.attribute //
-.highlight .nb {
-  color: #b58900;
-} // name.builtin //
-.highlight .nc {
-  color: #268bd2;
-} // name.class //
-.highlight .no {
-  color: #cb4b16;
-} // name.constant //
-.highlight .nd {
-  color: #268bd2;
-} // name.decorator //
-.highlight .ni {
-  color: #cb4b16;
-} // name.entity //
-.highlight .ne {
-  color: #cb4b16;
-} // name.exception //
-.highlight .nf {
-  color: #268bd2;
-} // name.function //
-.highlight .nl {
-  color: #555;
-} // name.label //
-.highlight .nn {
-  color: #93a1a1;
-} // name.namespace //
-.highlight .nx {
-  color: #555;
-} // name.other //
-.highlight .py {
-  color: #93a1a1;
-} // name.property //
-.highlight .nt {
-  color: #268bd2;
-} // name.tag //
-.highlight .nv {
-  color: #268bd2;
-} // name.variable //
-.highlight .ow {
-  color: #859900;
-} // operator.word //
-.highlight .w {
-  color: #93a1a1;
-} // text.whitespace //
-.highlight .mf {
-  color: #2aa198;
-} // literal.number.float //
-.highlight .mh {
-  color: #2aa198;
-} // literal.number.hex //
-.highlight .mi {
-  color: #2aa198;
-} // literal.number.integer //
-.highlight .mo {
-  color: #2aa198;
-} // literal.number.oct //
-.highlight .sb {
-  color: #586e75;
-} // literal.string.backtick //
-.highlight .sc {
-  color: #2aa198;
-} // literal.string.char //
-.highlight .sd {
-  color: #93a1a1;
-} // literal.string.doc //
-.highlight .s2 {
-  color: #2aa198;
-} // literal.string.double //
-.highlight .se {
-  color: #cb4b16;
-} // literal.string.escape //
-.highlight .sh {
-  color: #93a1a1;
-} // literal.string.heredoc //
-.highlight .si {
-  color: #2aa198;
-} // literal.string.interpol //
-.highlight .sx {
-  color: #2aa198;
-} // literal.string.other //
-.highlight .sr {
-  color: #dc322f;
-} // literal.string.regex //
-.highlight .s1 {
-  color: #2aa198;
-} // literal.string.single //
-.highlight .ss {
-  color: #2aa198;
-} // literal.string.symbol //
-.highlight .bp {
-  color: #268bd2;
-} // name.builtin.pseudo //
-.highlight .vc {
-  color: #268bd2;
-} // name.variable.class //
-.highlight .vg {
-  color: #268bd2;
-} // name.variable.global //
-.highlight .vi {
-  color: #268bd2;
-} // name.variable.instance //
-.highlight .il {
-  color: #2aa198;
-} // literal.number.integer.long //

_sass/custom/custom.scss

@@ -1,4 +1 @@
-$pink-000: #f77ef1;
+// custom SCSS (or CSS) goes here
-$pink-100: #f967f1;
-$pink-200: #e94ee1;
-$pink-300: #dd2cd4;

_sass/custom/setup.scss

@@ -0,0 +1 @@
+// custom setup code goes here

_sass/labels.scss

@@ -1,12 +1,13 @@
 // Labels (not the form kind)
 
-.label,
+// this :not() prevents a style clash with Mermaid.js's
-.label-blue {
+// diagram labels, which also use .label
+// for more, see https://github.com/just-the-docs/just-the-docs/issues/1272
+// and the accompanying PR
+.label:not(g),
+.label-blue:not(g) {
   display: inline-block;
-  padding-top: 0.16em;
+  padding: 0.16em 0.56em;
-  padding-right: 0.56em;
-  padding-bottom: 0.16em;
-  padding-left: 0.56em;
   margin-right: $sp-2;
   margin-left: $sp-2;
   color: $white;
@@ -18,19 +19,19 @@
   border-radius: 12px;
 }
 
-.label-green {
+.label-green:not(g) {
   background-color: $green-200;
 }
 
-.label-purple {
+.label-purple:not(g) {
   background-color: $purple-100;
 }
 
-.label-red {
+.label-red:not(g) {
   background-color: $red-200;
 }
 
-.label-yellow {
+.label-yellow:not(g) {
   color: $grey-dk-200;
   background-color: $yellow-200;
 }

_sass/layout.scss

@@ -7,11 +7,10 @@
   background-color: $sidebar-color;
 
   @include mq(md) {
-    flex-wrap: nowrap;
+    flex-flow: column nowrap;
     position: fixed;
     width: $nav-width-md;
     height: 100%;
-    flex-direction: column;
     border-right: $border $border-color;
     align-items: flex-end;
   }
@@ -30,9 +29,13 @@
   }
 
   @include mq(lg) {
-    margin-left: calc(
+    // stylelint-disable function-name-case
-      (100% - #{$nav-width + $content-width}) / 2 + #{$nav-width}
+    // 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
   }
 }
 

_sass/modules.scss

@@ -14,3 +14,4 @@
 @import "./code";
 @import "./utilities/utilities";
 @import "./print";
+@import "./skiptomain";

_sass/navigation.scss

@@ -73,19 +73,13 @@
 
       width: $nav-list-item-height-sm;
       height: $nav-list-item-height-sm;
-      padding-top: #{$nav-list-item-height-sm / 4};
+      padding: #{$nav-list-item-height-sm * 0.25};
-      padding-right: #{$nav-list-item-height-sm / 4};
-      padding-bottom: #{$nav-list-item-height-sm / 4};
-      padding-left: #{$nav-list-item-height-sm / 4};
       color: $link-color;
 
       @include mq(md) {
         width: $nav-list-item-height;
         height: $nav-list-item-height;
-        padding-top: #{$nav-list-item-height / 4};
+        padding: #{$nav-list-item-height * 0.25};
-        padding-right: #{$nav-list-item-height / 4};
-        padding-bottom: #{$nav-list-item-height / 4};
-        padding-left: #{$nav-list-item-height / 4};
       }
 
       &:hover {
@@ -138,10 +132,7 @@
 }
 
 .nav-category {
-  padding-top: $sp-2;
+  padding: $sp-2 $gutter-spacing-sm;
-  padding-right: $gutter-spacing-sm;
-  padding-bottom: $sp-2;
-  padding-left: $gutter-spacing-sm;
   font-weight: 600;
   text-align: start;
   text-transform: uppercase;
@@ -149,8 +140,7 @@
   @include fs-2;
 
   @include mq(md) {
-    padding-right: $gutter-spacing;
+    padding: $sp-2 $gutter-spacing;
-    padding-left: $gutter-spacing;
     margin-top: $gutter-spacing-sm;
     text-align: start;
 

_sass/print.scss

@@ -21,7 +21,7 @@
   }
 
   .site-title {
-    font-size: $root-font-size !important;
+    font-size: 1rem !important;
     font-weight: 700 !important;
   }
 

_sass/search.scss

@@ -6,7 +6,7 @@
   flex-grow: 1;
   height: $sp-10;
   padding: $sp-2;
-  transition: padding linear #{$transition-duration / 2};
+  transition: padding linear #{$transition-duration * 0.5};
 
   @include mq(md) {
     position: relative !important;
@@ -23,8 +23,10 @@
   height: $sp-8;
   overflow: hidden;
   border-radius: $border-radius;
-  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
+  box-shadow:
-  transition: height linear #{$transition-duration / 2};
+    0 1px 2px rgba(0, 0, 0, 0.12),
+    0 3px 10px rgba(0, 0, 0, 0.08);
+  transition: height linear #{$transition-duration * 0.5};
 
   @include mq(md) {
     position: absolute;
@@ -41,11 +43,8 @@
   position: absolute;
   width: 100%;
   height: 100%;
-  padding-top: $sp-2;
+  padding: $sp-2 $gutter-spacing-sm $sp-2 #{$gutter-spacing-sm + $sp-5};
-  padding-right: $gutter-spacing-sm;
+  font-size: 1rem;
-  padding-bottom: $sp-2;
-  padding-left: #{$gutter-spacing-sm + $sp-5};
-  font-size: 16px;
   color: $body-text-color;
   background-color: $search-background-color;
   border-top: 0;
@@ -55,12 +54,10 @@
   border-radius: 0;
 
   @include mq(md) {
-    padding-top: $gutter-spacing-sm;
+    padding: $sp-2 $gutter-spacing-sm $sp-2 #{$gutter-spacing + $sp-5};
-    padding-bottom: $gutter-spacing-sm;
+    font-size: 0.875rem;
-    padding-left: #{$gutter-spacing + $sp-5};
-    font-size: 14px;
     background-color: $body-background-color;
-    transition: padding-left linear #{$transition-duration / 2};
+    transition: padding-left linear #{$transition-duration * 0.5};
   }
 
   &:focus {
@@ -80,7 +77,7 @@
 
   @include mq(md) {
     padding-left: $gutter-spacing;
-    transition: padding-left linear #{$transition-duration / 2};
+    transition: padding-left linear #{$transition-duration * 0.5};
   }
 
   .search-icon {
@@ -101,7 +98,9 @@
   background-color: $search-background-color;
   border-bottom-right-radius: $border-radius;
   border-bottom-left-radius: $border-radius;
-  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
+  box-shadow:
+    0 1px 2px rgba(0, 0, 0, 0.12),
+    0 3px 10px rgba(0, 0, 0, 0.08);
 
   @include mq(md) {
     top: 100%;
@@ -128,10 +127,7 @@
 
 .search-result {
   display: block;
-  padding-top: $sp-1;
+  padding: $sp-1 $sp-3;
-  padding-right: $sp-3;
-  padding-bottom: $sp-1;
-  padding-left: $sp-3;
 
   &:hover,
   &.active {
@@ -224,10 +220,7 @@
 }
 
 .search-no-result {
-  padding-top: $sp-2;
+  padding: $sp-2 $sp-3;
-  padding-right: $sp-3;
-  padding-bottom: $sp-2;
-  padding-left: $sp-3;
   @include fs-3;
 }
 
@@ -240,8 +233,10 @@
   height: $sp-9;
   background-color: $search-background-color;
   border: 1px solid rgba($link-color, 0.3);
-  border-radius: #{$sp-9 / 2};
+  border-radius: #{$sp-9 * 0.5};
-  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
+  box-shadow:
+    0 1px 2px rgba(0, 0, 0, 0.12),
+    0 3px 10px rgba(0, 0, 0, 0.08);
   align-items: center;
   justify-content: center;
 }
@@ -255,7 +250,9 @@
   height: 0;
   background-color: rgba(0, 0, 0, 0.3);
   opacity: 0;
-  transition: opacity ease $transition-duration, width 0s $transition-duration,
+  transition:
+    opacity ease $transition-duration,
+    width 0s $transition-duration,
     height 0s $transition-duration;
 }
 
@@ -275,7 +272,9 @@
 
     @include mq(md) {
       width: $search-results-width;
-      box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
+      box-shadow:
+        0 1px 2px rgba(0, 0, 0, 0.12),
+        0 3px 10px rgba(0, 0, 0, 0.08);
     }
   }
 
@@ -301,7 +300,10 @@
     width: 100%;
     height: 100%;
     opacity: 1;
-    transition: opacity ease $transition-duration, width 0s, height 0s;
+    transition:
+      opacity ease $transition-duration,
+      width 0s,
+      height 0s;
   }
 
   @include mq(md) {

_sass/skiptomain.scss

@@ -0,0 +1,30 @@
+// Skipnav
+// Skip to main content
+
+a.skip-to-main {
+  left: -999px;
+  position: absolute;
+  top: auto;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  z-index: -999;
+}
+
+a.skip-to-main:focus,
+a.skip-to-main:active {
+  color: $link-color;
+  background-color: $body-background-color;
+  left: auto;
+  top: auto;
+  width: 30%;
+  height: auto;
+  overflow: auto;
+  margin: 10px 35%;
+  padding: 5px;
+  border-radius: 15px;
+  border: 4px solid $btn-primary-color;
+  text-align: center;
+  font-size: 1.2em;
+  z-index: 999;
+}

_sass/support/_functions.scss

@@ -1,9 +0,0 @@
-@function rem($size, $unit: "") {
-  $rem-size: $size / $root-font-size;
-
-  @if $unit == false {
-    @return #{$rem-size};
-  } @else {
-    @return #{$rem-size}rem;
-  }
-}

_sass/support/_variables.scss

@@ -1,9 +1,10 @@
 // Typography
 
+// prettier-ignore
 $body-font-family: system-ui, -apple-system, blinkmacsystemfont, "Segoe UI",
-  roboto, "Helvetica Neue", arial, sans-serif !default;
+  roboto, "Helvetica Neue", arial, sans-serif, "Segoe UI Emoji" !default;
 $mono-font-family: "SFMono-Regular", menlo, consolas, monospace !default;
-$root-font-size: 16px !default; // Base font-size for rems
+$root-font-size: 16px !default; // DEPRECATED: previously base font-size for rems
 $body-line-height: 1.4 !default;
 $content-line-height: 1.6 !default;
 $body-heading-line-height: 1.25 !default;
@@ -11,18 +12,18 @@ $body-heading-line-height: 1.25 !default;
 // Font size
 // `-sm` suffix is the size at the small (and above) media query
 
-$font-size-1: 9px !default;
+$font-size-1: 0.5625rem !default;
-$font-size-1-sm: 10px !default;
+$font-size-1-sm: 0.625rem !default;
-$font-size-2: 11px !default; // h4 - uppercased!, h6 not uppercased, text-small
+$font-size-2: 0.6875rem !default; // h4 - uppercased!, h6 not uppercased, text-small
-$font-size-3: 12px !default; // h5
+$font-size-3: 0.75rem !default; // h5
-$font-size-4: 14px !default;
+$font-size-4: 0.875rem !default;
-$font-size-5: 16px !default; // h3
+$font-size-5: 1rem !default; // h3
-$font-size-6: 18px !default; // h2
+$font-size-6: 1.125rem !default; // h2
-$font-size-7: 24px !default;
+$font-size-7: 1.5rem !default;
-$font-size-8: 32px !default; // h1
+$font-size-8: 2rem !default; // h1
-$font-size-9: 36px !default;
+$font-size-9: 2.25rem !default;
-$font-size-10: 42px !default;
+$font-size-10: 2.625rem !default;
-$font-size-10-sm: 48px !default;
+$font-size-10-sm: 3rem !default;
 
 // Colors
 
@@ -56,19 +57,6 @@ $red-000: #f77e7e !default;
 $red-100: #f96e65 !default;
 $red-200: #e94c4c !default;
 $red-300: #dd2e2e !default;
-$body-background-color: $white !default;
-$sidebar-color: $grey-lt-000 !default;
-$search-background-color: $white !default;
-$table-background-color: $white !default;
-$code-background-color: $grey-lt-000 !default;
-$feedback-color: darken($sidebar-color, 3%) !default;
-$body-text-color: $grey-dk-100 !default;
-$body-heading-color: $grey-dk-300 !default;
-$search-result-preview-color: $grey-dk-000 !default;
-$nav-child-link-color: $grey-dk-100 !default;
-$link-color: $purple-000 !default;
-$btn-primary-color: $purple-100 !default;
-$base-button-color: #f7f7f7 !default;
 
 // Spacing
 
@@ -108,22 +96,22 @@ $border-color: $grey-lt-100 !default;
 
 $gutter-spacing: $sp-6 !default;
 $gutter-spacing-sm: $sp-4 !default;
-$nav-width: 264px !default;
+$nav-width: 16.5rem !default;
-$nav-width-md: 248px !default;
+$nav-width-md: 15.5rem !default;
 $nav-list-item-height: $sp-6 !default;
 $nav-list-item-height-sm: $sp-8 !default;
 $nav-list-expander-right: true;
-$content-width: 800px !default;
+$content-width: 50rem !default;
-$header-height: 60px !default;
+$header-height: 3.75rem !default;
 $search-results-width: $content-width - $nav-width !default;
 $transition-duration: 400ms;
 
 // Media queries in pixels
 
 $media-queries: (
-  xs: 320px,
+  xs: 20rem,
-  sm: 500px,
+  sm: 31.25rem,
   md: $content-width,
   lg: $content-width + $nav-width,
-  xl: 1400px,
+  xl: 87.5rem,
 ) !default;

_sass/support/mixins/_buttons.scss

@@ -4,7 +4,9 @@
   color: $fg;
   background-color: darken($bg, 2%);
   background-image: linear-gradient(lighten($bg, 5%), darken($bg, 2%));
-  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.25), 0 4px 10px rgba(0, 0, 0, 0.12);
+  box-shadow:
+    0 1px 3px rgba(0, 0, 0, 0.25),
+    0 4px 10px rgba(0, 0, 0, 0.12);
 
   &:hover,
   &.zeroclipboard-is-hover {

_sass/support/mixins/_layout.scss

@@ -12,12 +12,11 @@
   // If the key exists in the map
   @if $value {
     // Prints a media query based on the value
-    @media (min-width: rem($value)) {
+    @media (min-width: $value) {
       @content;
     }
   } @else {
-    @warn "No value could be retrieved from `#{$media-query}`. "
+    @warn "No value could be retrieved from `#{$media-query}`. Please make sure it is defined in `$media-queries` map.";
-      + "Please make sure it is defined in `$media-queries` map.";
   }
 }
 

_sass/support/support.scss

@@ -1,3 +1,2 @@
 @import "./variables";
-@import "./functions";
 @import "./mixins/mixins";

_sass/tables.scss

@@ -8,7 +8,9 @@
   margin-bottom: $sp-5;
   overflow-x: auto;
   border-radius: $border-radius;
-  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
+  box-shadow:
+    0 1px 2px rgba(0, 0, 0, 0.12),
+    0 3px 10px rgba(0, 0, 0, 0.08);
 }
 
 table {
@@ -21,11 +23,8 @@ th,
 td {
   @include fs-3;
 
-  min-width: 120px;
+  min-width: 7.5rem;
-  padding-top: $sp-2;
+  padding: $sp-2 $sp-3;
-  padding-right: $sp-3;
-  padding-bottom: $sp-2;
-  padding-left: $sp-3;
   background-color: $table-background-color;
   border-bottom: $border rgba($border-color, 0.5);
   border-left: $border $border-color;

_sass/typography.scss

@@ -1,5 +1,4 @@
 // Typography
-
 // stylelint-disable selector-no-type, selector-max-type, selector-max-specificity, selector-max-id
 
 h1,

_sass/vendor/OneDarkJekyll/README.md

@@ -1,25 +0,0 @@
-# OneDarkJekyll
-
-*Use Atom's One Dark syntax colors in your Jekyll powered blog!*
-
-It's LESS file which can be compiled to a - Pygments, Rouge compatible - stylesheet from Atom editor's One Dark syntax theme (and any theme based on it, for example One Dark Vivid, Firewatch, etc.).
-
-Download the stylesheet files or compile a new one from any Atom syntax theme which based on One Dark (the variable names in `colors.less` must match with One Dark's)
-
-## Create a new syntax stylesheet
-
-1. `npm install -g less less-plugin-clean-css`
-2. Clone this repository
-3. Download the `colors.css` file from the syntax theme's repository (for example https://github.com/atom/one-dark-syntax/blob/master/styles/colors.less in case of One-Dark)
-4. Put the previously downloaded file next to `syntax.less`
-5. Run `lessc syntax.less syntax.css --clean-css`
-6. Use the `syntax.css`
-
-It's not final and in case you find any error/improvement feel free to create a PR. :)
-
-----
-
-# UPDATES FOR USE IN JUST-THE-DOCS:
-
-1. Layout added in `*.css`
-2. Renamed `*.css` to `*.scss`

_sass/vendor/OneDarkJekyll/colors.less

@@ -1,30 +0,0 @@
-// Config -----------------------------------
-@syntax-hue:          220;
-@syntax-saturation:   13%;
-@syntax-brightness:   18%;
-
-
-// Monochrome -----------------------------------
-@mono-1: hsl(@syntax-hue, 14%, 71%); // default text
-@mono-2: hsl(@syntax-hue,  9%, 55%);
-@mono-3: hsl(@syntax-hue, 10%, 40%);
-
-// Colors -----------------------------------
-@hue-1:   hsl(187, 47%, 55%); // <-cyan
-@hue-2:   hsl(207, 82%, 66%); // <-blue
-@hue-3:   hsl(286, 60%, 67%); // <-purple
-@hue-4:   hsl( 95, 38%, 62%); // <-green
-
-@hue-5:   hsl(355, 65%, 65%); // <-red 1
-@hue-5-2: hsl(  5, 48%, 51%); // <-red 2
-
-@hue-6:   hsl( 29, 54%, 61%); // <-orange 1
-@hue-6-2: hsl( 39, 67%, 69%); // <-orange 2
-
-
-// Base colors -----------------------------------
-@syntax-fg:     @mono-1;
-@syntax-bg:     hsl(@syntax-hue, @syntax-saturation, @syntax-brightness);
-@syntax-gutter: darken(@syntax-fg, 26%);
-@syntax-guide:  fade(@syntax-fg, 15%);
-@syntax-accent: hsl(@syntax-hue, 100%, 66% );

_sass/vendor/OneDarkJekyll/syntax-firewatch.scss

@@ -1,200 +0,0 @@
-.highlight,
-pre.highlight {
-  background: #282c34;
-  color: #abb2bf;
-}
-.highlight pre {
-  background: #282c34;
-}
-.highlight .hll {
-  background: #282c34;
-}
-.highlight .c {
-  color: #5c6370;
-  font-style: italic;
-}
-.highlight .err {
-  color: #960050;
-  background-color: #1e0010;
-}
-.highlight .k {
-  color: #dd672c;
-}
-.highlight .l {
-  color: #c8ae9d;
-}
-.highlight .n {
-  color: #abb2bf;
-}
-.highlight .o {
-  color: #abb2bf;
-}
-.highlight .p {
-  color: #abb2bf;
-}
-.highlight .cm {
-  color: #5c6370;
-  font-style: italic;
-}
-.highlight .cp {
-  color: #5c6370;
-  font-style: italic;
-}
-.highlight .c1 {
-  color: #5c6370;
-  font-style: italic;
-}
-.highlight .cs {
-  color: #5c6370;
-  font-style: italic;
-}
-.highlight .ge {
-  font-style: italic;
-}
-.highlight .gs {
-  font-weight: 700;
-}
-.highlight .kc {
-  color: #dd672c;
-}
-.highlight .kd {
-  color: #dd672c;
-}
-.highlight .kn {
-  color: #dd672c;
-}
-.highlight .kp {
-  color: #dd672c;
-}
-.highlight .kr {
-  color: #dd672c;
-}
-.highlight .kt {
-  color: #dd672c;
-}
-.highlight .ld {
-  color: #c8ae9d;
-}
-.highlight .m {
-  color: #d19a66;
-}
-.highlight .s {
-  color: #c8ae9d;
-}
-.highlight .na {
-  color: #d19a66;
-}
-.highlight .nb {
-  color: #e5c07b;
-}
-.highlight .nc {
-  color: #e5c07b;
-}
-.highlight .no {
-  color: #e5c07b;
-}
-.highlight .nd {
-  color: #e5c07b;
-}
-.highlight .ni {
-  color: #e5c07b;
-}
-.highlight .ne {
-  color: #e5c07b;
-}
-.highlight .nf {
-  color: #abb2bf;
-}
-.highlight .nl {
-  color: #e5c07b;
-}
-.highlight .nn {
-  color: #abb2bf;
-}
-.highlight .nx {
-  color: #abb2bf;
-}
-.highlight .py {
-  color: #e5c07b;
-}
-.highlight .nt {
-  color: #e06c75;
-}
-.highlight .nv {
-  color: #e5c07b;
-}
-.highlight .ow {
-  font-weight: 700;
-}
-.highlight .w {
-  color: #f8f8f2;
-}
-.highlight .mf {
-  color: #d19a66;
-}
-.highlight .mh {
-  color: #d19a66;
-}
-.highlight .mi {
-  color: #d19a66;
-}
-.highlight .mo {
-  color: #d19a66;
-}
-.highlight .sb {
-  color: #c8ae9d;
-}
-.highlight .sc {
-  color: #c8ae9d;
-}
-.highlight .sd {
-  color: #c8ae9d;
-}
-.highlight .s2 {
-  color: #c8ae9d;
-}
-.highlight .se {
-  color: #c8ae9d;
-}
-.highlight .sh {
-  color: #c8ae9d;
-}
-.highlight .si {
-  color: #c8ae9d;
-}
-.highlight .sx {
-  color: #c8ae9d;
-}
-.highlight .sr {
-  color: #56b6c2;
-}
-.highlight .s1 {
-  color: #c8ae9d;
-}
-.highlight .ss {
-  color: #56b6c2;
-}
-.highlight .bp {
-  color: #e5c07b;
-}
-.highlight .vc {
-  color: #e5c07b;
-}
-.highlight .vg {
-  color: #e5c07b;
-}
-.highlight .vi {
-  color: #e06c75;
-}
-.highlight .il {
-  color: #d19a66;
-}
-.highlight .gu {
-  color: #75715e;
-}
-.highlight .gd {
-  color: #f92672;
-}
-.highlight .gi {
-  color: #a6e22e;
-}

_sass/vendor/OneDarkJekyll/syntax-one-dark.scss

@@ -1,200 +0,0 @@
-.highlight,
-pre.highlight {
-  background: #282c34;
-  color: #abb2bf;
-}
-.highlight pre {
-  background: #282c34;
-}
-.highlight .hll {
-  background: #282c34;
-}
-.highlight .c {
-  color: #5c6370;
-  font-style: italic;
-}
-.highlight .err {
-  color: #960050;
-  background-color: #1e0010;
-}
-.highlight .k {
-  color: #c678dd;
-}
-.highlight .l {
-  color: #98c379;
-}
-.highlight .n {
-  color: #abb2bf;
-}
-.highlight .o {
-  color: #abb2bf;
-}
-.highlight .p {
-  color: #abb2bf;
-}
-.highlight .cm {
-  color: #5c6370;
-  font-style: italic;
-}
-.highlight .cp {
-  color: #5c6370;
-  font-style: italic;
-}
-.highlight .c1 {
-  color: #5c6370;
-  font-style: italic;
-}
-.highlight .cs {
-  color: #5c6370;
-  font-style: italic;
-}
-.highlight .ge {
-  font-style: italic;
-}
-.highlight .gs {
-  font-weight: 700;
-}
-.highlight .kc {
-  color: #c678dd;
-}
-.highlight .kd {
-  color: #c678dd;
-}
-.highlight .kn {
-  color: #c678dd;
-}
-.highlight .kp {
-  color: #c678dd;
-}
-.highlight .kr {
-  color: #c678dd;
-}
-.highlight .kt {
-  color: #c678dd;
-}
-.highlight .ld {
-  color: #98c379;
-}
-.highlight .m {
-  color: #d19a66;
-}
-.highlight .s {
-  color: #98c379;
-}
-.highlight .na {
-  color: #d19a66;
-}
-.highlight .nb {
-  color: #e5c07b;
-}
-.highlight .nc {
-  color: #e5c07b;
-}
-.highlight .no {
-  color: #e5c07b;
-}
-.highlight .nd {
-  color: #e5c07b;
-}
-.highlight .ni {
-  color: #e5c07b;
-}
-.highlight .ne {
-  color: #e5c07b;
-}
-.highlight .nf {
-  color: #abb2bf;
-}
-.highlight .nl {
-  color: #e5c07b;
-}
-.highlight .nn {
-  color: #abb2bf;
-}
-.highlight .nx {
-  color: #abb2bf;
-}
-.highlight .py {
-  color: #e5c07b;
-}
-.highlight .nt {
-  color: #e06c75;
-}
-.highlight .nv {
-  color: #e5c07b;
-}
-.highlight .ow {
-  font-weight: 700;
-}
-.highlight .w {
-  color: #f8f8f2;
-}
-.highlight .mf {
-  color: #d19a66;
-}
-.highlight .mh {
-  color: #d19a66;
-}
-.highlight .mi {
-  color: #d19a66;
-}
-.highlight .mo {
-  color: #d19a66;
-}
-.highlight .sb {
-  color: #98c379;
-}
-.highlight .sc {
-  color: #98c379;
-}
-.highlight .sd {
-  color: #98c379;
-}
-.highlight .s2 {
-  color: #98c379;
-}
-.highlight .se {
-  color: #98c379;
-}
-.highlight .sh {
-  color: #98c379;
-}
-.highlight .si {
-  color: #98c379;
-}
-.highlight .sx {
-  color: #98c379;
-}
-.highlight .sr {
-  color: #56b6c2;
-}
-.highlight .s1 {
-  color: #98c379;
-}
-.highlight .ss {
-  color: #56b6c2;
-}
-.highlight .bp {
-  color: #e5c07b;
-}
-.highlight .vc {
-  color: #e5c07b;
-}
-.highlight .vg {
-  color: #e5c07b;
-}
-.highlight .vi {
-  color: #e06c75;
-}
-.highlight .il {
-  color: #d19a66;
-}
-.highlight .gu {
-  color: #75715e;
-}
-.highlight .gd {
-  color: #f92672;
-}
-.highlight .gi {
-  color: #a6e22e;
-}

_sass/vendor/OneDarkJekyll/syntax-variables.less

@@ -1,56 +0,0 @@
-@import "colors.less";
-
-// Official Syntax Variables -----------------------------------
-
-// General colors
-@syntax-text-color:            @syntax-fg;
-@syntax-cursor-color:          @syntax-accent;
-@syntax-selection-color:       lighten(@syntax-background-color, 10%);
-@syntax-selection-flash-color: @syntax-accent;
-@syntax-background-color:      @syntax-bg;
-
-// Guide colors
-@syntax-wrap-guide-color:          @syntax-guide;
-@syntax-indent-guide-color:        @syntax-guide;
-@syntax-invisible-character-color: @syntax-guide;
-
-// For find and replace markers
-@syntax-result-marker-color:          fade(@syntax-accent, 24%);
-@syntax-result-marker-color-selected: @syntax-accent;
-
-// Gutter colors
-@syntax-gutter-text-color:                @syntax-gutter;
-@syntax-gutter-text-color-selected:       @syntax-fg;
-@syntax-gutter-background-color:          @syntax-bg; // unused
-@syntax-gutter-background-color-selected: lighten(@syntax-bg, 2%);
-
-// Git colors - For git diff info. i.e. in the gutter
-@syntax-color-renamed:  hsl(208, 100%, 60%);
-@syntax-color-added:    hsl(150,  60%, 54%);
-@syntax-color-modified: hsl(40,   60%, 70%);
-@syntax-color-removed:  hsl(0,    70%, 60%);
-
-// For language entity colors
-@syntax-color-variable:   @hue-5;
-@syntax-color-constant:   @hue-6;
-@syntax-color-property:   @syntax-fg;
-@syntax-color-value:      @syntax-fg;
-@syntax-color-function:   @hue-2;
-@syntax-color-method:     @hue-2;
-@syntax-color-class:      @hue-6-2;
-@syntax-color-keyword:    @hue-3;
-@syntax-color-tag:        @hue-5;
-@syntax-color-attribute:  @hue-6;
-@syntax-color-import:     @hue-3;
-@syntax-color-snippet:    @hue-4;
-
-
-// Custom Syntax Variables -----------------------------------
-// Don't use in packages
-
-@syntax-cursor-line: hsla(@syntax-hue, 100%,  80%, .04); // needs to be semi-transparent to show search results
-
-@syntax-deprecated-fg: darken(@syntax-color-modified, 50%);
-@syntax-deprecated-bg: @syntax-color-modified;
-@syntax-illegal-fg:    white;
-@syntax-illegal-bg:    @syntax-color-removed;

_sass/vendor/OneDarkJekyll/syntax.less

@@ -1,93 +0,0 @@
-/*
-  LESS for Pygments
-*/
-
-@import "syntax-variables.less";
-
-pre.highlight,
-.highlight {
-  background: @syntax-bg;
-	color: @mono-1;
-}
-.highlight {
- pre { background: @syntax-bg; }
- .hll { background: @syntax-bg; }
- .c {  color: @mono-3; font-style: italic;  } /* Comment */
- .err { color: @syntax-illegal-fg; background-color: @syntax-illegal-bg; } /* Error */
- .k { color: @hue-3;  } /* Keyword */
- .l { color: @hue-4; } /* Literal */
- .n { color: @mono-1; } /* Name */
- .o { color: @mono-1; } /* Operator */
- .p { color: @mono-1; } /* Punctuation */
- .cm { color: @mono-3; font-style: italic; } /* Comment.Multiline */
- .cp { color: @mono-3; font-style: italic; } /* Comment.Preproc */
- .c1 { color: @mono-3; font-style: italic; } /* Comment.Single */
- .cs { color: @mono-3; font-style: italic; } /* Comment.Special */
- .ge { font-style: italic } /* Generic.Emph */
- .gs { font-weight: bold } /* Generic.Strong */
- .kc { color: @hue-3;  } /* Keyword.Constant */
- .kd { color: @hue-3;  } /* Keyword.Declaration */
- .kn { color: @hue-3;  } /* Keyword.Namespace */
- .kp { color: @hue-3;  } /* Keyword.Pseudo */
- .kr { color: @hue-3;  } /* Keyword.Reserved */
- .kt { color: @hue-3;  } /* Keyword.Type */
- .ld { color: @hue-4; } /* Literal.Date */
- .m { color: @hue-6; } /* Literal.Number */
- .s { color: @hue-4; } /* Literal.String */
- .na { color: @hue-6; } /* Name.Attribute */
- .nb { color: @hue-6-2; } /* Name.Builtin */
- .nc { color: @hue-6-2; } /* Name.Class */
- .no { color: @hue-6-2; } /* Name.Constant */
- .nd { color: @hue-6-2; } /* Name.Decorator */
- .ni { color: @hue-6-2; } /* Name.Entity */
- .ne { color: @hue-6-2; } /* Name.Exception */
- .nf { color: @mono-1; } /* Name.Function */
- .nl { color: @hue-6-2; } /* Name.Label */
- .nn { color: @mono-1; } /* Name.Namespace */
- .nx { color: @mono-1; } /* Name.Other */
- .py { color: @hue-6-2; } /* Name.Property */
- .nt { color: @hue-5; } /* Name.Tag */
- .nv { color: @hue-6-2; } /* Name.Variable */
- .ow { font-weight: bold; } /* Operator.Word */
- .w { color: #f8f8f2 } /* Text.Whitespace */
- .mf { color: @hue-6; } /* Literal.Number.Float */
- .mh { color: @hue-6; } /* Literal.Number.Hex */
- .mi { color: @hue-6; } /* Literal.Number.Integer */
- .mo { color: @hue-6; } /* Literal.Number.Oct */
- .sb { color: @hue-4; } /* Literal.String.Backtick */
- .sc { color: @hue-4; } /* Literal.String.Char */
- .sd { color: @hue-4; } /* Literal.String.Doc */
- .s2 { color: @hue-4; } /* Literal.String.Double */
- .se { color: @hue-4; } /* Literal.String.Escape */
- .sh { color: @hue-4; } /* Literal.String.Heredoc */
- .si { color: @hue-4; } /* Literal.String.Interpol */
- .sx { color: @hue-4; } /* Literal.String.Other */
- .sr { color: @hue-1; } /* Literal.String.Regex */
- .s1 { color: @hue-4; } /* Literal.String.Single */
- .ss { color: @hue-1; } /* Literal.String.Symbol */
- .bp { color: @hue-6-2; } /* Name.Builtin.Pseudo */
- .vc { color: @hue-6-2; } /* Name.Variable.Class */
- .vg { color: @hue-6-2; } /* Name.Variable.Global */
- .vi { color: @hue-5; } /* Name.Variable.Instance */
- .il { color: @hue-6; } /* Literal.Number.Integer.Long */
-
- .gh { } /* Generic Heading & Diff Header */
- .gu { color: #75715e; } /* Generic.Subheading & Diff Unified/Comment? */
- .gd { color: @syntax-color-removed; } /* Generic.Deleted & Diff Deleted */
- .gi { color: @syntax-color-added; } /* Generic.Inserted & Diff Inserted */
-	
- ::selection { background-color: @syntax-selection-color; }
-
- .language-json {
-   .w + .s2 { color: @hue-5; }
-   .kc { color: @hue-1; }
- }
-
- .language-python {
-   // python related modifications
- }
-
- .language-csharp {
-   // csharp related modifications
- }
-}

_sass/vendor/OneDarkJekyll/syntax.scss

@@ -1,3 +1,5 @@
+// Generated with OneDarkJekyll applied to Atom's One Dark Vivid theme
+
 .highlight,
 pre.highlight {
   background: #31343f;

_sass/vendor/OneLightJekyll/LICENSE

@@ -0,0 +1,65 @@
+OneLightJekyll relies on two works: OneDarkJekyll, and Atom's One Light theme. This file contains the licensing for all the related software.
+
+---
+
+OneLightJekyll (https://github.com/just-the-docs/OneLightJekyll/blob/main/LICENSE)
+
+MIT License
+
+Copyright (c) 2023 Matthew Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+OneDarkJekyll (https://github.com/mgyongyosi/OneDarkJekyll/blob/master/LICENSE)
+
+MIT License
+
+Copyright (c) 2016 Mihály Gyöngyösi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Atom One Light (https://github.com/atom/atom/blob/master/LICENSE.md)
+
+Copyright (c) 2011-2022 GitHub Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

_sass/vendor/OneLightJekyll/syntax.scss

@@ -1,51 +1,53 @@
+// Generated with OneLightJekyll applied to Atom's One Light theme
+
 .highlight,
 pre.highlight {
-  background: #282c34;
+  background: #f9f9f9;
-  color: #abb2bf;
+  color: #383942;
 }
 .highlight pre {
-  background: #282c34;
+  background: #f9f9f9;
 }
 .highlight .hll {
-  background: #282c34;
+  background: #f9f9f9;
 }
 .highlight .c {
-  color: #5c6370;
+  color: #9fa0a6;
   font-style: italic;
 }
 .highlight .err {
-  color: #960050;
+  color: #fff;
-  background-color: #1e0010;
+  background-color: #e05151;
 }
 .highlight .k {
-  color: #5ba473;
+  color: #a625a4;
 }
 .highlight .l {
-  color: #c8ae9d;
+  color: #50a04f;
 }
 .highlight .n {
-  color: #abb2bf;
+  color: #383942;
 }
 .highlight .o {
-  color: #abb2bf;
+  color: #383942;
 }
 .highlight .p {
-  color: #abb2bf;
+  color: #383942;
 }
 .highlight .cm {
-  color: #5c6370;
+  color: #9fa0a6;
   font-style: italic;
 }
 .highlight .cp {
-  color: #5c6370;
+  color: #9fa0a6;
   font-style: italic;
 }
 .highlight .c1 {
-  color: #5c6370;
+  color: #9fa0a6;
   font-style: italic;
 }
 .highlight .cs {
-  color: #5c6370;
+  color: #9fa0a6;
   font-style: italic;
 }
 .highlight .ge {
@@ -55,73 +57,73 @@ pre.highlight {
   font-weight: 700;
 }
 .highlight .kc {
-  color: #5ba473;
+  color: #a625a4;
 }
 .highlight .kd {
-  color: #5ba473;
+  color: #a625a4;
 }
 .highlight .kn {
-  color: #5ba473;
+  color: #a625a4;
 }
 .highlight .kp {
-  color: #5ba473;
+  color: #a625a4;
 }
 .highlight .kr {
-  color: #5ba473;
+  color: #a625a4;
 }
 .highlight .kt {
-  color: #5ba473;
+  color: #a625a4;
 }
 .highlight .ld {
-  color: #c8ae9d;
+  color: #50a04f;
 }
 .highlight .m {
-  color: #d19a66;
+  color: #b66a00;
 }
 .highlight .s {
-  color: #c8ae9d;
+  color: #50a04f;
 }
 .highlight .na {
-  color: #d19a66;
+  color: #b66a00;
 }
 .highlight .nb {
-  color: #e5c07b;
+  color: #ca7601;
 }
 .highlight .nc {
-  color: #e5c07b;
+  color: #ca7601;
 }
 .highlight .no {
-  color: #e5c07b;
+  color: #ca7601;
 }
 .highlight .nd {
-  color: #e5c07b;
+  color: #ca7601;
 }
 .highlight .ni {
-  color: #e5c07b;
+  color: #ca7601;
 }
 .highlight .ne {
-  color: #e5c07b;
+  color: #ca7601;
 }
 .highlight .nf {
-  color: #abb2bf;
+  color: #383942;
 }
 .highlight .nl {
-  color: #e5c07b;
+  color: #ca7601;
 }
 .highlight .nn {
-  color: #abb2bf;
+  color: #383942;
 }
 .highlight .nx {
-  color: #abb2bf;
+  color: #383942;
 }
 .highlight .py {
-  color: #e5c07b;
+  color: #ca7601;
 }
 .highlight .nt {
-  color: #77b181;
+  color: #e35549;
 }
 .highlight .nv {
-  color: #e5c07b;
+  color: #ca7601;
 }
 .highlight .ow {
   font-weight: 700;
@@ -130,71 +132,77 @@ pre.highlight {
   color: #f8f8f2;
 }
 .highlight .mf {
-  color: #d19a66;
+  color: #b66a00;
 }
 .highlight .mh {
-  color: #d19a66;
+  color: #b66a00;
 }
 .highlight .mi {
-  color: #d19a66;
+  color: #b66a00;
 }
 .highlight .mo {
-  color: #d19a66;
+  color: #b66a00;
 }
 .highlight .sb {
-  color: #c8ae9d;
+  color: #50a04f;
 }
 .highlight .sc {
-  color: #c8ae9d;
+  color: #50a04f;
 }
 .highlight .sd {
-  color: #c8ae9d;
+  color: #50a04f;
 }
 .highlight .s2 {
-  color: #c8ae9d;
+  color: #50a04f;
 }
 .highlight .se {
-  color: #c8ae9d;
+  color: #50a04f;
 }
 .highlight .sh {
-  color: #c8ae9d;
+  color: #50a04f;
 }
 .highlight .si {
-  color: #c8ae9d;
+  color: #50a04f;
 }
 .highlight .sx {
-  color: #c8ae9d;
+  color: #50a04f;
 }
 .highlight .sr {
-  color: #56b6c2;
+  color: #0083bb;
 }
 .highlight .s1 {
-  color: #c8ae9d;
+  color: #50a04f;
 }
 .highlight .ss {
-  color: #56b6c2;
+  color: #0083bb;
 }
 .highlight .bp {
-  color: #e5c07b;
+  color: #ca7601;
 }
 .highlight .vc {
-  color: #e5c07b;
+  color: #ca7601;
 }
 .highlight .vg {
-  color: #e5c07b;
+  color: #ca7601;
 }
 .highlight .vi {
-  color: #77b181;
+  color: #e35549;
 }
 .highlight .il {
-  color: #d19a66;
+  color: #b66a00;
 }
 .highlight .gu {
   color: #75715e;
 }
 .highlight .gd {
-  color: #f92672;
+  color: #e05151;
 }
 .highlight .gi {
-  color: #a6e22e;
+  color: #43d089;
+}
+.highlight .language-json .w + .s2 {
+  color: #e35549;
+}
+.highlight .language-json .kc {
+  color: #0083bb;
 }

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

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

assets/images/search.svg

@@ -1 +0,0 @@
-<svg width="28" height="28" viewBox="0 0 28 28" xmlns="http://www.w3.org/2000/svg"><title>Search</title><g fill-rule="nonzero" fill="#959396"><path d="M17.332 20.735c-5.537 0-10-4.6-10-10.247 0-5.646 4.463-10.247 10-10.247 5.536 0 10 4.601 10 10.247s-4.464 10.247-10 10.247zm0-4c3.3 0 6-2.783 6-6.247 0-3.463-2.7-6.247-6-6.247s-6 2.784-6 6.247c0 3.464 2.7 6.247 6 6.247z"/><path d="M11.672 13.791L.192 25.271 3.02 28.1 14.5 16.62z"/></g></svg>

assets/js/just-the-docs.js

@@ -31,7 +31,7 @@ function initNav() {
     }
     if (target) {
       e.preventDefault();
-      target.parentNode.classList.toggle('active');
+      target.ariaPressed = target.parentNode.classList.toggle('active');
     }
   });
 
@@ -39,15 +39,19 @@ function initNav() {
   const mainHeader = document.getElementById('main-header');
   const menuButton = document.getElementById('menu-button');
 
+  disableHeadStyleSheets();
+
   jtd.addEvent(menuButton, 'click', function(e){
     e.preventDefault();
 
     if (menuButton.classList.toggle('nav-open')) {
       siteNav.classList.add('nav-open');
       mainHeader.classList.add('nav-open');
+      menuButton.ariaPressed = true;
     } else {
       siteNav.classList.remove('nav-open');
       mainHeader.classList.remove('nav-open');
+      menuButton.ariaPressed = false;
     }
   });
 
@@ -64,6 +68,26 @@ function initNav() {
   {%- endif %}
 }
 
+// The <head> element is assumed to include the following stylesheets:
+// - a <link> to /assets/css/just-the-docs-head-nav.css,
+//             with id 'jtd-head-nav-stylesheet'
+// - a <style> containing the result of _includes/css/activation.scss.liquid.
+// To avoid relying on the order of stylesheets (which can change with HTML
+// compression, user-added JavaScript, and other side effects), stylesheets
+// are only interacted with via ID
+
+function disableHeadStyleSheets() {
+  const headNav = document.getElementById('jtd-head-nav-stylesheet');
+  if (headNav) {
+    headNav.disabled = true;
+  }
+
+  const activation = document.getElementById('jtd-nav-activation');
+  if (activation) {
+    activation.disabled = true;
+  }
+}
+
 {%- if site.search_enabled != false %}
 // Site search
 
@@ -87,6 +111,7 @@ function initSearch() {
         this.metadataWhitelist = ['position']
 
         for (var i in docs) {
+          {% include lunr/custom-index.js %}
           this.add({
             id: i,
             title: docs[i].title,
@@ -120,6 +145,18 @@ function searchLoaded(index, docs) {
   var currentInput;
   var currentSearchIndex = 0;
 
+  {%- if site.search.focus_shortcut_key %}
+  // add event listener on ctrl + <focus_shortcut_key> for showing the search input
+  jtd.addEvent(document, 'keydown', function (e) {
+    if ((e.ctrlKey || e.metaKey) && e.key === '{{ site.search.focus_shortcut_key }}') {
+      e.preventDefault();
+
+      mainHeader.classList.add('nav-open');
+      searchInput.focus();
+    }
+  });
+  {%- endif %}
+
   function showSearch() {
     document.documentElement.classList.add('search-active');
   }
@@ -217,6 +254,7 @@ function searchLoaded(index, docs) {
       resultTitle.classList.add('search-result-title');
       resultLink.appendChild(resultTitle);
 
+      // note: the SVG svg-doc is only loaded as a Jekyll include if site.search_enabled is true; see _includes/icons/icons.html
       var resultDoc = document.createElement('div');
       resultDoc.classList.add('search-result-doc');
       resultDoc.innerHTML = '<svg viewBox="0 0 24 24" class="search-result-icon"><use xlink:href="#svg-doc"></use></svg>';
@@ -457,15 +495,60 @@ jtd.setTheme = function(theme) {
   cssFile.setAttribute('href', '{{ "assets/css/just-the-docs-" | relative_url }}' + theme + '.css');
 }
 
+// Note: pathname can have a trailing slash on a local jekyll server
+// and not have the slash on GitHub Pages
+
+function navLink() {
+  var pathname = document.location.pathname;
+
+  var navLink = document.getElementById('site-nav').querySelector('a[href="' + pathname + '"]');
+  if (navLink) {
+    return navLink;
+  }
+
+  // The `permalink` setting may produce navigation links whose `href` ends with `/` or `.html`.
+  // To find these links when `/` is omitted from or added to pathname, or `.html` is omitted:
+
+  if (pathname.endsWith('/') && pathname != '/') {
+    pathname = pathname.slice(0, -1);
+  }
+
+  if (pathname != '/') {
+    navLink = document.getElementById('site-nav').querySelector('a[href="' + pathname + '"], a[href="' + pathname + '/"], a[href="' + pathname + '.html"]');
+    if (navLink) {
+      return navLink;
+    }
+  }
+
+  return null; // avoids `undefined`
+}
+
 // Scroll site-nav to ensure the link to the current page is visible
 
 function scrollNav() {
-  const href = document.location.pathname;
+  const targetLink = navLink();
-  const siteNav = document.getElementById('site-nav');
-  const targetLink = siteNav.querySelector('a[href="' + href + '"], a[href="' + href + '/"]');
   if (targetLink) {
-    const rect = targetLink.getBoundingClientRect();
+    targetLink.scrollIntoView({ block: "center" });
-    siteNav.scrollBy(0, rect.top - 3*rect.height);
+    targetLink.removeAttribute('href');
+  }
+}
+
+// Find the nav-list-link that refers to the current page
+// then make it and all enclosing nav-list-item elements active.
+
+function activateNav() {
+  var target = navLink();
+  if (target) {
+    target.classList.toggle('active', true);
+  }
+  while (target) {
+    while (target && !(target.classList && target.classList.contains('nav-list-item'))) {
+      target = target.parentNode;
+    }
+    if (target) {
+      target.classList.toggle('active', true);
+      target = target.parentNode;
+    }
   }
 }
 
@@ -476,9 +559,57 @@ jtd.onReady(function(){
   {%- if site.search_enabled != false %}
   initSearch();
   {%- endif %}
+  activateNav();
   scrollNav();
 });
 
+// Copy button on code
+
+
+{%- if site.enable_copy_code_button != false %}
+
+jtd.onReady(function(){
+
+  if (!window.isSecureContext) {
+    console.log('Window does not have a secure context, therefore code clipboard copy functionality will not be available. For more details see https://web.dev/async-clipboard/#security-and-permissions');
+    return;
+  }
+
+  var codeBlocks = document.querySelectorAll('div.highlighter-rouge, div.listingblock > div.content, figure.highlight');
+
+  // note: the SVG svg-copied and svg-copy is only loaded as a Jekyll include if site.enable_copy_code_button is true; see _includes/icons/icons.html
+  var svgCopied =  '<svg viewBox="0 0 24 24" class="copy-icon"><use xlink:href="#svg-copied"></use></svg>';
+  var svgCopy =  '<svg viewBox="0 0 24 24" class="copy-icon"><use xlink:href="#svg-copy"></use></svg>';
+
+  codeBlocks.forEach(codeBlock => {
+    var copyButton = document.createElement('button');
+    var timeout = null;
+    copyButton.type = 'button';
+    copyButton.ariaLabel = 'Copy code to clipboard';
+    copyButton.innerHTML = svgCopy;
+    codeBlock.append(copyButton);
+
+    copyButton.addEventListener('click', function () {
+      if(timeout === null) {
+        var code = (codeBlock.querySelector('pre:not(.lineno, .highlight)') || codeBlock.querySelector('code')).innerText;
+        window.navigator.clipboard.writeText(code);
+
+        copyButton.innerHTML = svgCopied;
+
+        var timeoutSetting = 4000;
+
+        timeout = setTimeout(function () {
+          copyButton.innerHTML = svgCopy;
+          timeout = null;
+        }, timeoutSetting);
+      }
+    });
+  });
+
+});
+
+{%- endif %}
+
 })(window.jtd = window.jtd || {});
 
 {% include js/custom.js %}

assets/js/zzzz-search-data.json

@@ -51,6 +51,7 @@ permalink: /assets/js/search-data.json
     "title": {{ title | jsonify }},
     "content": {{ content | replace: '</h', ' . </h' | replace: '<hr', ' . <hr' | replace: '</p', ' . </p' | replace: '<ul', ' . <ul' | replace: '</ul', ' . </ul' | replace: '<ol', ' . <ol' | replace: '</ol', ' . </ol' | replace: '</tr', ' . </tr' | replace: '<li', ' | <li' | replace: '</li', ' | </li' | replace: '</td', ' | </td' | replace: '<td', ' | <td' | replace: '</th', ' | </th' | replace: '<th', ' | <th' | strip_html | remove: 'Table of contents' | normalize_whitespace | replace: '. . .', '.' | replace: '. .', '.' | replace: '| |', '|' | append: ' ' | jsonify }},
     "url": "{{ url | relative_url }}",
+    {% include lunr/custom-data.json page=page %}
     "relUrl": "{{ url }}"
   }
         {%- assign i = i | plus: 1 -%}
@@ -62,6 +63,7 @@ permalink: /assets/js/search-data.json
     "title": {{ page.title | jsonify }},
     "content": {{ parts[0] | replace: '</h', ' . </h' | replace: '<hr', ' . <hr' | replace: '</p', ' . </p' | replace: '<ul', ' . <ul' | replace: '</ul', ' . </ul' | replace: '<ol', ' . <ol' | replace: '</ol', ' . </ol' | replace: '</tr', ' . </tr' | replace: '<li', ' | <li' | replace: '</li', ' | </li' | replace: '</td', ' | </td' | replace: '<td', ' | <td' | replace: '</th', ' | </th' | replace: '<th', ' | <th' | strip_html | remove: 'Table of contents' | normalize_whitespace | replace: '. . .', '.' | replace: '. .', '.' | replace: '| |', '|' | append: ' ' | jsonify }},
     "url": "{{ page.url | relative_url }}",
+    {% include lunr/custom-data.json page=page %}
     "relUrl": "{{ page.url }}"
   }
         {%- assign i = i | plus: 1 -%}

docs/configuration.md

@@ -27,6 +27,15 @@ View this site's [\_config.yml](https://github.com/just-the-docs/just-the-docs/t
 logo: "/assets/images/just-the-docs.png"
 ```
 
+## Site favicon
+
+```yaml
+# Set a path/url to a favicon that will be displayed by the browser
+favicon_ico: "/assets/images/favicon.ico"
+```
+
+If the path to your favicon is `/favicon.ico`, you can leave `favicon_ico` unset.
+
 ## Search
 
 ```yaml
@@ -57,9 +66,15 @@ search:
   # Enable or disable the search button that appears in the bottom right corner of every page
   # Supports true or false (default)
   button: false
+  # Focus the search input by pressing `ctrl + focus_shortcut_key` (or `cmd + focus_shortcut_key` on macOS)
+  focus_shortcut_key: 'k'
 ```
 
 ## Mermaid Diagrams
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }
 
 The minimum configuration requires the key for `version` ([from jsDelivr](https://cdn.jsdelivr.net/npm/mermaid/)) in `_config.yml`:
 
@@ -70,7 +85,9 @@ mermaid:
   version: "9.1.3"
 ```
 
-See [the Code documentation]({{ site.baseurl }}{% link docs/ui-components/code.md %}#mermaid-diagram-code-blocks) for more configuration options and information.
+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.
 
 ## Aux links
 
@@ -95,9 +112,13 @@ heading_anchors: true
 ```
 
 ## External navigation links
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }
 
 External links can be added to the navigation through the `nav_external_links` option.
-See [Navigation Structure]({{ site.baseurl }}{% link docs/navigation-structure.md %}#external-navigation-links) for more details.
+See [Navigation Structure]({% link docs/navigation-structure.md %}#external-navigation-links) for more details.
 
 ## Footer content
 
@@ -153,9 +174,13 @@ jtd.addEvent(toggleDarkMode, 'click', function(){
 });
 </script>
 
-See [Customization]({{ site.baseurl }}{% link docs/customization.md %}) for more information.
+See [Customization]({% link docs/customization.md %}) for more information.
 
 ## Callouts
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }
 
 To use this feature, you need to configure a `color` and (optionally) `title` for each kind of callout you want to use, e.g.:
 
@@ -176,7 +201,7 @@ A paragraph...
 [^dark]:
     If you use the `dark` color scheme, this callout uses `$red-300` for the background, and `$red-000` for the title.
 
-The colors `grey-lt`, `grey-dk`, `purple`, `blue`, `green`, `yellow`, and `red` are predefined; to use a custom color, you need to define its `000` and `300` levels in your SCSS files. For example, to use `pink`, add the following to your `_sass/custom/custom.scss` file:
+The colors `grey-lt`, `grey-dk`, `purple`, `blue`, `green`, `yellow`, and `red` are predefined; to use a custom color, you need to define its `000` and `300` levels in your SCSS files. For example, to use `pink`, add the following to your `_sass/custom/setup.scss` file:
 
 ```scss
 $pink-000: #f77ef1;
@@ -206,15 +231,32 @@ The value of `callouts_level` is either `quiet` or `loud`;
 The default level is `quiet` when using the `light` or custom color schemes,
 and `loud` when using the `dark color scheme.`
 
-See [Callouts]({{ site.baseurl }}{% link docs/ui-components/callouts.md %}) for more information.
+See [Callouts]({% link docs/ui-components/callouts.md %}) for more information.
 
 ## Google Analytics
 
+{: .warning }
+> [Google Analytics 4 will replace Universal Analytics](https://support.google.com/analytics/answer/11583528). On **July 1, 2023**, standard Universal Analytics properties will stop processing new hits. The earlier you migrate, the more historical data and insights you will have in Google Analytics 4.
+
+Universal Analytics (UA) and Google Analytics 4 (GA4) properties are supported.
+
 ```yaml
 # Google Analytics Tracking (optional)
-# e.g, UA-1234567-89
+# Supports a CSV of tracking ID strings (eg. "UA-1234567-89,G-1AB234CDE5")
-ga_tracking: UA-5555555-55
+ga_tracking: UA-2709176-10
-ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true by default)
+ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true/nil by default)
+```
+
+### Multiple IDs
+{: .d-inline-block .no_toc }
+
+New (v0.4.0)
+{: .label .label-green }
+
+This theme supports multiple comma-separated tracking IDs. This helps seamlessly transition UA properties to GA4 properties by tracking both for a while.
+
+```yaml
+ga_tracking: "UA-1234567-89,G-1AB234CDE5"
 ```
 
 ## Document collections
@@ -222,6 +264,9 @@ ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (t
 By default, the navigation and search include normal [pages](https://jekyllrb.com/docs/pages/).
 You can also use [Jekyll collections](https://jekyllrb.com/docs/collections/) which group documents semantically together.
 
+{: .warning }
+> Collection folders always start with an underscore (`_`), e.g. `_tests`. You won't see your collections if you omit the prefix.
+
 For example, put all your test files in the `_tests` folder and create the `tests` collection:
 
 ```yaml
@@ -244,7 +289,7 @@ just_the_docs:
       # nav_exclude: true
       # Fold the collection in the navigation
       # Supports true or false (default)
-      # nav_fold: true
+      # nav_fold: true  # note: this option is new in v0.4
       # Exclude the collection from the search
       # Supports true or false (default)
       # search_exclude: true
@@ -252,6 +297,16 @@ just_the_docs:
 
 The navigation for all your normal pages (if any) is displayed before those in collections.
 
+<span>New (v0.4.0)</span>{: .label .label-green }
+Including `nav_fold: true` in a collection configuration *folds* that collection:
+an expander symbol appears next to the collection name,
+and clicking it displays/hides the links to the top-level pages of the collection.[^js-disabled]
+
+[^js-disabled]: <span>New (v0.6.0)</span>{: .label .label-green }
+    When JavaScript is disabled in the browser, all folded collections are automatically expanded,
+    since clicking expander symbols has no effect.
+    (In previous releases, navigation into folded collections required JavaScript to be enabled.)
+
 You can reference multiple collections.
 This creates categories in the navigation with the configured names.
 

docs/customization.md

@@ -17,11 +17,6 @@ nav_order: 6
 
 ## Color schemes
 
-{: .d-inline-block }
-
-New
-{: .label .label-green }
-
 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:
@@ -50,6 +45,15 @@ jtd.addEvent(toggleDarkMode, 'click', function(){
 });
 </script>
 
+### deprecated: `legacy_light`
+{: .d-inline-block .no_toc }
+
+New (v0.4.2)
+{: .label .label-green }
+
+
+In Just the Docs version `0.4.2`, we changed the default syntax highlighting theme for the `light` color scheme to have higher contrast. Users who want to use the old highlighting need to explicitly opt-in with the deprecated `legacy_light` color scheme. In a future major release of Just the Docs, we will remove this color scheme.
+
 ## Custom schemes
 
 ### Define a custom scheme
@@ -58,6 +62,17 @@ You can add custom schemes.
 If you want to add a scheme named `foo` (can be any name) just add a file `_sass/color_schemes/foo.scss` (replace `foo` by your scheme name)
 where you override theme variables to change colors, fonts, spacing, etc.
 
+{: .note }
+Since the default color scheme is `light`, your custom scheme is implicitly based on the variable settings used by the `light` scheme.
+
+If you want your custom scheme to be based on the `dark` scheme, you need to start your file with the following line:
+
+```scss
+@import "./color_schemes/dark";
+```
+
+You can define custom schemes based on other custom schemes in the same way.
+
 Available variables are listed in the [\_variables.scss](https://github.com/just-the-docs/just-the-docs/tree/main/_sass/support/_variables.scss) file.
 
 For example, to change the link color from the purple default to blue, include the following inside your scheme file:
@@ -101,9 +116,29 @@ This allows you to switch the scheme via the following javascript.
 jtd.setTheme("foo")
 ```
 
+## Override and define new variables
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }
+
+To define new SCSS variables or functions, place SCSS code in `_sass/custom/setup.scss`. This should *not* be used for defining custom styles (see the next section) or overriding color scheme variables (in this case, you should create a new color scheme).
+
+This is most commonly-used to define [custom callout colors]({% link docs/configuration.md %}#callouts). For example,
+
+```scss
+// _sass/custom/setup.scss
+$pink-000: #f77ef1;
+$pink-100: #f967f1;
+$pink-200: #e94ee1;
+$pink-300: #dd2cd4;
+```
+
+In particular: this file is imported *after* the theme's variables and functions are defined, but *before* any CSS classes are emitted.
+
 ## Override and completely custom styles
 
-For styles that aren't defined as variables, you may want to modify specific CSS classes.
+For styles that aren't defined as SCSS variables, you may want to modify specific CSS classes.
 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.
@@ -129,11 +164,31 @@ For example, if you'd like to add your own styles for printing a page, you could
 
 ## Override includes
 
-The site can be modified by overriding any of the custom [Jekyll includes](https://jekyllrb.com/docs/includes/) provided by default in the theme.
+You can customize the theme by overriding any of the custom [Jekyll includes](https://jekyllrb.com/docs/includes/) files that it provides.
 
-To do this, create an `_includes` directory and make a copy of the specific file you wish to modify. Any content added to this file will override the theme defaults. You can learn more about this process in the Jekyll docs for [Overriding theme defaults](https://jekyllrb.com/docs/themes/#overriding-theme-defaults).
+To do this, create an `_includes` directory and make a copy of the specific file you wish to modify. The content in this file will override the theme defaults. You can learn more about this process in the Jekyll docs for [Overriding theme defaults](https://jekyllrb.com/docs/themes/#overriding-theme-defaults).
 
-The following includes were made available to you:
+Just the Docs provides the following custom includes files:
+
+### Custom TOC Heading
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }
+
+`_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.
+
+#### Example
+{: .no_toc }
+
+To change the default TOC heading to "Contents", create `_includes/toc_heading_custom.html` and add:
+```html
+<h2 class="text-delta">Contents</h2>
+```
+
+The (optional) `text-delta` class makes the heading appear as **Contents**{:.text-delta} .
 
 ### Custom Footer
 
@@ -147,12 +202,7 @@ This content appears at the bottom of every page's main content. More info for t
 
 Any HTML added to this file will be inserted before the closing `<head>` tag. This might include additional `<meta>`, `<link>`, or `<script>` tags.
 
-#### Example
+The `<head>` tag automatically includes a link to an existing favicon if you set `favicon_ico` to the corresponding path in your configuration, or if the path to the favicon is `/favicon.ico`.
-
-To add a custom favicon, create `_includes/head_custom.html` and add:
-```html
-<link rel="shortcut icon" type="image/png" href="{{site.baseurl}}/path/to/your/favicon.png">
-```
 
 ### Custom Header
 
@@ -161,7 +211,196 @@ To add a custom favicon, create `_includes/head_custom.html` and add:
 Content added to this file appears at the top of every page's main content between the site search and auxiliary links if they are enabled. If `search_enabled` were set to false and `aux_links` were removed, the content of `header_custom.html` would occupy the space at the top of every page.
 
 ### Custom Nav Footer
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }
 
 `_includes/nav_footer_custom.html`
 
 Any content added to this file will appear at the bottom left of the page below the site's navigation. By default an attribution to Just the Docs is displayed which reads, `This site uses Just the Docs, a documentation theme for Jekyll.`.
+
+### Custom Search Placeholder
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }
+
+`_includes/search_placeholder_custom.html`
+
+Content added to this file will replace the default placeholder text in the search bar (and its `aria-label`), after stripping HTML and leading/trailing whitespace. By default, the content of the include is:
+
+{% raw %}
+
+```liquid
+Search {{site.title}}
+```
+
+{% endraw %}
+
+Override this file to render a custom placeholder. One common use-case is internationalization; for example,
+
+{% raw %}
+
+```liquid
+Chercher notre site
+```
+
+{% endraw %}
+
+would make the placeholder text "Chercher notre site". [Liquid code](https://jekyllrb.com/docs/liquid/) (including [Jekyll variables](https://jekyllrb.com/docs/variables/)) is also supported.
+
+## Custom layouts and includes
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }
+
+Advanced
+{: .label .label-yellow }
+
+Just the Docs uses Jekyll's powerful [layouts](https://jekyllrb.com/docs/layouts/) and [includes](https://jekyllrb.com/docs/includes/) features to generate and compose various elements of the site. Jekyll users and developers can extend or replace existing layouts and includes to customize the entire site layout.
+
+### Default layout and includable components
+
+The `default` layout is inherited by most of the "out-of-the-box" pages provided by Just the Docs. It composes various re-usable components of the site, including the sidebar, navbar, footer, breadcrumbs, and various imports. Most users who create new pages or layouts will inherit from `default`.
+
+Here is a simplified code example of what it looks like:
+
+{% raw %}
+
+```liquid
+<!-- a simplified version of _layouts/default.html -->
+<html>
+{% include head.html %}
+<body>
+  {% include icons/icons.html %}
+  {% include components/sidebar.html %}
+  {% include components/header.html %}
+  {% 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.search_enabled != false %}
+    {% include components/search_footer.html %}
+  {% endif %}
+
+  {% if site.mermaid %}
+    {% include components/mermaid.html %}
+  {% endif %}
+</body>
+</html>
+```
+
+{% endraw %}
+
+#### Component summary
+{: .no_toc }
+
+{: .warning }
+Defining a new `_includes` with the same name as any of these components will significantly change the existing layout. Please proceed with caution when adjusting them.
+
+To briefly summarize each component:
+
+- `_includes/head.html` is the entire `<head>` tag for the site; this imports stylesheets, various JavaScript files (ex: analytics, mermaid, search, and Just the Docs code), and SEO / meta information.
+- `_includes/icons/icons.html` imports all SVG icons that are used throughout the site. Some, such as those relating to search or code snippet copying, are only loaded when those features are enabled.
+- `_includes/components/sidebar.html` renders the sidebar, containing the site header, navigation links, external links, collections, and nav footer.
+- `_includes/components/header.html` renders the navigation header, containing the search bar, custom header, and aux links
+- `_includes/components/breadcrumbs.html` renders the breadcrumbs feature
+- `vendor/anchor_headings.html` is a local copy of Vladimir Jimenez's [jekyll-anchor-headings](https://github.com/allejo/jekyll-anchor-headings) snippet
+- `_includes/components/children_nav.html` renders a list of nav links to child pages on parent pages
+- `_includes/components/footer.html` renders the bottom-of-page footer
+- `_includes/components/search_footer.html` renders DOM elements that are necessary for the search bar to work
+- `_includes/components/mermaid.html` initializes mermaid if the feature is enabled
+
+Each of these components can be overridden individually using the same process described in the [Override includes](#override-includes) section. In particular, the granularity of components should allow users to replace certain components (such as the sidebar) without having to adjust the rest of the code.
+
+Future versions may subdivide components further; we guarantee that we will only place them in folders (ex `components/`, `icons/`, or a new `js/`) to avoid top-level namespace collisions.
+
+### 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.
+
+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:
+
+{% raw %}
+
+```
+---
+layout: minimal
+title: Minimal layout test
+---
+```
+
+{% endraw %}
+
+Similarly, users and developers can create other alternative layouts using Just the Docs' reusable includable components.
+
+### Default layout and inheritance chain
+
+Under the hood,
+
+- `default` and `minimal` 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.
+
+### Overridden default Jekyll layouts
+
+By default, Jekyll (and its default theme `minima`) provide the `about`, `home`, `page`, and `post` layouts. In Just the Docs, we override all of these layouts with the `default` layout. Each of those layouts is simply:
+
+{% raw %}
+
+```
+---
+layout: default
+---
+
+{{ content }}
+```
+
+{% endraw %}

docs/index-test.md

@@ -22,7 +22,7 @@ jtd.addEvent(toggleDarkMode, 'click', function(){
 
 Text can be **bold**, _italic_, or ~~strikethrough~~.
 
-[Link to another page](another-page).
+[Link to another page]({{site.baseurl}}/).
 
 There should be whitespace between paragraphs.
 
@@ -55,7 +55,7 @@ GitHubPages::Dependencies.gems.each do |gem, version|
 end
 ```
 
-#### [](#header-4)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.
@@ -310,7 +310,17 @@ graph TD;
     C-->D;
 ```
 
+### Collapsed Section
 
-```
+The following uses the [`<details>`](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections) tag to create a collapsed section.
-The final element.
+
-```
+<details markdown="block">
+<summary>Shopping list (click me!)</summary>
+
+This is content inside a `<details>` dropdown.
+
+- [ ] Apples
+- [ ] Oranges
+- [ ] Milk
+
+</details>

docs/layout/layout.md

@@ -0,0 +1,40 @@
+---
+title: Layout
+layout: default
+nav_order: 4.5
+has_children: true
+---
+
+# Layout
+
+You specify the layout for a page in its [front matter]. Just the Docs has a `default` layout with a sidebar, used for almost all pages in the theme docs, and a `minimal` layout that omits the sidebar.
+{: .fs-6 .fw-300 }
+
+## The layout concept
+
+See the [Jekyll docs page about layouts] for an explanation of the general idea of layouts and how to specify them.
+
+You can use [Jekyll's front matter defaults] to specify the same layout for many pages.
+
+## The `default` layout
+
+This page uses the default layout.
+
+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.
+
+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.
+
+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.
+
+## Other layouts
+
+Just the Docs has further layouts: `about`, `home`, `page`, and `post`. Currently, they are all based on the `default` layout. See the [Jekyll docs about inheritance] for how to customize them.
+
+[front matter]: https://jekyllrb.com/docs/front-matter/ "Jekyll docs about front matter"
+[Jekyll docs page about layouts]: https://jekyllrb.com/docs/layouts/ "Jekyll docs about layouts"
+[Jekyll's front matter defaults]: https://jekyllrb.com/docs/configuration/front-matter-defaults/ "Jekyll docs about front matter defaults"
+[Jekyll docs about inheritance]: https://jekyllrb.com/docs/layouts/#inheritance "Jekyll docs about inheritance"

docs/layout/minimal/default-child.md

@@ -0,0 +1,8 @@
+---
+title: Default layout child page
+layout: default
+parent: A minimal layout page 
+grand_parent: Layout
+---
+
+This is a child page that uses the same minimal layout as its parent page.

docs/layout/minimal/minimal-child.md

@@ -0,0 +1,8 @@
+---
+title: Minimal layout child page
+layout: minimal
+parent: A minimal layout page
+grand_parent: Layout
+---
+
+This is a child page that uses the same minimal layout as its parent page.

docs/layout/minimal/minimal.md

@@ -0,0 +1,12 @@
+---
+title: A minimal layout page
+layout: minimal
+parent: Layout
+has_children: true
+---
+
+# A minimal layout page
+
+This page illustrates the built-in layout `minimal`.
+
+One of its child pages also uses the minimal layout; the other child pages uses the default layout.

docs/minimal-test.md

@@ -0,0 +1,9 @@
+---
+layout: minimal
+title: Minimal layout test
+nav_exclude: true
+---
+
+[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

@@ -20,7 +20,7 @@ nav_order: 5
 
 ## Main navigation
 
-The main navigation for your Just the Docs site is on the left side of the page at 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).
+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)).
 
@@ -30,7 +30,7 @@ By default, all pages will appear as top level pages in the main nav unless a pa
 
 To specify a page order, you can use the `nav_order` parameter in your pages' YAML front matter.
 
-#### Example
+### Example (ordering pages)
 {: .no_toc }
 
 ```yaml
@@ -44,11 +44,10 @@ 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. 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.
+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 quotation marks is optional.
+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.
-
-> _Note for users of previous versions:_ `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.
 
 ---
 
@@ -56,7 +55,7 @@ By default, all Capital letters come before all lowercase letters; you can add `
 
 For specific pages that you do not wish to include in the main navigation, e.g. a 404 page or a landing page, use the `nav_exclude: true` parameter in the YAML front matter for that page.
 
-#### Example
+### Example (excluding pages)
 {: .no_toc }
 
 ```yaml
@@ -70,7 +69,7 @@ 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 navigation.
+Pages with no `title` are automatically excluded from the main navigation.
 
 ---
 
@@ -109,7 +108,7 @@ On the parent pages, add this YAML front matter parameter:
 
 - `has_children: true` (tells us that this is a parent page)
 
-#### Example
+### Example (parent pages)
 {: .no_toc }
 
 ```yaml
@@ -130,7 +129,7 @@ Here we're setting up the UI Components landing page that is available at `/docs
 
 On child pages, simply set the `parent:` YAML front matter to whatever the parent's page title is and set a nav order (this number is now scoped within the section).
 
-#### Example
+#### Example (child pages)
 {: .no_toc }
 
 ```yaml
@@ -146,18 +145,22 @@ 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 }
 
-You can optionally add the following to the YAML front matter to change the default sort order of child pages from ascending to descending order:
+New (v0.4.0)
+{: .label .label-green }
 
-- `child_nav_order: desc`
+You can optionally add the following to the YAML front matter to reverse the default sort order of child pages:
 
-#### Example
+- `child_nav_order: reversed`
+
+#### Example (ordering child pages)
 {: .no_toc }
 ```yaml
 ---
 layout: default
-title: Descending Child Pages
+title: Reversed Child Pages
-child_nav_order: desc
+child_nav_order: reversed
 ---
 ```
 
@@ -165,7 +168,7 @@ child_nav_order: desc
 
 By default, all pages with children will automatically append a Table of Contents which lists the child pages after the parent page's content. To disable this auto Table of Contents, set `has_toc: false` in the parent page's YAML front matter.
 
-#### Example
+#### Example (auto-generating Table of Contents)
 {: .no_toc }
 
 ```yaml
@@ -188,7 +191,7 @@ Child pages can also have children (grandchildren). This is achieved by using a
 1. Add the `has_children` attribute to the child
 1. Add the `parent` and `grand_parent` attribute to the grandchild
 
-#### Example
+##### Example (children within children)
 {: .no_toc }
 
 ```yaml
@@ -229,13 +232,50 @@ This would create the following navigation structure:
 +-- ..
 ```
 
+{: .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]({{ site.baseurl }}{% link docs/configuration.md %}#aux-links) in your site's `_config.yml` file.
+To add auxiliary links to your site (in the upper right on all pages), add it to the `aux_links` [configuration option]({% link docs/configuration.md %}#aux-links) in your site's `_config.yml` file.
 
-#### Example
+### Example (auxiliary links)
 {: .no_toc }
 
 ```yaml
@@ -248,12 +288,15 @@ aux_links:
 ---
 
 ## External Navigation Links
+{: .d-inline-block }
 
-To add external links to the navigation, add them to the `nav_external_links` [configuration]({{ site.baseurl }}{% link docs/configuration.md %}) option in your site's `_config.yml` file.
+New (v0.4.0)
-External links will appear under all other items in the listing order.
+{: .label .label-green }
 
-#### Example
+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
@@ -262,15 +305,32 @@ nav_external_links:
   - title: Just the Docs on GitHub
     url: https://github.com/just-the-docs/just-the-docs
     hide_icon: false # set to true to hide the external link icon - defaults to false
+    opens_in_new_tab: false # set to true to open this link in a new tab - defaults to false
 ```
 
+### Opening external links in a new tab
+{: .d-inline-block }
+
+New (unreleased)
+{: .label .label-green }
+
+The external links are decorated by an icon, which distinguishes them from internal links.
+You can suppress the icon by setting `hide_icon: true`.
+
+By default, external links are not opened in a new tab. However, this can be enabled by:
+
+1. setting `opens_in_new_tab: true` in the link's configuration object
+2. setting the configuration option `nav_external_links_new_tab: true` in `_config.yml`
+
+When they conflict, `opens_in_new_tab` takes precedence.
+
 ---
 
 ## In-page navigation with Table of Contents
 
 To generate a Table of Contents on your docs pages, you can use the `{:toc}` method from Kramdown, immediately after an `<ol>` in Markdown. This will automatically generate an ordered list of anchor links to various sections of the page based on headings and heading levels. There may be occasions where you're using a heading and you don't want it to show up in the TOC, so to skip a particular heading use the `{: .no_toc }` CSS class.
 
-#### Example
+### Example (in-page navigation with Table of Contents)
 {: .no_toc }
 
 ```markdown

docs/search.md

@@ -5,11 +5,9 @@ nav_order: 7
 ---
 
 # Search
-
 {: .no_toc }
 
 ## Table of contents
-
 {: .no_toc .text-delta }
 
 1. TOC
@@ -17,7 +15,7 @@ nav_order: 7
 
 ---
 
-Just the Docs uses [lunr.js](http://lunrjs.com) to add a client-side search interface powered by a JSON index that Jekyll generates.
+Just the Docs uses [lunr.js](https://lunrjs.com) to add a client-side search interface powered by a JSON index that Jekyll generates.
 All search results are shown in an auto-complete style interface (there is no search results page).
 By default, all generated HTML pages are indexed using the following data points:
 
@@ -96,9 +94,24 @@ The search button displays in the bottom right corner of the screen and triggers
 search.button: true
 ```
 
+### Focus search bar with a keyboard shortcut
+
+Just the Docs supports focusing the search bar input with a keyboard shortcut. After setting the `search.focus_shortcut_key` config item key, users who press <kbd>Ctrl</kbd> + `search.focus_shortcut_key` (or on macOS, <kbd>Command</kbd> + `search.focus_shortcut_key`) will focus the search bar.
+
+Note that this feature is **disabled by default**. `search.focus_shortcut_key` should be a [valid value from `KeyboardEvent.key`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key); this involves all ASCII alphanumeric values, as well as modifier keys.
+
+For example,
+
+```yaml
+search:
+    focus_shortcut_key: 'k'
+```
+
+Will make <kbd>Ctrl</kbd> + <kbd>K</kbd> focus the search bar for Windows users (and <kbd>Command</kbd> + <kbd>K</kbd> on macOS).
+
 ## Hiding pages from search
 
-Sometimes you might have a page that you don't want to be indexed for the search nor to show up in search results, e.g, a 404 page.
+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
@@ -127,3 +140,43 @@ $ bundle exec just-the-docs rake search:init
 
 This command creates the `assets/js/zzzz-search-data.json` file that Jekyll uses to create your search index.
 Alternatively, you can create the file manually with [this content]({{ site.github.repository_url }}/blob/main/assets/js/zzzz-search-data.json).
+
+## Custom content for search index
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }
+
+Advanced
+{: .label .label-yellow }
+
+By default, the search feature indexes a page's `.content`, `.title`, and *some* headers within the `.content`. Other data (e.g. front matter, files in `_data` and `assets`) is not indexed. Users can customize what is indexed.
+
+{: .warning }
+> Customizing search indices is an advanced feature that requires Javascript and Liquid knowledge.
+
+1. When Just the Docs is a local or gem theme, ensure `assets/js/zzzz-search-data.json` is up-to-date with [Generate search index when used as a gem](#generate-search-index-when-used-as-a-gem).
+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
+
+This example adds front matter `usage` and `examples` fields to the search index.
+
+`_includes/lunr/custom-data.json` custom code reads the page `usage` and `examples` fields, normalizes the text, and writes the text to custom Javascript `myusage` and `myexamples` fields. Javascript fields are similar yet [not the same as JSON](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON#javascript_and_json_differences). `jsonify` will probably work for most scenarios.
+
+{% raw %}
+```liquid
+{%- capture newline %}
+{% endcapture -%}
+"myusage": {{ include.page.usage | markdownify | replace:newline,' ' | strip_html | normalize_whitespace | strip | jsonify }},
+"myexamples": {{ include.page.examples | markdownify | replace:newline,' ' | strip_html | normalize_whitespace | strip | jsonify }},
+```
+{% endraw %}
+
+`_includes/lunr/custom-index.js` custom code is inserted into the Javascript loop of `assets/js/just-the-docs.js`. All custom Javascript fields are accessed as fields of `docs[i]` such as `docs[i].myusage`. Finally, append your custom fields on to the already existing `docs[i].content`.
+
+```javascript
+const content_to_merge = [docs[i].content, docs[i].myusage, docs[i].myexamples];
+docs[i].content = content_to_merge.join(' ');
+```

docs/ui-components/buttons.md

@@ -21,22 +21,22 @@ nav_order: 2
 ### Links that look like buttons
 
 <div class="code-example" markdown="1">
-[Link button](http://example.com/){: .btn }
+[Link button](https://just-the-docs.com){: .btn }
 
-[Link button](http://example.com/){: .btn .btn-purple }
+[Link button](https://just-the-docs.com){: .btn .btn-purple }
-[Link button](http://example.com/){: .btn .btn-blue }
+[Link button](https://just-the-docs.com){: .btn .btn-blue }
-[Link button](http://example.com/){: .btn .btn-green }
+[Link button](https://just-the-docs.com){: .btn .btn-green }
 
-[Link button](http://example.com/){: .btn .btn-outline }
+[Link button](https://just-the-docs.com){: .btn .btn-outline }
 </div>
 ```markdown
-[Link button](http://example.com/){: .btn }
+[Link button](https://just-the-docs.com){: .btn }
 
-[Link button](http://example.com/){: .btn .btn-purple }
+[Link button](https://just-the-docs.com){: .btn .btn-purple }
-[Link button](http://example.com/){: .btn .btn-blue }
+[Link button](https://just-the-docs.com){: .btn .btn-blue }
-[Link button](http://example.com/){: .btn .btn-green }
+[Link button](https://just-the-docs.com){: .btn .btn-green }
 
-[Link button](http://example.com/){: .btn .btn-outline }
+[Link button](https://just-the-docs.com){: .btn .btn-outline }
 ```
 
 ### Button element
@@ -56,42 +56,42 @@ GitHub Flavored Markdown does not support the `button` element, so you'll have t
 
 ### Button size
 
-Wrap the button in a container that uses the [font-size utility classes]({{ site.baseurl }}{% link docs/utilities/typography.md %}) to scale buttons:
+Wrap the button in a container that uses the [font-size utility classes]({% link docs/utilities/typography.md %}) to scale buttons:
 
 <div class="code-example" markdown="1">
 <span class="fs-6">
-[Big ass button](http://example.com/){: .btn }
+[Big ass button](https://just-the-docs.com){: .btn }
 </span>
 
 <span class="fs-3">
-[Tiny ass button](http://example.com/){: .btn }
+[Tiny ass button](https://just-the-docs.com){: .btn }
 </span>
 </div>
 ```markdown
 <span class="fs-8">
-[Link button](http://example.com/){: .btn }
+[Link button](https://just-the-docs.com){: .btn }
 </span>
 
 <span class="fs-3">
-[Tiny ass button](http://example.com/){: .btn }
+[Tiny ass button](https://just-the-docs.com){: .btn }
 </span>
 ```
 
 ### Spacing between buttons
 
-Use the [margin utility classes]({{ site.baseurl }}{% link docs/utilities/layout.md %}#spacing) to add spacing between two buttons in the same block.
+Use the [margin utility classes]({% link docs/utilities/layout.md %}#spacing) to add spacing between two buttons in the same block.
 
 <div class="code-example" markdown="1">
-[Button with space](http://example.com/){: .btn .btn-purple .mr-2 }
+[Button with space](https://just-the-docs.com){: .btn .btn-purple .mr-2 }
-[Button](http://example.com/){: .btn .btn-blue }
+[Button](https://just-the-docs.com){: .btn .btn-blue }
 
-[Button with more space](http://example.com/){: .btn .btn-green .mr-4 }
+[Button with more space](https://just-the-docs.com){: .btn .btn-green .mr-4 }
-[Button](http://example.com/){: .btn .btn-blue }
+[Button](https://just-the-docs.com){: .btn .btn-blue }
 </div>
 ```markdown
-[Button with space](http://example.com/){: .btn .btn-purple .mr-2 }
+[Button with space](https://just-the-docs.com){: .btn .btn-purple .mr-2 }
-[Button](http://example.com/){: .btn .btn-blue }
+[Button](https://just-the-docs.com){: .btn .btn-blue }
 
-[Button with more space](http://example.com/){: .btn .btn-green .mr-4 }
+[Button with more space](https://just-the-docs.com){: .btn .btn-green .mr-4 }
-[Button](http://example.com/){: .btn .btn-blue }
+[Button](https://just-the-docs.com){: .btn .btn-blue }
 ```

docs/ui-components/callouts.md

@@ -6,12 +6,19 @@ nav_order: 7
 ---
 
 # Callouts
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }
 
 Markdown does not include support for callouts. However, you can style text as a callout using a Markdown extension supported by kramdown: [*block IALs*](https://kramdown.gettalong.org/quickref.html#block-attributes).
 
-Common kinds of callouts include `admonition`, `attention`, `caution`, `danger`, `error`, `hint`, `important`, `note`, `tip`, and `warning`.
+Common kinds of callouts include `highlight`, `important`, `new`, `note`, and `warning`.
 
-When you have [configured]({{ site.baseurl }}{% link docs/configuration.md %}#callouts) the  `color` and (optional) `title` for a callout, you can apply it to a paragraph, or to a block quote with several paragraphs, as illustrated below.[^postfix]
+{: .warning }
+These callout names are *not* pre-defined by the theme: you need to define your own names.
+
+When you have [configured]({% link docs/configuration.md %}#callouts) the  `color` and (optional) `title` for a callout, you can apply it to a paragraph, or to a block quote with several paragraphs, as illustrated below.[^postfix]
 
 [^postfix]:
     You can put the callout markup either before or after its content.
@@ -24,6 +31,10 @@ When you have [configured]({{ site.baseurl }}{% link docs/configuration.md %}#ca
 A paragraph
 ```
 
+{: .highlight }
+A paragraph
+
+
 #### A single paragraph callout
 {: .no_toc }
 
@@ -32,6 +43,9 @@ A paragraph
 A paragraph
 ```
 
+{: .note }
+A paragraph
+
 ```markdown
 {: .note-title }
 > My note title
@@ -39,6 +53,11 @@ A paragraph
 > A paragraph with a custom title callout
 ```
 
+{: .note-title }
+> My note title
+>
+> A paragraph with a custom title callout
+
 #### A multi-paragraph callout
 {: .no_toc }
 
@@ -51,6 +70,13 @@ A paragraph
 > The last paragraph
 ```
 
+{: .important }
+> A paragraph
+>
+> Another paragraph
+>
+> The last paragraph
+
 ```markdown
 {: .important-title }
 > My important title
@@ -62,19 +88,31 @@ A paragraph
 > The last paragraph
 ```
 
+{: .important-title }
+> My important title
+>
+> A paragraph
+>
+> Another paragraph
+>
+> The last paragraph
+
 #### An indented callout
 {: .no_toc }
 
 ```markdown
-> {: .hint }
+> {: .highlight }
   A paragraph
 ```
 
+> {: .highlight }
+  A paragraph
+
 #### Indented multi-paragraph callouts
 {: .no_toc }
 
 ```markdown
-> {: .attention }
+> {: .new }
 > > A paragraph
 > >
 > > Another paragraph
@@ -82,6 +120,14 @@ A paragraph
 > > The last paragraph
 ```
 
+> {: .new }
+> > A paragraph
+> >
+> > Another paragraph
+> >
+> > The last paragraph
+
+
 #### Nested callouts
 {: .no_toc }
 
@@ -91,6 +137,10 @@ A paragraph
 > A paragraph
 ```
 
+{: .important }
+> {: .warning }
+> A paragraph
+
 #### Opaque background
 {: .no_toc }
 
@@ -102,3 +152,10 @@ A paragraph
 > A paragraph
 > </div>
 ```
+
+{: .important }
+> {: .opaque }
+> <div markdown="block">
+> {: .warning }
+> A paragraph
+> </div>

docs/ui-components/code.md

@@ -58,6 +58,8 @@ var fun = function lang(l) {
 ```
 {% endhighlight %}
 
+Syntax highlighting, line numbers, and HTML compression do not work together; **the combination of these features generates invalid HTML that renders incorrectly**. To learn more, see ["Code with line numbers"]({% link docs/ui-components/line-nos.md %}).
+
 ---
 
 ## Code blocks with rendered examples
@@ -68,30 +70,34 @@ To demonstrate front end code, sometimes it's useful to show a rendered example
 
 <div class="code-example" markdown="1">
 
-[Link button](http://example.com/){: .btn }
+[Link button](https://just-the-docs.com){: .btn }
 
 </div>
 ```markdown
-[Link button](http://example.com/){: .btn }
+[Link button](https://just-the-docs.com){: .btn }
 ```
 
 </div>
 {% highlight markdown %}
 <div class="code-example" markdown="1">
 
-[Link button](http://example.com/){: .btn }
+[Link button](https://just-the-docs.com){: .btn }
 
 </div>
 ```markdown
-[Link button](http://example.com/){: .btn }
+[Link button](https://just-the-docs.com){: .btn }
 ```
 {% endhighlight %}
 
 ---
 
 ## Mermaid diagram code blocks
+{: .d-inline-block }
 
-[Mermaid](https://mermaid-js.github.io/mermaid/) allows you to add diagrams and visualizations using Markdown code blocks. You can turn on support for mermaid by adding a `mermaid` key to your `_config.yml`.
+New (v0.4.0)
+{: .label .label-green }
+
+[Mermaid](https://mermaid-js.github.io/mermaid/) allows you to add diagrams and visualizations using Markdown code blocks. **It is disabled by default**. However, you can turn on support for mermaid by adding a `mermaid` key to your `_config.yml`.
 
 The minimum configuration requires a `version` key (matching a version in [jsDelivr](https://cdn.jsdelivr.net/npm/mermaid/)):
 
@@ -111,7 +117,7 @@ Additional configuration options are loaded through `_includes/mermaid_config.js
 
 This loads the default settings.
 
-The contents of this object should follow [mermaid's configuration API](https://mermaid-js.github.io/mermaid/#/./Setup?id=configuration). For example, to override the theme, change `_includes/mermaid_config.js` to:
+The contents of this object should follow [mermaid's configuration API](https://mermaid.js.org/config/configuration.html). For example, to override the theme, change `_includes/mermaid_config.js` to:
 
 ```js
 // _includes/mermaid_config.js
@@ -131,3 +137,71 @@ graph TD;
     C-->D;
 ```
 {% endhighlight %}
+
+which renders:
+
+```mermaid
+graph TD;
+    A-->B;
+    A-->C;
+    B-->D;
+    C-->D;
+```
+
+*Note: for demonstration purposes, we've enabled mermaid on this site. It is still disabled by default, and users need to opt-in to use it.*
+
+### Using a local mermaid library
+
+To load a local version of mermaid, also use the `path` key to specify the location of the library; e.g.
+
+```yaml
+mermaid:
+  version: "10.1.0"
+  # for (v10+)
+  path: "/assets/js/mermaid.esm.min.mjs"
+  # for (<v10):
+  # path: "/assets/js/mermaid.min.js"
+  # Note: copy both `mermaid.esm.min.mjs` (v10+) or `mermaid.min.js` (<v10) and the associated
+  # `.map` file from the specified version of `mermaid/dist` to `/assets/js/`.
+```
+
+For mermaid versions `>=10`, this file is imported directly as an ESM module (rather than as a plain `<script>` tag); users should use the `mermaid.esm.min.mjs` file. In contrast, for mermaid versions `<10`, this file is loaded as a script tag; it should be a standalone CJS file (i.e. `mermaid.min.js`).
+
+{: .warning }
+Mermaid versions `10.0` - `10.1` (and possibly, future releases) still encode relative imports in `mermaid.esm.min.mjs`. Local users must copy *all* of the contents of the `dist` folder to the specified path (preserving the relative location of the files). Just the Docs is actively monitoring mermaid releases; an upstream fix is planned.
+
+### Using mermaid with AsciiDoc
+
+Users of [AsciiDoc](https://asciidoc.org/) (e.g. via [jekyll-asciidoc](https://github.com/asciidoctor/jekyll-asciidoc)) may need additional configuration to use mermaid.
+
+By default, AsciiDoc generates HTML markup that mermaid cannot properly parse. The simplest way to resolve this is to use a [passthrough block](https://docs.asciidoctor.org/asciidoc/latest/pass/pass-block/):
+{% highlight asciidoc %}
+++++
+<pre class="language-mermaid">
+graph TD;
+    A-->B;
+    A-->C;
+    B-->D;
+    C-->D;
+</pre>
+++++
+{% endhighlight %}
+
+Alternatively, community member [@flyx](https://github.com/flyx) has contributed a Ruby extension that does not require extra markup. The extension is available [as a GitHub Gist](https://gist.github.com/flyx/9fff080cf4edc95d495bc661a002232c). Thank you to [@flyx](https://github.com/flyx)!
+
+The [asciidoctor-diagram](https://docs.asciidoctor.org/diagram-extension/latest/) extension which also supports mermaid is not recommended for use with Just the Docs, since it requires separate configuration e.g. for theming, and is known to not be trivial to set up.
+
+## Copy button
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }
+
+The copy button for code blocks can be enabled or disabled via the `enable_copy_code_button` key in `_config.yml`. By default, the value of this key is `false`; users need to opt-in.
+
+```yaml
+# For copy button on code
+enable_copy_code_button: true
+```
+
+Note that this feature requires JavaScript; if JavaScript is disabled in the browser, this feature will not work. In addition, this feature uses `navigator.clipboard`, which is only available in [secure contexts](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) (such as over HTTPS). If the site is viewed in an insecure context, the copy button will not work ([relevant issue: #1202](https://github.com/just-the-docs/just-the-docs/issues/1202)).

docs/ui-components/line-nos.md

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

docs/ui-components/typography.md

@@ -21,7 +21,7 @@ nav_order: 1
 By default, Just the Docs uses a native system font stack for sans-serif fonts:
 
 ```scss
-system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif
+system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Segoe UI Emoji"
 ```
 
 ABCDEFGHIJKLMNOPQRSTUVWXYZ
@@ -97,12 +97,12 @@ Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor
 <div class="code-example" markdown="1">
 Text can be **bold**, _italic_, or ~~strikethrough~~.
 
-[Link to another page](another-page).
+[Link to another page]({{site.baseurl}}/).
 </div>
 ```markdown
 Text can be **bold**, _italic_, or ~~strikethrough~~.
 
-[Link to another page](another-page).
+[Link to another page]({{site.baseurl}}/).
 ```
 
 ---
@@ -111,4 +111,4 @@ Text can be **bold**, _italic_, or ~~strikethrough~~.
 
 There are a number of specific typographic CSS classes that allow you to override default styling for font size, font weight, line height, and capitalization.
 
-[View typography utilities]({{ site.baseurl }}{% link docs/utilities/utilities.md %}#typography){: .btn .btn-outline }
+[View typography utilities]({% link docs/utilities/typography.md %}){: .btn .btn-outline }