Prep for v0.4.0.rc5; update gemspec and CHANGELOG

Co-authored-by: Simone <26844016+simonebortolin@users.noreply.github.com>

.devcontainer/Dockerfile

@@ -0,0 +1,14 @@
+# [Choice] Debian OS version (use bullseye on local arm64/Apple Silicon): bullseye, buster
+ARG VARIANT=bullseye
+FROM mcr.microsoft.com/vscode/devcontainers/jekyll:0-${VARIANT}
+
+# [Choice] Node.js version: none, lts/*, 16, 14, 12, 10
+ARG NODE_VERSION="none"
+RUN if [ "${NODE_VERSION}" != "none" ]; then su vscode -c "umask 0002 && . /usr/local/share/nvm/nvm.sh && nvm install ${NODE_VERSION} 2>&1"; fi
+
+# [Optional] Uncomment this section to install additional OS packages.
+# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
+#     && apt-get -y install --no-install-recommends <your-package-list-here>
+
+# [Optional] Uncomment this line to install global node packages.
+# RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g <your-package-here>" 2>&1

.devcontainer/base.Dockerfile

@@ -0,0 +1,26 @@
+# [Choice] Debian OS version (use 2.7-bullseye on local arm64/Apple Silicon): 2.7-bullseye, 2.7-buster
+ARG VARIANT=2.7-bullseye
+FROM mcr.microsoft.com/vscode/devcontainers/ruby:${VARIANT}
+COPY library-scripts/meta.env /usr/local/etc/vscode-dev-containers
+
+# ENV Variables required by Jekyll
+ENV LANG=en_US.UTF-8 \
+    LANGUAGE=en_US:en \
+    TZ=Etc/UTC \
+    LC_ALL=en_US.UTF-8 \
+    LANG=en_US.UTF-8 \
+    LANGUAGE=en_US
+
+# Install bundler, latest jekyll, and github-pages for older jekyll
+RUN gem install bundler jekyll github-pages
+
+# [Choice] Node.js version: none, lts/*, 16, 14, 12, 10
+ARG NODE_VERSION="none"
+RUN if [ "${NODE_VERSION}" != "none" ]; then su vscode -c "umask 0002 && . /usr/local/share/nvm/nvm.sh && nvm install ${NODE_VERSION} 2>&1"; fi
+
+# [Optional] Uncomment this section to install additional OS packages.
+# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
+#     && apt-get -y install --no-install-recommends <your-package-list-here>
+
+# [Optional] Uncomment this line to install global node packages.
+# RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g <your-package-here>" 2>&1

.devcontainer/devcontainer.json

@@ -0,0 +1,35 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
+// https://github.com/microsoft/vscode-dev-containers/tree/v0.224.2/containers/jekyll
+{
+  "name": "Just the docs",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "args": {
+      // Update 'VARIANT' to pick a Debian OS version: bullseye, buster
+      // Use bullseye when on local arm64/Apple Silicon.
+      "VARIANT": "bullseye",
+      // Enable Node.js: pick the latest LTS version
+      "NODE_VERSION": "lts/*"
+    }
+  },
+
+  // Set *default* container specific settings.json values on container create.
+  "settings": {},
+
+  // Add the IDs of extensions you want installed when the container is created.
+  "extensions": ["GitHub.vscode-pull-request-github"],
+
+  // Use 'forwardPorts' to make a list of ports inside the container available locally.
+  "forwardPorts": [
+    // Jekyll server
+    4000,
+    // Live reload server
+    35729
+  ],
+
+  // Use 'postCreateCommand' to run commands after the container is created.
+  "postCreateCommand": "sh .devcontainer/post-create.sh",
+
+  // Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
+  "remoteUser": "vscode"
+}

.devcontainer/post-create.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+
+# Install the version of Bundler.
+if [ -f Gemfile.lock ] && grep "BUNDLED WITH" Gemfile.lock > /dev/null; then
+    cat Gemfile.lock | tail -n 2 | grep -C2 "BUNDLED WITH" | tail -n 1 | xargs gem install bundler -v
+fi
+
+# If there's a Gemfile, then run `bundle install`
+# It's assumed that the Gemfile will install Jekyll too
+if [ -f Gemfile ]; then
+    bundle install
+fi

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,5 @@
 blank_issues_enabled: false
 contact_links:
   - name: Ask a question
-    url: https://github.com/pmarsceill/just-the-docs/discussions
+    url: https://github.com/just-the-docs/just-the-docs/discussions
     about: Ask questions and discuss with other community members

.github/dependabot.yml

@@ -0,0 +1,14 @@
+version: 2
+updates:
+- package-ecosystem: npm
+  directory: "/"
+  schedule:
+    interval: daily
+    time: "10:00"
+  open-pull-requests-limit: 10
+- package-ecosystem: bundler
+  directory: "/"
+  schedule:
+    interval: daily
+    time: "10:00"
+  open-pull-requests-limit: 10

.github/release-drafter.yml

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

.github/workflows/ci-master.yml

@@ -1,45 +0,0 @@
-on: 
-  push:
-    branches:
-    - master
-
-name: Master branch CI
-
-jobs:
-
-  jekyll-latest:
-    name: Build Jekyll site (latest)
-    runs-on: ubuntu-latest
-    steps:
-
-    - uses: actions/checkout@master
-
-    - name: Build the site in the jekyll/builder container
-      run: |
-        docker run --rm \
-        --volume="${{ github.workspace }}:/srv/jekyll" \
-        jekyll/builder:latest /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && bundle install && bundle exec jekyll build && bundle exec rake search:init"
-  jekyll-3-8-5:
-    name: Build Jekyll site (v3.8.5)
-    runs-on: ubuntu-latest
-    steps:
-
-    - uses: actions/checkout@master
-
-    - name: Build the site in the jekyll/builder container
-      run: |
-        docker run --rm \
-        --volume="${{ github.workspace }}:/srv/jekyll" \
-        jekyll/builder:3.8.5 /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && bundle install && bundle exec jekyll build && bundle exec rake search:init"
-  assets:
-    name: Format and test CSS and JS
-    runs-on: ubuntu-latest
-
-    steps:
-    - uses: actions/checkout@v2
-    - name: Use Node.js 12.x
-      uses: actions/setup-node@v1
-      with:
-        node-version: '12.x'
-    - run: npm install
-    - run: npm test

.github/workflows/ci.yml

@@ -1,44 +1,50 @@
-on: [pull_request]
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+      - 'v**'
 
 name: CI
 
 jobs:
-
-  jekyll-latest:
-    name: Build Jekyll site (latest)
+  jekyll-build:
+    name: Build Jekyll site
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        jekyll-version: [3.9, 4.3]
     steps:
-
-    - uses: actions/checkout@v2
-
-    - name: Build the site in the jekyll/builder container
-      run: |
-        docker run --rm \
-        --volume="${{ github.workspace }}:/srv/jekyll" \
-        jekyll/builder:latest /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && bundle install && bundle exec jekyll build && bundle exec rake search:init"
-
-  jekyll-3-8-5:
-    name: Build Jekyll site (v3.8.5)
-    runs-on: ubuntu-latest
-    steps:
-
-    - uses: actions/checkout@v2
-
-    - name: Build the site in the jekyll/builder container
-      run: |
-        docker run --rm \
-        --volume="${{ github.workspace }}:/srv/jekyll" \
-        jekyll/builder:3.8.5 /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && bundle install && bundle exec jekyll build && bundle exec rake search:init"
+    - uses: actions/checkout@v3
+    - name: Setup Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.1' # Not needed with a .ruby-version file
+        bundler-cache: false
+    - name: Bundle Install
+      run: bundle install
+    - name: Install Jekyll ${{ matrix.jekyll-version }}
+      run: gem install jekyll -v ${{ matrix.jekyll-version }}
+    - name: Init Search
+      run: bundle exec rake search:init
+    - name: Build Site
+      run: bundle exec jekyll build
 
   assets:
     name: Test CSS and JS
     runs-on: ubuntu-latest
 
+    strategy:
+      matrix:
+        node-version: [18.x]
+
     steps:
-    - uses: actions/checkout@v2
-    - name: Use Node.js 12.x
+    - uses: actions/checkout@v3
+    - name: Use Node.js ${{ matrix.node-version }}
       uses: actions/setup-node@v1
       with:
-        node-version: '12.x'
+        node-version: ${{ matrix.node-version }}
     - run: npm install
     - run: npm test

.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@v3
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.1' # Not needed with a .ruby-version file
+          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@v2
+      - 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@v1
+
+  # 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@v1

.github/workflows/publish-gem.yml

@@ -1,30 +1,31 @@
-name: Publish Gem
+name: Publish Ruby Gem
 
-on: [release]
+on:
+  workflow_dispatch
 
 jobs:
   build:
-    name: Build + Publish
+    name: Publish
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@master
-    - name: Set up Ruby 2.6
+    - uses: actions/checkout@v3
+    - name: Set up Ruby 3.1
       uses: actions/setup-ruby@v1
       with:
-        version: 2.6.x
+        ruby-version: 3.1
 
     - name: Publish to GPR
       run: |
         mkdir -p $HOME/.gem
         touch $HOME/.gem/credentials
         chmod 0600 $HOME/.gem/credentials
-        printf -- "---\n:github: Bearer ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
-        gem build just-the-docs.gemspec
+        printf -- "---\n:github: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
+        gem build *.gemspec
         gem push --KEY github --host https://rubygems.pkg.github.com/${OWNER} *.gem
       env:
-        GEM_HOST_API_KEY: ${{secrets.GPR_AUTH_TOKEN}}
-        OWNER: pmarsceill
+        GEM_HOST_API_KEY: "Bearer ${{secrets.GITHUB_TOKEN}}"
+        OWNER: ${{ github.repository_owner }}
 
     - name: Publish to RubyGems
       run: |
@@ -32,8 +33,7 @@ jobs:
         touch $HOME/.gem/credentials
         chmod 0600 $HOME/.gem/credentials
         printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
-        gem build just-the-docs.gemspec
+        gem build *.gemspec
         gem push *.gem
       env:
-        GEM_HOST_API_KEY: ${{secrets.RUBYGEMS_AUTH_TOKEN}}
-
+        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

@@ -6,3 +6,4 @@
 _site
 Gemfile.lock
 node_modules
+.DS_Store

.prettierignore

@@ -7,3 +7,4 @@ assets/css/just-the-docs-dark.scss
 assets/js/vendor/lunr.min.js
 assets/js/search-data.json
 assets/js/just-the-docs.js
+*.md

.prettierrc

@@ -5,4 +5,3 @@
   "tabWidth": 2,
   "trailingComma": "es5"
 }
-

.stylelintrc.json

@@ -5,9 +5,16 @@
     "assets/css/just-the-docs-dark.scss",
     "_sass/vendor/**/*.scss"
   ],
-  "extends": ["stylelint-config-primer", "stylelint-config-prettier"],
+  "extends": [
+    "stylelint-config-standard-scss",
+    "stylelint-config-prettier-scss"
+  ],
   "plugins": ["stylelint-prettier"],
   "rules": {
-    "prettier/prettier": true
+    "prettier/prettier": true,
+    "alpha-value-notation": null,
+    "color-function-notation": null,
+    "no-descending-specificity": null,
+    "scss/no-global-function-names": null
   }
 }

.vscode/tasks.json

@@ -0,0 +1,26 @@
+{
+  // See https://go.microsoft.com/fwlink/?LinkId=733558
+  // for the documentation about the tasks.json format
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Serve",
+      "type": "shell",
+      "command": "bundle exec jekyll serve --livereload",
+      "group": {
+        "kind": "test",
+        "isDefault": true
+      },
+      "isBackground": true
+    },
+    {
+      "label": "Build",
+      "type": "shell",
+      "command": "bundle exec jekyll build",
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      }
+    }
+  ]
+}

404.html

@@ -8,4 +8,4 @@ search_exclude: true
 
 <h1>Page not found</h1>
 
-<p>The page you requested could not be found. Try using the navigation {% if site.search_enabled != false %}or search {% endif %}to find what you're looking for or go to this <a href="{{ '/' | absolute_url }}">site's home page</a>.</p>
+<p>The page you requested could not be found. Try using the navigation {% if site.search_enabled != false %}or search {% endif %}to find what you're looking for or go to this <a href="{{ '/' | relative_url }}">site's home page</a>.</p>

CHANGELOG.md

@@ -0,0 +1,987 @@
+---
+title: CHANGELOG
+layout: default
+---
+
+# CHANGELOG
+
+All notable user-facing changes to this project are documented in this file.
+
+{: .highlight }
+The project underwent a major maintenance shift in March 2022.
+
+## HEAD
+
+{: .note }
+This website is built from the `HEAD` of the `main` branch of the theme repository.
+
+{: .warning }
+This website includes docs for some new features that are not available in `v0.4.0.rc5` and `v0.3.3`!
+
+Changes to `main` that are *not* in the latest pre-release:
+
+- n/a
+
+## Pre-release v0.4.0.rc5
+
+Hi everyone, we're so excited to finally release `v0.4.0`! For posterity's sake, we're going to release `v0.4.0.rc5` and then immediately re-release it as `v0.4.0`; this should make it more clear what changes were introduced in the lead up to the minor release.
+
+This RC does not introduce any major user-facing features. It adds more customizability for custom SCSS variables (fixing a bug with callout introduction order), `lunr` indexing, and loading `mermaid` locally. In addition, it fixes bugs introduced in `.rc4`: incorrect CSS, inconsistencies with code block backgrounds in dark theme, and the copy code button. It also adds a migration guide for users coming from `v0.3.3`.
+
+### Trying out pre-release `v0.4.0.rc5`
+
+Simlar to the prior release, `v0.4.0.rc5` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` following immediately after. While we don't anticipate many users using this RC, it is still possible to opt-in.
+
+To use this RC explicitly as a remote theme:
+
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.4.0.rc5
+```
+
+To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
+
+```Ruby
+gem "just-the-docs", "0.4.0.rc5"
+```
+
+By default, **users will not be upgraded to `0.4.0.rc5`**. To enforce that explicitly, either:
+
+1. pin your gem version in your `Gemfile`, like so
+```Ruby
+gem "just-the-docs", "0.3.3"
+```
+2. freeze the `remote_theme`, like so
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.3.3
+```
+
+### New Features
+
+- Added: includes for custom `lunr` Liquid and JS code by [@diablodale] in [#1068]
+- Added: new `_sass/custom/setup.scss` for variable definition by [@mattxwang] in [#1135]
+- Added: configuration key to load a local version of mermaid by [@fabrik42] in [#1153]
+
+### Bugfixes and Maintenance
+
+- Fixed: incorrect `padding` property value pair in `search.scss` by [@kevinlin1] in [#1123]
+- Fixed: minor spacing and comment nits by [@EricFromCanada] in [#1128]
+- Fixed: exclude images from being bundled with gem by [@m-r-mccormick] in [#1142]
+- Fixed: dark theme code block background, line number colors by [@m-r-mccormick] in [#1124]
+- Fixed: copy code button interaction with kramdown line numbers by [@mattxwang] in [#1143]
+
+### Docs
+
+- Docs: add a migration guide by [@pdmosses] in [#1059]
+- Docs: update `README` demo video by [@codewithfan] in [#1097]
+- Docs: update "View Typography Utilities" link by [@agabrys] in [#1130]
+- Docs: fix broken relative page links by [@mattxwang] in [#1106]
+- Docs: clarify steps to add custom `lunr` index code by [@diablodale] in [#1139]
+- Docs: label new features introduced in `v0.4` by [@mattxwang] in [#1138]
+
+### New Contributors
+
+- [@kevinlin1] made their first contribution in [#1123]
+- [@codewithfan] made their first contribution in [#1097]
+- [@agabrys] made their first contribution in [#1130]
+- [@diablodale] made their first contribution in [#1068]
+- [@m-r-mccormick] made their first contribution in [#1142]
+- [@fabrik42] made their first contribution in [#1153]
+
+[#1059]: https://github.com/just-the-docs/just-the-docs/pull/1059
+[#1068]: https://github.com/just-the-docs/just-the-docs/pull/1068
+[#1097]: https://github.com/just-the-docs/just-the-docs/pull/1097
+[#1106]: https://github.com/just-the-docs/just-the-docs/pull/1106
+[#1123]: https://github.com/just-the-docs/just-the-docs/pull/1123
+[#1124]: https://github.com/just-the-docs/just-the-docs/pull/1124
+[#1128]: https://github.com/just-the-docs/just-the-docs/pull/1128
+[#1130]: https://github.com/just-the-docs/just-the-docs/pull/1130
+[#1135]: https://github.com/just-the-docs/just-the-docs/pull/1135
+[#1138]: https://github.com/just-the-docs/just-the-docs/pull/1138
+[#1139]: https://github.com/just-the-docs/just-the-docs/pull/1139
+[#1142]: https://github.com/just-the-docs/just-the-docs/pull/1142
+[#1143]: https://github.com/just-the-docs/just-the-docs/pull/1143
+[#1153]: https://github.com/just-the-docs/just-the-docs/pull/1153
+
+[@agabrys]: https://github.com/agabrys
+[@codewithfan]: https://github.com/codewithfan
+[@diablodale]: https://github.com/diablodale
+[@fabrik42]: https://github.com/fabrik42
+[@kevinlin1]: https://github.com/kevinlin1
+[@EricFromCanada]: https://github.com/EricFromCanada
+[@m-r-mccormick]: https://github.com/m-r-mccormick
+
+## Pre-release v0.4.0.rc4
+
+Happy new year! We're celebrating with another pre-release, with features that should help theme users better adapt to changes moving forward. **We aim to re-release this as `v0.4.0`, with only few changes**.
+
+Notable new additions include:
+
+- modular site components, which split up the site into smaller reusable components; advanced theme users can then remix layouts quickly without duplication
+- a "copy code" button to code blocks
+- fixing bugs in generated TOCs and navigation from previous prereleases
+- various cleanups of CSS and HTML markup
+
+The roadmap to `v0.4.0` is small. We are only looking to:
+
+- finish a migration guide, so users can easily upgrade from `v0.3.3` to `v0.4.0`
+- fix one last bug relating to callouts and custom colors
+- fix any new bugs introduced by this pre-release
+
+Have any questions, thoughts, or concerns? We'd love to hear from you! Please [open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know!
+
+### Trying out pre-release `v0.4.0.rc4`
+
+Simlar to the prior release, `v0.4.0.rc4` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc4`.
+
+To use this RC explicitly as a remote theme:
+
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.4.0.rc4
+```
+
+To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
+
+```Ruby
+gem "just-the-docs", "0.4.0.rc4"
+```
+
+By default, **users will not be upgraded to `0.4.0.rc4`**. To enforce that explicitly, either:
+
+1. pin your gem version in your `Gemfile`, like so
+```Ruby
+gem "just-the-docs", "0.3.3"
+```
+2. freeze the `remote_theme`, like so
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.3.3
+```
+
+### New Features
+
+- Added: support multiple Google Analytics tracking IDs, document UA -> GA4 switch by [@MichelleBlanchette] in [#1029]
+- Added: copy code button to code snippets by [@simonebortolin] in [#945]
+- Added: restore simple configuration of `favicon.ico` via `site.static_files` by [@pdmosses] in [#1095]
+- Added: modularize site components by [@mattxwang] in [#1058]
+
+### Bugfixes and Maintenance
+
+- Fixed: incorrect disambiguation in generated TOCs by [@pdmosses] in [#999]
+- Fixed: duplicated external links in collections by [@pdmosses] in [#1001]
+- Fixed: import order of `custom.scss`; puts at end by [@deseo] in [#1010]
+- Fixed: top-level active link styling by [@pdmosses] in [#1015]
+- Fixed: external links for sites with no pages by [@pdmosses] in [#1021]
+- Fixed: duplicate `title` if `jekyll-seo-tag` not in users's plugins by [@Tom-Brouwer] in [#1040]
+- Fixed: removes (duplicate) `favicon.html`, shifts content to `head_custom.html` by [@mattxwang] in [#1027]
+- Fixed: add `reversed`, deprecate `desc` for nav `child_nav_order` by [@jmertic] in [#1061]
+- Fixed: `child.child_nav_order` to `node.child_nav_order` by [@mattxwang] in [#1065]
+- Fixed: remove all uses of `/` as SASS division by [@mattxwang] in [#1074]
+    - note: this was originally merged as [#1074] with a bug; it was reverted in [#1076], and then reimplemented in [#1077]
+- Fixed: skip nav collection generation when site has no pages by [@pdmosses] in [#1092]
+- Fixed: standardize SCSS with `declaration-block-no-redundant-longhand-properties` by [@simonebortolin] in [#1102]
+- Fixed: incorrect `padding` property value pair in `labels.scss` by [@SConaway] in [#1104]
+- Fixed: various bugs with copy code button by [@simonebortolin] in [#1096]
+- Fixed: replace inline styling for `<svg>` icons by [@captn3m0] in [#1110]
+- Vendor: update `jekyll-anchor-headings`, `lunr.js` by [@mattxwang] in [#1071]
+
+### Docs
+
+- Docs: fix typo in changelog links [@koppor] in [#1000]
+- Docs: update homepage (focus: new features, conciseness, deduplication) by [@pdmosses] in [#1018]
+- Docs: update README (focus: new features, conciseness, deduplication) by [@pdmosses] in [#1019]
+- Docs: fix two bugs in "Customization" (custom favicon, new annotation) by [@mattxwang] in [#1090]
+- Docs: Add warning about mandatory `_`-prefix for collections by [@max06] in [#1091]
+- Docs: remove Google Analytics on main site by [@mattxwang] in [#1113]
+
+### New Contributors
+
+- [@koppor] made their first contribution in [#1000]
+- [@deseo] made their first contribution in [#1010]
+- [@Tom-Brouwer] made their first contribution in [#1040]
+- [@simonebortolin] made their first contribution in [#945]
+- [@SConaway] made their first contribution in [#1104]
+- [@captn3m0] made their first contribution in [#1110]
+
+**Full Changelog**: https://github.com/just-the-docs/just-the-docs/compare/v0.4.0.rc3...v0.4.0.rc4
+
+[#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
+[#1058]: https://github.com/just-the-docs/just-the-docs/pull/1058
+[#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
+[#1096]: https://github.com/just-the-docs/just-the-docs/pull/1096
+[#1102]: https://github.com/just-the-docs/just-the-docs/pull/1102
+[#1104]: https://github.com/just-the-docs/just-the-docs/pull/1104
+[#1110]: https://github.com/just-the-docs/just-the-docs/pull/1110
+[#1113]: https://github.com/just-the-docs/just-the-docs/pull/1113
+
+[@captn3m0]: https://github.com/captn3m0
+[@deseo]: https://github.com/deseo
+[@koppor]: https://github.com/koppor
+[@MichelleBlanchette]: https://github.com/MichelleBlanchette
+[@simonebortolin]: https://github.com/simonebortolin
+[@SConaway]: https://github.com/SConaway
+[@Tom-Brouwer]: https://github.com/Tom-Brouwer
+
+## Pre-release v0.4.0.rc3
+
+Hi there! This is (actually) hopefully the last prerelease before `v0.4.0`; in particular, if we find that this prerelease is stable, we'll re-release it as `v0.4.0`.
+
+In general, this is a more mature pre-release; there are few new features. However, we'll highlight [@pdmosses]'s work in [#992] to better optimize nav generation for large sites (ex 100+ pages). We don't expect this to affect most users; however, **it is technically a breaking change**, and we suggest testing your site before upgrading to this prerelease.
+
+We want your feedback! Please [open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know!
+
+As soon as we get stable test results from major downstream users, we'll push out a `v0.4.0` ASAP - closing out almost 2 years of backlogged work!
+
+### Trying out pre-release `v0.4.0.rc3`
+
+Simlar to the prior release, `v0.4.0.rc3` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc3`.
+
+To use this RC explicitly as a remote theme:
+
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.4.0.rc3
+```
+
+To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
+
+```Ruby
+gem "just-the-docs", "0.4.0.rc3"
+```
+
+By default, **users will not be upgraded to `0.4.0.rc3`**. To enforce that explicitly, either:
+
+1. pin your gem version in your `Gemfile`, like so
+```Ruby
+gem "just-the-docs", "0.3.3"
+```
+2. freeze the `remote_theme`, like so
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.3.3
+```
+
+### Features
+
+Broadly, this prerelease is feature-light!
+
+- Added: styling for `<blockquote>` by [@mattxwang] in [#965]
+- Added: custom include for TOC heading by [@pdmosses] in [#980]
+
+### Bugfixes and Experimental Features
+
+*Note*: experimental nav optimization may be unstable. Please give us feedback!
+
+- Added: experimental nav optimization for simple cases by [@pdmosses] in [#992]
+- Fixed: spacing issue when search is disabled by [@henryiii] in [#960]
+- Fixed: active grandchild link class by [@pdmosses] in [#962]
+- Fixed: HTML validation issues (W3C validator) by [@mattxwang] in [#964]
+- Fixed: link styling now uses `text-decoration` values by [@mattxwang] in [#967]
+- Fixed: cleaning up Jekyll excludes by [@pdmosses] in [#985]
+- Fixed: docs, narrow styling for code highlighting with line numbers by [@pdmosses] in [#974]
+- Fixed: default syntax highlighting in custom color schemes [@pdmosses] in [#986]
+
+[#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
+
+[@henryiii]: https://github.com/henryiii
+
+**Full Changelog**: https://github.com/just-the-docs/just-the-docs/compare/v0.4.0.rc2...v0.4.0.rc3
+
+## Pre-release v0.4.0.rc2
+
+{: .warning }
+This website includes docs for some new features that are not available in `v0.4.0.rc1` and `v0.3.3`!
+
+Hey there! This is likely the last pre-release before releasing `v0.4.0`, which we plan on doing soon (i.e. before the end of the month) - very exciting! Some new additions to highlight:
+
+- significant improvement on build time of navigation panel by [@pdmosses]
+  - this is big: for a community member with over 300 pages, we shortened the build time from 3 minutes to 30 seconds!
+- improved accessibility features led by [@JPrevost]
+- more docs!
+
+The intention of this release candidate is to gather even more feedback on a potential `v0.4.0`. As it stands, we have not encountered any breaking changes with early adopters of `v0.4.0.rc1`. If you encounter any - for either of our pre-releases - please let us know!
+
+### Trying out pre-release `v0.4.0.rc2`
+
+Simlar to the prior release, `v0.4.0.rc2` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc2`.
+
+To use this RC explicitly as a remote theme:
+
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.4.0.rc2
+```
+
+To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
+
+```Ruby
+gem "just-the-docs", "0.4.0.rc2"
+```
+
+By default, **users will not be upgraded to `0.4.0.rc2`**. To enforce that explicitly, either:
+
+1. pin your gem version in your `Gemfile`, like so
+```Ruby
+gem "just-the-docs", "0.3.3"
+```
+2. freeze the `remote_theme`, like so
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.3.3
+```
+
+### Features
+
+- Added: accessible titles to nested page nav toggle by [@JPrevost] in [#950]
+- Added: better title styling for AsciiDoc examples by [@alyssais] in [#944]
+- Added: docs for custom search placeholder by [@mattxwang] in [#939]
+- Added: provide ability to skip to main content by [@JPrevost] in [#949]
+- Fixed: exclude `vendor/` in Jekyll config by [@manuelhenke] in [#941]
+- Fixed: improve build time of navigation panel by [@pdmosses] in [#956]
+
+[#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
+
+[@alyssais]: https://github.com/alyssais
+
+### Documentation and Maintenance
+
+- Added: docs load mermaid.js by default by [@mattxwang] in [#935]
+- Fixed: table of contents on search docs by [@robinpokorny] in [#940]
+- Fixed: broken docs link (custom footer) by [@olgarithms] in [#951]
+- Fixed: clarify version docs by [@pdmosses] in [#955]
+- Deleted: unused script directory by [@mattxwang] in [#937]
+
+[#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
+
+### New Contributors
+
+* [@robinpokorny] made their first contribution in [#940]
+* [@olgarithms] made their first contribution in [#951]
+* [@manuelhenke] made their first contribution in [#941]
+* [@JPrevost] made their first contribution in [#950]
+
+[@robinpokorny]: https://github.com/robinpokorny
+[@olgarithms]: https://github.com/olgarithms
+[@manuelhenke]: https://github.com/manuelhenke
+[@JPrevost]: https://github.com/JPrevost
+
+## Pre-release v0.4.0.rc1
+
+### We're back!
+
+Hi all! The Just the Docs team is excited to have our first pre-release in over two years! It is jam-packed with features and bugfixes that have been requested by the community since 2020. They include:
+
+- The new callouts component
+- Allowing pages and collections to coexist on the navigation pane
+- New styling: dark syntax highlighting, support for jekyll-asciidoc, word-wrapping instead of overflow for various elements
+- More customization: external nav links, custom nav footers, favicon includes, search color and placeholder configuration, mermaid.js support, and nav sorting
+- Over 20 bugfixes! Big ones include fixing the `rake` command, using `relative_url`, and search input color
+- More documentation, especially on using custom includes
+- Updating core dependencies to stable Ruby versions
+- A WIP [template repository](https://github.com/just-the-docs/just-the-docs-template) that allows you to setup your own repository using Just the Docs and GitHub Pages with one click - give it a shot! More documentation, etc. is on the way!
+
+We want your feedback! Are these changes helpful? Are our docs easy to understand? Should new features like `mermaid` be opt-in or opt-out? Please [open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know!
+
+### Trying out pre-release `v0.4.0.rc1`
+
+Due to the massive scope of these changes, we're making `v0.4.0.rc1` avaialble as a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc1`.
+
+To use this RC explicitly as a remote theme:
+
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.4.0.rc1
+```
+
+To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
+
+```Ruby
+gem "just-the-docs", "0.4.0.rc1"
+```
+
+### Staying on `v0.3.3`
+
+If you're not ready to make the switch, that's alright! If your version of just-the-docs is pinned to `v0.3.3` (i.e. by a `Gemfile.lock` or in `remote_theme`, then there's nothing you need to do.
+
+If you have not pinned your theme version, you should either:
+
+1. pin your gem version in your `Gemfile`, like so
+```Ruby
+gem "just-the-docs", "0.3.3"
+```
+2. freeze the `remote_theme`, like so
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.3.3
+```
+
+{: .warning }
+Use of branches for closed PRs (e.g., [#466], [#578]) is now deprecated, as those branches have been (directly or indirectly) merged, and they may be deleted after the pre-release of `v0.4.0.rc1`.
+
+### Maintenance
+
+Internally, our maintainer team has expanded: [Patrick Marsceill][@pmarsceill], the original maintainer, has stepped down from an active role after almost 4 years! We're very thankful for the work that he's done to create and maintain one of the most popular Jekyll themes. Please join us in giving him thanks!
+
+The new core team currently consists of [@mattxwang], [@pdmosses], [@skullface], [@dougaitken], and [@max06]. Over the past six months, we've been triaging and merging in PRs, as well as contributing our own fixes. We'll continue to address open issues, merge in PRs from the community, and plan out the future of Just the Docs. If you'd like to contribute, now is a great time!
+
+[@mattxwang]: https://github.com/mattxwang
+[@pdmosses]: https://github.com/pdmosses
+[@skullface]: https://github.com/skullface
+[@dougaitken]: https://github.com/dougaitken
+[@max06]: https://github.com/max06
+
+### Roadmap
+
+In the short-term, we're committed to tidying up everything for a `v0.4.0` release. This involves fixing bugs reported from the community in this pre-release, as well as continually merging in minor PRs.
+
+We're also scoping out medium and long-term projects, and want to keep you in the loop. These include:
+
+- upgrading to Jekyll 4, and stopping support for Jekyll 3
+- versioned docs - issue [#728]
+- improved accessibility - issues [#566], [#870]
+- internationalization (i18n) - issue [#59]
+- recursive/multi-level navigation - PR [#462]
+- toggleable dark mode - issue [#234]
+
+as well as DX improvements like better regression tests, CI, and tooling. If you're interested in any of these, please join us [on GitHub](https://github.com/just-the-docs/just-the-docs) - any contribution (raising an issue, writing docs, or submitting a PR) is welcome!
+
+[#728]: https://github.com/just-the-docs/just-the-docs/issues/728
+[#566]: https://github.com/just-the-docs/just-the-docs/issues/566
+[#870]: https://github.com/just-the-docs/just-the-docs/issues/870
+[#59]: https://github.com/just-the-docs/just-the-docs/issues/59
+[#462]: https://github.com/just-the-docs/just-the-docs/pull/462
+[#234]: https://github.com/just-the-docs/just-the-docs/issues/234
+
+### Features
+
+* Added: Combination by [@pdmosses] in [#578]
+  - Added: dark highlighting in [#463]
+  - Added: pages and collections in [#448]
+  - Added: callouts in [#466]
+  - Fixed: breadcrumb behaviour … by [@AdityaTiwari2102] in [#477]
+  - Fixed: prevent rake command corrupting search data in [#495] (also listed below)
+  - Fixed: nested lists in [#496]
+  - Fixed: set color for search input in [#498] (also listed below)
+  - Fixed: sites with no child pages (no PR)
+  - Fixed: TOC/breadcrumbs for multiple collections in [#494]
+  - Added: collection configuration option `nav_fold` (no PR)
+  - Fixed: indentation and color for folded collection navigation (no PR)
+  - Fixed: scroll navigation to show the link to the current page in [#639]
+  - Fixed: Replace all uses of `absolute_url` by `relative_url`, by [@svrooij] in [#544]
+* Added: custom favicon `_includes` by [@burner1024] in [#364]
+* Added: set color for search input by [@pdmosses] in [#498]
+* Added: search placeholder configuration by [@mattxwang] in [#613]
+* Added: 'child_nav_order' front matter to be able to sort navigation pages in reverse by [@jmertic] in [#726]
+* Added: `nav_footer_custom` include by [@nathanjessen] in [#474]
+* Added: style fixes for jekyll-asciidoc by [@alyssais] in [#829]
+* Added: mermaid.js support by [@nascosto] in [#857]
+* Added: support for external navigation links by [@SPGoding] in [#876]
+* Added: refactor `mermaid` config to use `mermaid_config.js` include, only require `mermaid.version` in `_config.yml` by [@mattxwang] in [#909]
+* Fixed: prepend `site.collections_dir` if exists by [@alexsegura] in [#519]
+* Fixed: nested task lists (#517) by [@pdmosses] in [#855]
+* Fixed: suppress Liquid processing in CSS comments by [@pdmosses] in [#686]
+* Fixed: prevent rake command from corrupting search data by [@pdmosses] in [#495]
+* Fixed: anchor heading links should be visible on focus by [@jacobhq] in [#846]
+* Fixed: add `overflow-x: auto` to `figure.highlight` by [@iridazzle] in [#727]
+* Fixed: add `overflow-wrap: word-break` to `body` by [@iridazzle] in [#889]
+* Fixed: vertical alignment for consecutive labels by [@Eisverygoodletter] in [#893]
+* Fixed: allow links to wrap by [@pdmosses] in [#905]
+* Fixed: nav scroll feature and absolute/relative URLs by [@pdmosses] in [#898]
+
+[#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
+
+### Documentation
+
+* Added: docs on how to break an `ol` by [@pdmosses] in [#856]
+* Added: docs for custom includes by [@nathanjessen] in [#806]
+* Added: document caveat about variable dependencies by [@waldyrious] in [#555]
+* Added: docs on how to use `custom_head` to add a custom favicon by [@UnclassedPenguin] in [#814]
+* Fixed: `ol` on `index.md` by [@pmarsceill] in [#778]
+* Fixed: image link in Markdown kitchen sink by [@JeffGuKang] in [#221]
+* Fixed: images in Markdown kitchen sink by [@dougaitken] in [#782]
+* Fixed: clearer label of link to Jekyll quickstart by [@waldyrious] in [#549]
+* Fixed: remove extra spaces in component docs by [@MichelleBlanchette] in [#554]
+* Fixed: double "your" typo in `index.md` by [@sehilyi] in [#499]
+* Fixed: "you" -> "your" typo in `index.md` by [@nathanjessen] in [#473]
+* Fixed: spacing in toc example by [@henryiii] in [#835]
+* Fixed: typo in `README` on `_config.yml` by [@ivanskodje] in [#891]
+* Fixed: missing code fence in navigation structure docs by [@mattxwang] in [#906]
+
+[#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
+
+### Maintenance
+
+* Added: VScode devcontainer by [@max06] in [#783]
+* Added: `webrick` to `Gemfile` by [@mattxwang] in [#799]
+* Added: 'This site is powered by Netlify.' to the footer by [@mattxwang] in [#797]
+* Updated: new repo path by [@pmarsceill] in [#775]
+* Updated: rename `master` -> `main` by [@pmarsceill] in [#776]
+* Updated: README by [@pmarsceill] in [#777]
+* Updated: Code of Conduct to Contributor Covenant v2.1 by [@mattxwang] in [#790]
+* Updated: CI files, Ruby & Node Versions by [@mattxwang] in [#820]
+* Updated: Stylelint to v14, extend SCSS plugins, remove primer-* configs, resolve issues by [@mattxwang] in [#821]
+
+[#783]: https://github.com/just-the-docs/just-the-docs/pull/783
+[#799]: https://github.com/just-the-docs/just-the-docs/pull/799
+[#797]: https://github.com/just-the-docs/just-the-docs/pull/797
+[#775]: https://github.com/just-the-docs/just-the-docs/pull/775
+[#776]: https://github.com/just-the-docs/just-the-docs/pull/776
+[#777]: https://github.com/just-the-docs/just-the-docs/pull/777
+[#790]: https://github.com/just-the-docs/just-the-docs/pull/790
+[#820]: https://github.com/just-the-docs/just-the-docs/pull/820
+[#821]: https://github.com/just-the-docs/just-the-docs/pull/821
+
+### Dependencies
+
+* Upgrade to GitHub-native Dependabot by @dependabot-preview in [#627]
+* [Security] Bump y18n from 3.2.1 to 3.2.2 by @dependabot-preview in [#606]
+* [Security] Bump hosted-git-info from 2.7.1 to 2.8.9 by @dependabot-preview in [#641]
+* [Security] Bump lodash from 4.17.19 to 4.17.21 by @dependabot-preview in [#640]
+* [Security] Bump ini from 1.3.5 to 1.3.8 by @dependabot-preview in [#511]
+* Bump path-parse from 1.0.6 to 1.0.7 by @dependabot in [#699]
+* Bump ajv from 6.10.0 to 6.12.6 by @dependabot in [#766]
+* Bump prettier from 2.1.2 to 2.5.1 by @dependabot in [#787]
+* Bump prettier from 2.5.1 to 2.6.2 by @dependabot in [#809]
+* Bump prettier from 2.6.2 to 2.7.1 by @dependabot in [#864]
+
+[#627]: https://github.com/just-the-docs/just-the-docs/pull/627
+[#606]: https://github.com/just-the-docs/just-the-docs/pull/606
+[#641]: https://github.com/just-the-docs/just-the-docs/pull/641
+[#640]: https://github.com/just-the-docs/just-the-docs/pull/640
+[#511]: https://github.com/just-the-docs/just-the-docs/pull/511
+[#699]: https://github.com/just-the-docs/just-the-docs/pull/699
+[#766]: https://github.com/just-the-docs/just-the-docs/pull/766
+[#787]: https://github.com/just-the-docs/just-the-docs/pull/787
+[#809]: https://github.com/just-the-docs/just-the-docs/pull/809
+[#864]: https://github.com/just-the-docs/just-the-docs/pull/864
+
+### New Contributors
+
+* [@AdityaTiwari2102] made their first contribution in [#477]
+* [@svrooij] made their first contribution in [#544]
+* [@alexsegura] made their first contribution in [#519]
+* [@burner1024] made their first contribution in [#364]
+* [@JeffGuKang] made their first contribution in [#221]
+* [@dougaitken] made their first contribution in [#782]
+* [@max06] made their first contribution in [#783]
+* [@sehilyi] made their first contribution in [#499]
+* [@nathanjessen] made their first contribution in [#473]
+* [@waldyrious] made their first contribution in [#549]
+* [@MichelleBlanchette] made their first contribution in [#554]
+* [@henryiii] made their first contribution in [#835]
+* [@jmertic] made their first contribution in [#726]
+* [@jacobhq] made their first contribution in [#846]
+* [@UnclassedPenguin] made their first contribution in [#814]
+* [@alyssais] made their first contribution in [#829]
+* [@nascosto] made their first contribution in [#857]
+* [@SPGoding] made their first contribution in [#876]
+* [@iridazzle] made their first contribution in [#727]
+* [@ivanskodje] made their first contribution in [#891]
+* [@Eisverygoodletter] made their first contribution in [#893]
+
+[@AdityaTiwari2102]: https://github.com/AdityaTiwari2102
+[@svrooij]: https://github.com/svrooij
+[@alexsegura]: https://github.com/alexsegura
+[@burner1024]: https://github.com/burner1024
+[@JeffGuKang]: https://github.com/JeffGuKang
+[@dougaitken]: https://github.com/dougaitken
+[@max06]: https://github.com/max06
+[@sehilyi]: https://github.com/sehilyi
+[@nathanjessen]: https://github.com/nathanjessen
+[@waldyrious]: https://github.com/waldyrious
+[@MichelleBlanchette]: https://github.com/MichelleBlanchette
+[@henryiii]: https://github.com/henryiii
+[@jmertic]: https://github.com/jmertic
+[@jacobhq]: https://github.com/jacobhq
+[@UnclassedPenguin]: https://github.com/UnclassedPenguin
+[@alyssais]: https://github.com/alyssais
+[@nascosto]: https://github.com/nascosto
+[@SPGoding]: https://github.com/SPGoding
+[@iridazzle]: https://github.com/iridazzle
+[@ivanskodje]: https://github.com/ivanskodje
+[@Eisverygoodletter]: https://github.com/Eisverygoodletter
+
+**Full Changelog**: https://github.com/just-the-docs/just-the-docs/compare/v0.3.3...v0.4.0.rc1
+
+[@pmarsceill]: https://github.com/pmarsceill
+
+## v0.3.3
+
+### 🚀 Features
+
+- Add custom header and footer include files @CodeSandwich (#334)
+
+### 🐛 Bug Fixes
+
+- Limit the effect of `nav_exclude` to the main navigation @pdmosses (#443)
+- Update normalize.scss @pdmosses (#444)
+- Update code.scss @pdmosses (#445)
+- Fix list alignment @pdmosses (#446)
+
+### 🧰 Maintenance
+
+- Bump stylelint-config-primer from 9.0.0 to 9.2.1 @dependabot-preview (#451)
+- Bump stylelint from 13.6.1 to 13.7.2 @dependabot-preview (#440)
+- Bump @primer/css from 15.1.0 to 15.2.0 @dependabot-preview (#436)
+- Bump prettier from 2.1.1 to 2.1.2 @dependabot-preview (#429)
+
+## v0.3.2
+
+### Changes
+
+- Safe page sorting @pdmosses (#411)
+- v0.3.2 @pmarsceill (#388)
+
+### 🚀 Features
+
+- make font-sizes sass variables so they can be changed @pdebruic (#361)
+- run the site locally inside docker container @fogfish (#398)
+- Feature/doc collections @SgtSilvio (#379)
+- Adjust dl layout @pdmosses (#401)
+
+### 🐛 Bug Fixes
+
+- Add site.gh_edit_source to "Edit this page on GitHub" link @mrfleap (#418)
+- Inhibit text-transform for code in h4 @pdmosses (#404)
+- Fix native font stack precedence issue on Windows systems. @hvianna (#331)
+- Support for the linenos option on highlighted code @pdmosses (#375)
+- Update anchor_headings.html @pdmosses (#399)
+- Fix https @marksie1988 (#359)
+
+### 🧰 Maintenance
+
+- Bump prettier from 2.0.5 to 2.1.1 @dependabot-preview (#427)
+- Bump prettier from 2.0.5 to 2.1.1 @dependabot-preview (#419)
+- [Security] Bump lodash from 4.17.15 to 4.17.19 @dependabot-preview (#389)
+- Bump @primer/css from 14.4.0 to 15.1.0 @dependabot-preview (#402)
+- Bump lodash from 4.17.15 to 4.17.19 @dependabot (#384)
+- Bump @primer/css from 14.4.0 to 15.0.0 @dependabot-preview (#371)
+
+
+## v0.3.1
+
+### Changes
+
+### 🐛 Bug Fixes
+
+- Improve accessibility by adding label to Anchor links. @mscoutermarsh (#376)
+
+### 🧰 Maintenance
+
+- Remove collapsible TOC on nav doc @pmarsceill (#368)
+- Pdmosses collapsible toc @pmarsceill (#367)
+
+
+## v0.3.0
+
+### Changes
+
+- v0.2.9 @pmarsceill (#306)
+
+### 🚀 Features
+
+- Add print styles @pmarsceill (#362)
+- Navigation improvements and search sections @SgtSilvio (#352)
+
+### 🐛 Bug Fixes
+
+- Remove constraint with jekyll 4.1.0 @PierrickMartos (#348)
+
+### 🧰 Maintenance
+
+- Bump version numbers @pmarsceill (#360)
+- Bump stylelint from 13.3.3 to 13.6.1 @dependabot-preview (#343)
+- Bump stylelint-config-prettier from 8.0.1 to 8.0.2 @dependabot-preview (#349)
+
+
+## v0.2.9
+
+### Bug fixes
+- Horizontal Alignment #103 @pmarsceill
+- Code snippet in headers do not inherit font size #140 @pmarsceill
+- Fix duplicated title and description tags #294 @iefserge
+- Update nav.html for handling nav_exclude #282 @blawqchain
+- Fix duplicate entries in nav.html and default.html #239 @KasparEtter
+- Don't show pages with no title (e.g. redirects in nav) https://github.com/pmarsceill/just-the-docs/pull/295/commits/672de29f2e332a9350af7237e4fb6693c848989e @SgtSilvio
+- [SEARCH RAKE] Fix search generator #319 @RoiArthurB
+
+### Enhancements
+- Improvement/custom themes #186 @SgtSilvio
+- feat: adds "edit this page" and "page last modified" to footer #217 @malsf21
+- feat: adds option to open aux links in new tab #229 @malsf21
+- Default nav order #236 @pdmosses
+- Enable IP anonymization in Google Analytics (GDPR) #250 @r-brown
+
+closes #240 #308 #266 #140 #103
+
+## v0.2.8
+
+### Bugfixes
+- bugfix in search.rake #218 @tiaitsch85
+
+### Dependency and security updates:
+
+- Update jekyll requirement from ~> 3.8.5 to >= 3.8.5, < 4.1.0 #197 @dependabot-preview
+- Update rake requirement from ~> 12.3.1 to >= 12.3.1, < 13.1.0 #227 @dependabot-preview
+- Bump stylelint-config-primer from 8.0.0 to 9.0.0 #247 @dependabot-preview
+- Update bundler requirement from ~> 2.0.1 to ~> 2.1.4 #268 @dependabot-preview
+- Bump @primer/css from 12.7.0 to 14.3.0 #296 @dependabot-preview
+
+### Operations
+
+- Update CI to test multiple versions of Jekyll
+- Update CI to check the rake command that builds the search file
+
+fixes #291 #256 #293 #177
+
+## v0.2.7
+
+### Bugs fixed
+- Anchor headings are now displayed on hover, not only on heading hover
+- Deduplicated anchor heading svg
+- If last page of `site.html_pages` was excluded from search, search json breaks
+- Config variable should be `blanklines` not `blank_lines` for html compression
+- `list-style-none` does not hide bullets on `ul`
+
+### Enhancements
+- Summary for child pages appears in generated TOC
+- Site logo configuration supported replacing title text with image
+- Allow custom CSS overrides (new scss partial at the end of the cascade) separate from variable overrides.
+- Configuration around search strings added to allow search for hyphenated words
+
+### Maintenance
+- Update docs to suggest using index.md as section page filename
+- Bump @primer/css from 12.6.0 to 12.7.0
+- Bump mixin-deep from 1.3.1 to 1.3.2
+- Bump stylelint-config-primer from 7.0.1 to 8.0.0
+
+### PR included
+- #98 by @stefanoborini Introduces the possibility for a summary in the table of contents
+- #141 by @ghabs Fix trailing comma bug in search-data.json
+- #153 by @jacobherrington Change button copy on theme preview
+- #181 by @m3nu Recommend using index.md as parent page for sections
+- #183 by @SgtSilvio Improve heading anchors
+- #187 by @SgtSilvio Improvement/site logo
+- #200 Bump mixin-deep from 1.3.1 to 1.3.2
+- #203 by @pdmosses Search config
+- #205 by @pdmosses Fix blank_lines var to blanklines in config.yml
+- #206 by @iamcarrico Allow for custom overrides by the user
+- #208 Bump @primer/css from 12.6.0 to 12.7.0
+- #213 Bump mixin-deep from 1.3.1 to 1.3.2
+- #214 Bump stylelint-config-primer from 7.0.1 to 8.0.0
+- #215 Bump @primer/css from 12.6.0 to 12.7.0
+
+## v0.2.6
+
+### Bugs fixed
+- Google Analytics tag has been updated #162
+- ~BaseURL has been modified #109~ Reverted -- seems the existing implementation worked
+- Titles can now wrap fixes #106
+
+### Enhancements
+- Search now displays content preview #135
+- Custom footer content added #179
+- Now using GitHub Actions for CI #170
+
+### Maintenance
+- lunrjs upgraded #135
+- Nav generation is optimized #159
+- Stylelint upgrade #143
+- Stylelint config primer upgrade #149
+- Lodash upgrade #160
+
+### PR included
+~#109 by @daviddarnes - Fix baseurl link~ Reverted
+#135 by @SgtSilvio - Upgrades lunr.js, improves search UI, adds heading anchors
+#152 by @yavorg - Improves syntax highlighting for js readablity
+#159 by @julienduchesne - Optimizes nav generation
+#162 by @nergmada - Modifies the google analytics code to match the new tags used by GA
+
+
+## v0.2.5
+
+### Bugs fixed
+
+- Duplicate title tag when Jekyll SEO Plugin gem is used #125 #126
+
+### Enhancements
+
+- Favicon support added #118
+
+### Maintenance
+- Bump stylelint-config-primer from 6.0.0 to 7.0.0  #123
+- Bump @primer/css from 12.2.3 to 12.3.1 #129
+- Add workflow to publish to GPR
+- Fix workflow to publish to Ruby Gems
+
+## v0.2.4
+
+### Bugs
+
+- #102 Remove unnecessary console.log() @JoeNyland
+- #97 Import custom Sass variable overrides before default variables are defined @montchr and @ptvandi
+
+### Additions
+- #117 Add links to docs for setting up GH pages locally @gnarea
+- #95 Add SEO and 'lang' param for `_config` @gebeto
+
+## v0.2.3
+
+### Enhancements
+- Adds ability to use Google Analytics tracking by @pmarsceill
+
+### Bug fixes
+- Fixes 404 error for "/assets/js//search-data.json" by @stephenedmondson
+- Fixes #80 Single quotes in the string were unescaped and ruby attempted variable substitution of amp within it (which failed) by @novelistparty
+- Fixes bug that would only show 2 or more search results (not one) by @ilivewithian
+- Fixes a typo on the layout example by @woernfl
+- Fixes #78 Page scroll position too far down on load by @pmarsceill
+- Fixds ability to nest ul in ol without breaking style or counters
+
+### Dependency updates
+- Bumps stylelint dependency from 9.9.0 to 9.10.1
+
+## v0.2.2
+
+- Bumps stylelint-config-primer to 3.0.1 #44
+- Bumps bundler req to 2.0.1 #61
+- Adds custom 404 page
+- Excludes package-lock.json from jekyll build #47
+- Fixes keyboard scrolling / focus #48
+- Adds ARIA roles to navigation elements
+- Adds support for optional page description metadata (if present in yaml front matter)
+- Addresses some issues with search in #46
+- Option to hide TOC on parent pages if turned off in page's YAML front matter #30
+- Option to suppress an item from being indexed by search if present in page's YAML front matter #32
+
+## v0.2.1
+
+This update fixes security vulnerablities in the lodash sub-dependency and bumps other dev dependencies to their latest version.
+
+## v0.2.0
+
+Adds:
+- Dark mode via `color_scheme` parameter
+- Ability to exclude a page from the main nav with `nav_exclude` parameter closes #21
+- Ability for create children of children pages (3 nav levels) closes #25
+
+Changes:
+- Permalink structure for tiered navigation has been updated
+- Some colors have been updated for consistency / accessibility
+
+## v0.1.6
+
+### Added
+
+- Support for task list styles #19
+- Configuration docs
+- Configuration option to enable / disable search
+- Normalize.scss dependency pulled into project #16 #
+
+### Fixed
+
+- Layout bug in navigation #17
+
+## v0.1.5
+
+Major changes:
+
+- Fixed bug where the rake task would fail when the assets/js directory didn't exist
+
+## v0.1.4
+
+Major changes:
+- Adds Rake as a runtime dependency
+- Definition list styled
+- Sidebar and support cleaned up for smaller screen support
+- Updated some stale docs
+
+## v0.1.3
+
+Major changes:
+- Fix path problems, typos, and general clean-up for OSS.
+
+## v0.1.2
+
+Fix paths when deployed to gh-pages
+
+## v0.1.1
+
+Major updates:
+- Adds search to mobile nav
+- Pulls footer to bottom of the page on mobile (not hidden in nav)
+
+Minor updates:
+- Cleans up h1 typography spacing

CODE_OF_CONDUCT.md

@@ -2,45 +2,131 @@
 
 ## Our Pledge
 
-In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
 
 ## Our Standards
 
-Examples of behavior that contributes to creating a positive environment include:
+Examples of behavior that contributes to a positive environment for our
+community include:
 
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
 
-Examples of unacceptable behavior by participants include:
+Examples of unacceptable behavior include:
 
-* The use of sexualized language or imagery and unwelcome sexual attention or advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
 * Public or private harassment
-* Publishing others' private information, such as a physical or electronic address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a professional setting
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
 
-## Our Responsibilities
+## Enforcement Responsibilities
 
-Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
 
-Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
 
 ## Scope
 
-This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at patrick.marsceill@gmail.com. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+patrick.marsceill@gmail.com.
+All complaints will be reviewed and investigated promptly and fairly.
 
-Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
 
-[homepage]: http://contributor-covenant.org
-[version]: http://contributor-covenant.org/version/1/4/
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

Dockerfile

@@ -1,4 +1,4 @@
-FROM ruby:2.6
+FROM ruby:2.7
 
 ENV LC_ALL C.UTF-8
 ENV LANG en_US.UTF-8
@@ -10,4 +10,3 @@ COPY Gemfile just-the-docs.gemspec ./
 RUN gem install bundler && bundle install
 
 EXPOSE 4000
-

Gemfile

@@ -1,2 +1,4 @@
 source "https://rubygems.org"
 gemspec
+
+gem "webrick", "~> 1.7"

MIGRATION.md

@@ -0,0 +1,404 @@
+---
+title: Migration and Upgrading
+layout: default
+---
+
+# Migrating and Upgrading
+
+Summary
+:   A site that uses `just-the-docs` (as a theme or as a remote them) 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.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>.
+
+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.github.io/just-the-docs
+
+#### 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)
+
+Brief descriptions of the following changes are to be added below.
+
+#### 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

@@ -1,19 +1,42 @@
 <p align="right">
-    <a href="https://badge.fury.io/rb/just-the-docs"><img src="https://badge.fury.io/rb/just-the-docs.svg" alt="Gem version"></a> <a href="https://github.com/pmarsceill/just-the-docs/actions?query=workflow%3A%22Master+branch+CI%22"><img src="https://github.com/pmarsceill/just-the-docs/workflows/Master%20branch%20CI/badge.svg" alt="Build status"></a>
+    <a href="https://badge.fury.io/rb/just-the-docs"><img src="https://badge.fury.io/rb/just-the-docs.svg" alt="Gem version"></a> <a href="https://github.com/just-the-docs/just-the-docs/actions/workflows/ci.yml"><img src="https://github.com/just-the-docs/just-the-docs/actions/workflows/ci.yml/badge.svg" alt="CI Build status"></a> <a href="https://app.netlify.com/sites/just-the-docs/deploys"><img src="https://api.netlify.com/api/v1/badges/9dc0386d-c2a4-4077-ad83-f02c33a6c0ca/deploy-status" alt="Netlify Status"></a>
 </p>
 <br><br>
 <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://pmarsceill.github.io/just-the-docs/">See it in action!</a></strong></p>
+    <p align="center"><strong><a href="https://just-the-docs.github.io/just-the-docs/">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
 
-Add this line to your Jekyll site's Gemfile:
+### Use the template
+
+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]"!
+
+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.
+
+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.
+
+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"
@@ -39,18 +62,20 @@ Alternatively, you can run it inside Docker while developing your site
 
 ## Usage
 
-[View the documentation](https://pmarsceill.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/pmarsceill/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:
 
-- Open a [Pull Request](https://github.com/pmarsceill/just-the-docs/pulls)
+- 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:
 
@@ -61,12 +86,25 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/pmarsc
 
 ## 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.github.io/just-the-docs/
+[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

@@ -16,18 +16,32 @@
 title: Just the Docs
 description: A Jekyll theme for documentation
 baseurl: "/just-the-docs" # the subpath of your site, e.g. /blog
-url: "https://pmarsceill.github.io" # the base hostname & protocol for your site, e.g. http://example.com
+url: "https://just-the-docs.github.io" # the base hostname & protocol for your site, e.g. http://example.com
 
 permalink: pretty
-exclude: ["node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json",  "script/", "LICENSE.txt", "lib/", "bin/", "README.md", "Rakefile"
-, "docs/tests/"
-]
 
-# Regression tests
-# By default, the pages in /docs/tests are excluded when the ste is built.
-# To include them, comment-out the relevant line above.
-# Uncommenting the following line doesn't work - see https://github.com/jekyll/jekyll/issues/4791
-# include: ["docs/tests/"]
+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
 
 # Set a path/url to a logo that will be displayed instead of the title
 #logo: "/assets/images/just-the-docs.png"
@@ -59,13 +73,28 @@ search:
   # Supports true or false (default)
   button: false
 
+# For copy button on code
+enable_copy_code_button: true
+
+# To disable support for mermaid diagrams (https://mermaid.js.org),
+# comment out the `mermaid` and `version` keys below
+# By default, consuming the theme as a gem leaves mermaid disabled; it is opt-in
+mermaid:
+  # Version of mermaid library
+  # Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/
+  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 file use the `path` key to specify the location of the library instead; e.g.
+  # path: "/assets/js/mermaid.min.js"
+
 # Enable or disable heading anchors
 heading_anchors: true
 
 # Aux links for the upper right navigation
 aux_links:
   "Just the Docs on GitHub":
-    - "//github.com/pmarsceill/just-the-docs"
+    - "//github.com/just-the-docs/just-the-docs"
 
 # Makes Aux links open in a new tab. Default is false
 aux_links_new_tab: false
@@ -74,6 +103,11 @@ aux_links_new_tab: false
 # nav_sort: case_insensitive # default, equivalent to nil
 nav_sort: case_sensitive # Capital letters sorted before lowercase
 
+# External navigation links
+nav_external_links:
+  - title: Just the Docs on GitHub
+    url: https://github.com/just-the-docs/just-the-docs
+
 # Footer content
 # appears at the bottom of every page's main content
 
@@ -81,7 +115,7 @@ nav_sort: case_sensitive # Capital letters sorted before lowercase
 back_to_top: true
 back_to_top_text: "Back to top"
 
-footer_content: "Copyright &copy; 2017-2020 Patrick Marsceill. Distributed by an <a href=\"https://github.com/pmarsceill/just-the-docs/tree/master/LICENSE.txt\">MIT license.</a>"
+footer_content: "Copyright &copy; 2017-2020 Patrick Marsceill. Distributed by an <a href=\"https://github.com/just-the-docs/just-the-docs/tree/main/LICENSE.txt\">MIT license.</a> <a href=\"https://www.netlify.com/\">This site is powered by Netlify.</a>"
 
 # Footer last edited timestamp
 last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter
@@ -92,18 +126,36 @@ last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https:/
 # Footer "Edit this page on GitHub" link text
 gh_edit_link: true # show or hide edit this page link
 gh_edit_link_text: "Edit this page on GitHub"
-gh_edit_repository: "https://github.com/pmarsceill/just-the-docs" # the github URL for your repo
-gh_edit_branch: "master" # the branch that your docs is served from
+gh_edit_repository: "https://github.com/just-the-docs/just-the-docs" # the github URL for your repo
+gh_edit_branch: "main" # the branch that your docs is served from
 # gh_edit_source: docs # the source that your files originate from
 gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately
 
 # 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
-ga_tracking: UA-2709176-10
-ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true/nil by default)
+# Supports a CSV of tracking ID strings (eg. "UA-1234567-89,G-1AB234CDE5")
+# Note: the main Just the Docs site does *not* use Google Analytics.
+# 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

_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,15 @@
+{% 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 %}

_includes/components/children_nav.html

@@ -0,0 +1,9 @@
+<hr>
+{% include toc_heading_custom.html %}
+<ul>
+  {% for child in include.toc_list %}
+    <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,5 @@
+<script>
+  var config = {% include mermaid_config.js %};
+  mermaid.initialize(config);
+  window.mermaid.init(undefined, document.querySelectorAll('.language-mermaid'));
+</script>

_includes/components/search_footer.html

@@ -0,0 +1,7 @@
+{% if site.search.button %}
+<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>

_includes/components/search_header.html

@@ -0,0 +1,9 @@
+{% capture search_placeholder %}{% include search_placeholder_custom.html %}{% endcapture %}
+
+<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>

_includes/components/sidebar.html

@@ -0,0 +1,69 @@
+<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 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.nav_external_links -%}
+      <ul class="nav-list">
+        {%- for node in site.nav_external_links -%}
+          <li class="nav-list-item external">
+            <a href="{{ node.url | absolute_url }}" class="nav-list-link external">
+              {{ node.title }}
+              {% unless node.hide_icon %}<svg viewBox="0 0 24 24" aria-labelledby="svg-external-link-title"><use xlink:href="#svg-external-link"></use></svg>{% endunless %}
+            </a>
+          </li>
+        {%- endfor -%}
+      </ul>
+    {%- endif -%}
+    {% if site.just_the_docs.collections %}
+      {% assign collections_size = site.just_the_docs.collections | size %}
+      {% for collection_entry in site.just_the_docs.collections %}
+        {% assign collection_key = collection_entry[0] %}
+        {% assign collection_value = collection_entry[1] %}
+        {% assign collection = site[collection_key] %}
+        {% if collection_value.nav_exclude != true %}
+          {% if collections_size > 1 or pages_top_size > 0 %}
+            {% if collection_value.nav_fold == true %}
+              <ul class="nav-list nav-category-list">
+                <li class="nav-list-item{% if page.collection == collection_key %} active{% endif %}">
+                  {%- if collection.size > 0 -%}
+                  <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>

_includes/css/callouts.scss.liquid

@@ -0,0 +1,93 @@
+{%- comment -%}
+  {% include css/callouts.scss.liquid color_scheme = string %}
+  produces SCSS for all the callouts in site.callouts. For the "dark"
+  color scheme, the levels of the text and background colors are reversed.
+{%- endcomment -%}
+
+{%- assign callout_background_hue = "000" -%}
+{%- assign callout_color_hue = "300" -%}
+{%- if site.callouts_level == "loud" or include.color_scheme == "dark" and site.callouts_level != "quiet" -%}
+  {%- assign callout_background_hue = "300" -%}
+  {%- assign callout_color_hue = "000" -%}
+{%- endif -%}
+
+div.opaque {
+  background-color: $body-background-color;
+}
+
+{%- for callout in site.callouts %}
+
+{%- assign callout_opacity = callout[1].opacity | default: site.callouts_opacity | default: 0.2 -%}
+
+p.{{ callout[0] }}, blockquote.{{ callout[0] }} {
+    background: rgba(${{ callout[1].color }}-{{ callout_background_hue }}, {{ callout_opacity }});
+    border-left: $border-radius solid ${{ callout[1].color }}-{{ callout_color_hue }};
+    border-radius: $border-radius;
+    box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
+    padding: .8rem;
+    {% if callout[1].title %}
+    &::before {
+        color: ${{ callout[1].color }}-{{ callout_color_hue }};
+        content: "{{ callout[1].title }}";
+        display: block;
+        font-weight: bold;
+        text-transform: uppercase;
+        font-size: .75em;
+        padding-bottom: .125rem;
+    }
+    {% endif %}
+    > .{{ callout[0] }}-title {
+      color: ${{ callout[1].color }}-{{ callout_color_hue }};
+      display: block;
+      font-weight: bold;
+      text-transform: uppercase;
+      font-size: .75em;
+      padding-bottom: .125rem;
+    }
+}
+
+p.{{ callout[0] }}-title, blockquote.{{ callout[0] }}-title {
+    background: rgba(${{ callout[1].color }}-{{ callout_background_hue }}, {{ callout_opacity }});
+    border-left: $border-radius solid ${{ callout[1].color }}-{{ callout_color_hue }};
+    border-radius: $border-radius;
+    box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
+    padding: .8rem;
+    > p:first-child {
+      margin-top: 0;
+      margin-bottom: 0;
+      color: ${{ callout[1].color }}-{{ callout_color_hue }};
+      display: block;
+      font-weight: bold;
+      text-transform: uppercase;
+      font-size: .75em;
+      padding-bottom: .125rem;
+    }
+}
+
+blockquote.{{ callout[0] }} {
+  margin-left: 0;
+  margin-right: 0;
+  
+  > p:first-child {
+    margin-top: 0;
+  }
+    
+  > p:last-child {
+    margin-bottom: 0;
+  }
+}
+
+blockquote.{{ callout[0] }}-title {
+  margin-left: 0;
+  margin-right: 0;
+  
+  > p:nth-child(2) {
+    margin-top: 0;
+  }
+    
+  > p:last-child {
+    margin-bottom: 0;
+  }
+}
+
+{% endfor -%}

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

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

_includes/head.html

@@ -2,37 +2,47 @@
   <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 %}
-
-  <link rel="shortcut icon" href="{{ 'favicon.ico' | relative_url }}" type="image/x-icon">
-
   <link rel="stylesheet" href="{{ '/assets/css/just-the-docs-default.css' | relative_url }}">
 
   {% 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 %}
-  <script type="text/javascript" src="{{ '/assets/js/just-the-docs.js' | relative_url }}"></script>
+
+  {% if site.mermaid %}
+    {% 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 %}
+  {% endif %}
+
+  <script src="{{ '/assets/js/just-the-docs.js' | relative_url }}"></script>
 
   <meta name="viewport" content="width=device-width, initial-scale=1">
 
+  {% 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 %}
+
   {% 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/external_link.html

@@ -0,0 +1,5 @@
+<!-- Feather. MIT License: https://github.com/feathericons/feather/blob/master/LICENSE -->
+<symbol id="svg-external-link" 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-external-link">
+  <title id="svg-external-link-title">(external link)</title>
+  <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"></path><polyline points="15 3 21 3 21 9"></polyline><line x1="10" y1="14" x2="21" y2="3"></line>
+</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/mermaid_config.js

@@ -0,0 +1 @@
+{}

_includes/nav.html

@@ -1,87 +1,201 @@
-<ul class="nav-list">
-  {%- assign titled_pages = include.pages
+{%- 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 title_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.
+  A page with `nav_exclude: true` does not appear in the main navigation.
+  If it has a `parent`, it may appear in the parent's table of contents.
+  If it specifies `has_children: true`, it should appear in the breadcrumbs
+  of the child pages, but its order in relation to other pages is irrelevant.
+  Pages that never appear can be removed from the pages that need to be sorted.
+  This optimisation can be significant on a site with many pages.
   
-    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).
+  In Jekyll 4, the pages to be sorted can be filtered by:
   
-    The case-sensitivity of string sorting is determined by `site.nav_sort`.
+  {%- assign title_pages = title_pages
+        | where_exp: "item", "item.nav_exclude != true or item.parent != nil" -%}
+  
+  That filter is not allowed in Jekyll 3. The following iterative code gives the
+  same effect, but it is activated only when it will filter more than 50% of the
+  pages.
 {%- endcomment -%}
 
-  {%- assign string_ordered_pages = titled_pages
-        | where_exp:"item", "item.nav_order == nil" -%}
-  {%- assign nav_ordered_pages = titled_pages
+{%- unless title_pages == empty -%}
+  {%- assign unsorted_pages = title_pages
+        | where_exp: "item", "item.parent == nil" 
+        | where_exp: "item", "item.nav_exclude == true" -%}
+  {%- assign title_pages_size = title_pages.size -%}
+  {%- assign unsorted_pages_percent = unsorted_pages.size
+        | times: 100 | divided_by: title_pages_size -%}
+  {%- if unsorted_pages_percent > 50 -%}
+    {%- assign sorted_pages = "" | split: "" -%}
+    {%- for item in title_pages -%}
+      {%- if item.nav_exclude != true or item.parent -%}
+        {%- assign sorted_pages = sorted_pages | push: item -%}
+      {%- endif -%}
+    {%- endfor -%}
+    {%- assign title_pages = sorted_pages -%}
+  {%- endif -%}
+{%- endunless -%}
+
+{%- assign nav_order_pages = title_pages
       | where_exp: "item", "item.nav_order != nil" -%}
+{%- assign title_order_pages = title_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.
+  Divide the arrays of `nav_order_pages` and `title_order_pages` according to
+  the type of value.
+  
+  The first character of the result of `jsonify` is `"` only for strings.
+  Grouping by a single character also ensures the number of groups is small.
 {%- endcomment -%}
-  {%- assign nav_ordered_groups = nav_ordered_pages
+
+{%- assign nav_number_pages = "" | split: "" -%}
+{%- assign nav_string_pages = "" | split: "" -%}
+{%- assign nav_order_groups = nav_order_pages
       | group_by_exp: "item", "item.nav_order | jsonify | slice: 0" -%}
-  {%- assign number_ordered_pages = "" | split:"X" -%}
-  {%- for group in nav_ordered_groups -%}
+{%- for group in nav_order_groups -%}
   {%- if group.name == '"' -%}
-      {%- assign string_ordered_pages = string_ordered_pages | concat: group.items -%}
+    {%- assign nav_string_pages = group.items -%}
   {%- else -%}
-      {%- assign number_ordered_pages = number_ordered_pages | concat: group.items -%}
+    {%- assign nav_number_pages = nav_number_pages | concat: group.items -%}
   {%- endif -%}
 {%- endfor -%}
 
-  {%- assign sorted_number_ordered_pages = number_ordered_pages | sort:"nav_order" -%}
+{%- 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 -%}
+
+{%- assign title_number_pages = "" | split: "" -%}
+{%- assign title_string_pages = "" | split: "" -%}
+{%- assign title_order_groups = title_order_pages
+      | group_by_exp: "item", "item.title | jsonify | slice: 0" -%}
+{%- for group in title_order_groups -%}
+  {%- if group.name == '"' -%}
+    {%- assign title_string_pages = group.items -%}
+  {%- else -%}
+    {%- assign title_number_pages = title_number_pages | concat: group.items -%}
+  {%- endif -%}
+{%- endfor -%}
+
+{%- 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 pages_list = nav_number_pages | concat: nav_string_pages
+      | concat: title_number_pages | concat: title_string_pages -%}
+
+{%- assign first_level_pages = pages_list
+      | where_exp: "item", "item.parent == nil" -%}
+{%- assign second_level_pages = pages_list
+      | where_exp: "item", "item.parent != nil"
+      | where_exp: "item", "item.grand_parent == nil" -%}
+{%- assign third_level_pages = pages_list
+      | where_exp: "item", "item.grand_parent != nil" -%}
 
 {%- 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.
+  The order of sibling pages in `pages_list` determines the order of display of
+  links to them in lists of navigation links and in auto-generated TOCs.
+  
+  Note that Liquid evaluates conditions from right to left (and it does not allow
+  the use of parentheses). Some conditions are not so easy to express clearly...
+  
+  For example, consider the following condition:
+  
+    C: page.collection = = include.key and 
+       page.url = = node.url or 
+       page.grand_parent = = node.title or 
+       page.parent = = node.title and 
+       page.grand_parent = = nil
+ 
+  Here, `node` is a first-level page. The last part of the condition
+  -- namely: `page.parent = = node.title and page.grand_parent = = nil` --
+  is evaluated first; it holds if and only if `page` is a child of `node`.
+  
+  The condition `page.grand_parent = = node.title or ...` holds when 
+  `page` is a grandchild of node, OR `...` holds.
+  
+  The condition `page.url = = node.url or ...` holds when 
+  `page` is `node`, OR `...` holds.
+  
+  The condition C: `page.collection = = include.key and ...` holds when we are 
+  generating the nav links for a collection that includes `page`, AND `...` holds.
 {%- 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 -%}
+<ul class="nav-list">
+{%- for node in first_level_pages -%}
     {%- unless node.nav_exclude -%}
-      <li class="nav-list-item{% if page.url == node.url or page.parent == node.title or page.grand_parent == node.title %} active{% endif %}">
+      <li class="nav-list-item{% if page.collection == include.key and page.url == node.url or page.grand_parent == node.title or page.parent == node.title and page.grand_parent == nil %} 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>
+          <a href="#" class="nav-list-expander" aria-label="toggle links in {{ node.title }} category">
+            <svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg>
+          </a>
         {%- endif -%}
-        <a href="{{ node.url | absolute_url }}" class="nav-list-link{% if page.url == node.url %} active{% endif %}">{{ node.title }}</a>
+        <a href="{{ node.url | relative_url }}" class="nav-list-link{% if page.url == node.url %} active{% endif %}">{{ node.title }}</a>
         {%- if node.has_children -%}
-          {%- assign children_list = pages_list | where: "parent", node.title -%}
+          {%- 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 -%}
             {%- 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>
+                <a href="#" class="nav-list-expander" aria-label="toggle links in {{ child.title }} category">
+                  <svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg>
+                </a>
               {%- endif -%}
-              <a href="{{ child.url | absolute_url }}" class="nav-list-link{% if page.url == child.url %} active{% endif %}">{{ child.title }}</a>
+              <a href="{{ child.url | relative_url }}" class="nav-list-link{% if page.url == child.url %} active{% endif %}">{{ child.title }}</a>
               {%- if child.has_children -%}
-                {%- assign grand_children_list = pages_list | where: "parent", child.title | where: "grand_parent", node.title -%}
+                {%- 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 -%}
                   {%- unless grand_child.nav_exclude -%}
                   <li class="nav-list-item {% if page.url == grand_child.url %} active{% endif %}">
-                    <a href="{{ grand_child.url | absolute_url }}" class="nav-list-link{% if page.url == grand_child.url %} active{% endif %}">{{ grand_child.title }}</a>
+                    <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 -%}
@@ -94,6 +208,44 @@
         {%- endif -%}
       </li>
     {%- endunless -%}
-    {%- endif -%}
 {%- endfor -%}
 </ul>
+
+{%- comment -%}
+  `page.collection` is the name of the Jekyll collection that contains the page,
+  if any, and otherwise nil. Similarly for `include.key`.
+  
+  If the current page is in the collection (if any) whose navigation is currently
+  being generated, the following code sets `first_level_url` to the URL used in
+  the page's top-level breadcrumb (if any), and `second_level_url` to that used
+  in the page's second-level breadcrumb (if any).
+  
+  For pages with children, the code also sets `toc_list` to the list of child pages,
+  reversing the order if needed.
+{%- endcomment -%}
+
+{%- if page.collection == include.key -%}
+  {%- for node in first_level_pages -%}
+      {%- 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 = second_level_pages | 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 -%}
+  {%- endfor -%}
+  {%- if page.has_children == true and page.has_toc != false -%}
+    {%- assign toc_list = pages_list
+          | where: "parent", page.title
+          | where_exp: "item", "item.grand_parent == page.parent" -%}
+    {%- if page.child_nav_order == 'desc' or page.child_nav_order == 'reversed' -%}
+      {%- assign toc_list = toc_list | reverse -%}
+    {%- endif -%}
+  {%- endif -%}
+{%- endif -%}

_includes/search_placeholder_custom.html

@@ -0,0 +1 @@
+Search {{site.title}}

_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,129 +7,13 @@ 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;">
-    <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>
-    <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>
-  </svg>
-
-  <div class="side-bar">
-    <div class="site-header">
-      <a href="{{ '/' | absolute_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">
-      {% 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 %}
-              <div class="nav-category">{{ collection_value.name }}</div>
-            {% endif %}
-            {% include nav.html pages=collection %}
-          {% endif %}
-        {% endfor %}
-      {% else %}
-        {% include nav.html pages=site.html_pages %}
-      {% endif %}
-    </nav>
-    <footer class="site-footer">
-      This site uses <a href="https://github.com/pmarsceill/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll.
-    </footer>
-  </div>
+  <a class="skip-to-main" href="#main-content">Skip to main content</a>
+  {% include icons/icons.html %}
+  {% include components/sidebar.html %}
   <div class="main" id="top">
-    <div id="main-header" class="main-header">
-      {% if site.search_enabled != false %}
-        <div class="search">
-          <div class="search-input-wrap">
-            <input type="text" id="search-input" class="search-input" tabindex="0" placeholder="Search {{ site.title }}" aria-label="Search {{ site.title }}" 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>
+    {% include components/header.html %}
     <div id="main-content-wrap" class="main-content-wrap">
-      {% unless page.url == "/" %}
-        {% if page.parent %}
-          {%- for node in pages_list -%}
-            {%- if node.parent == nil -%}
-              {%- if page.parent == node.title or page.grand_parent == node.title -%}
-                {%- assign first_level_url = node.url | absolute_url -%}
-              {%- endif -%}
-              {%- if node.has_children -%}
-                {%- assign children_list = pages_list | where: "parent", node.title -%}
-                {%- for child in children_list -%}
-                  {%- if page.url == child.url or page.parent == child.title -%}
-                    {%- assign second_level_url = child.url | absolute_url -%}
-                  {%- endif -%}
-                {%- endfor -%}
-              {%- endif -%}
-            {%- endif -%}
-          {%- endfor -%}
-          <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 %}
+      {% 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%\"" %}
@@ -138,65 +22,20 @@ layout: table_wrappers
         {% endif %}
 
         {% if page.has_children == true and page.has_toc != false %}
-          <hr>
-          <h2 class="text-delta">Table of contents</h2>
-          <ul>
-            {%- assign children_list = pages_list | where: "parent", page.title | where: "grand_parent", page.parent -%}
-            {% for child in children_list %}
-              <li>
-                <a href="{{ child.url | absolute_url }}">{{ child.title }}</a>{% if child.summary %} - {{ child.summary }}{% endif %}
-              </li>
-            {% endfor %}
-          </ul>
+          {% include components/children_nav.html toc_list=toc_list %}
         {% endif %}
 
-        {% 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 %}/{{ page.path }}" id="edit-this-page">{{ site.gh_edit_link_text }}</a>
-                  </p>
-                {% endif %}
-              </div>
-            {% endif %}
-          </footer>
-        {% endif %}
+        {% include components/footer.html %}
 
       </div>
     </div>
-
     {% if site.search_enabled != false %}
-      {% if site.search.button %}
-        <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>
+      {% include components/search_footer.html %}
     {% endif %}
   </div>
+
+  {% if site.mermaid %}
+    {% include components/mermaid.html %}
+  {% endif %}
 </body>
 </html>

_layouts/minimal.html

@@ -0,0 +1,60 @@
+---
+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 %}
+  {% comment %}
+    This is a bandaid fix to properly render breadcrumbs; as of now, there is some variable leakage between the sidebar component (which computes parents, grandparents) and the breadcrumbs component. We plan to remove this in a future release to deduplicate code.
+
+    For more context, see https://github.com/just-the-docs/just-the-docs/pull/1058#discussion_r1057014053
+  {% endcomment %}
+  {% capture 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 %}
+          {% include nav.html pages=collection key=collection_key %}
+        {% endif %}
+      {% endfor %}
+    {% endif %}
+  {% endcapture %}
+  <div id="main-content-wrap" 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 toc_list=toc_list %}
+      {% endif %}
+
+      {% include components/footer.html %}
+
+    </div>
+  </div>
+
+  {% if site.mermaid %}
+    {% include components/mermaid.html %}
+  {% endif %}
+</body>
+</html>

_sass/base.scss

@@ -1,7 +1,5 @@
-//
 // Base element style overrides
-//
-// stylelint-disable selector-no-type, selector-max-type
+// stylelint-disable selector-no-type, selector-max-type, selector-max-specificity, selector-max-id
 
 * {
   box-sizing: border-box;
@@ -14,6 +12,7 @@
 
 html {
   @include fs-4;
+
   scroll-behavior: smooth;
 }
 
@@ -23,6 +22,7 @@ body {
   line-height: $body-line-height;
   color: $body-text-color;
   background-color: $body-background-color;
+  overflow-wrap: break-word;
 }
 
 ol,
@@ -45,7 +45,8 @@ h2,
 h3,
 h4,
 h5,
-h6 {
+h6,
+#toctitle {
   margin-top: 0;
   margin-bottom: 1em;
   font-weight: 500;
@@ -64,18 +65,12 @@ a {
 }
 
 a:not([class]) {
-  text-decoration: none;
-  background-image: linear-gradient($border-color 0%, $border-color 100%);
-  background-repeat: repeat-x;
-  background-position: 0 100%;
-  background-size: 1px 1px;
+  text-decoration: underline;
+  text-decoration-color: $border-color;
+  text-underline-offset: 2px;
 
   &:hover {
-    background-image: linear-gradient(
-      rgba($link-color, 0.45) 0%,
-      rgba($link-color, 0.45) 100%
-    );
-    background-size: 1px 1px;
+    text-decoration-color: rgba($link-color, 0.45);
   }
 }
 
@@ -106,3 +101,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: 15px;
+  border-left: 3px solid $border-color;
+}

_sass/buttons.scss

@@ -1,15 +1,10 @@
-//
 // Buttons and things that look like buttons
-//
 // stylelint-disable color-named
 
 .btn {
   display: inline-block;
   box-sizing: border-box;
-  padding-top: 0.3em;
-  padding-right: 1em;
-  padding-bottom: 0.3em;
-  padding-left: 1em;
+  padding: 0.3em 1em;
   margin: 0;
   font-family: inherit;
   font-size: inherit;

_sass/code.scss

@@ -1,15 +1,18 @@
-//
 // Code and syntax highlighting
-//
-// stylelint-disable selector-no-qualifying-type, declaration-block-semicolon-newline-after,declaration-block-single-line-max-declarations, selector-no-type, selector-max-type
+// stylelint-disable selector-no-qualifying-type, declaration-block-semicolon-newline-after,declaration-block-single-line-max-declarations, selector-no-type, selector-max-type, scss/comment-no-empty
 
-code {
+// {% raw %}
+
+// 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 {
@@ -36,6 +39,9 @@ a:visited code {
 //   > td.gutter.gl > pre.lineno
 //   | td.code > pre
 //
+// ----...---- (AsciiDoc)
+//   div.listingblock > div.content > pre.rouge.highlight
+//
 // fix_linenos removes the outermost pre when it encloses table.rouge-table
 //
 // See docs/index-test.md for some tests.
@@ -44,17 +50,77 @@ a:visited code {
 // Kramdown line_numbers = true: fences have a wider gutter than with Liquid?
 
 // ```[LANG]...```
-div.highlighter-rouge {
-  padding: $sp-3;
+
+// 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
+
+// select top level container
+div.highlighter-rouge,
+div.listingblock > div.content,
+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;
+
+  // copy button (or other button)
+  // 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 thirt level
+div.highlighter-rouge,
+div.listingblock {
+  div.highlight {
+    overflow-x: auto;
+    padding: $sp-3;
+    margin: 0;
+    border: 0;
+  }
 
-  div.highlight,
   pre.highlight,
   code {
     padding: 0;
@@ -65,18 +131,15 @@ div.highlighter-rouge {
 
 // {% highlight LANG %}...{% endhighlight %},
 // {% highlight LANG linenos %}...{% endhighlight %}:
-figure.highlight {
-  padding: $sp-3;
-  margin-top: 0;
-  margin-bottom: $sp-3;
-  background-color: $code-background-color;
-  border-radius: $border-radius;
-  box-shadow: none;
-  -webkit-overflow-scrolling: touch;
 
+// 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 {
-    padding: 0;
+  :not(pre) > code {
+    overflow-x: auto;
+    padding: $sp-3;
     margin: 0;
     border: 0;
   }
@@ -84,8 +147,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;
@@ -93,6 +158,7 @@ figure.highlight {
   td,
   pre {
     @include fs-2;
+
     min-width: 0;
     padding: 0;
     background-color: $code-background-color;
@@ -100,7 +166,9 @@ figure.highlight {
   }
 
   td.gl {
+    width: 1em;
     padding-right: $sp-3;
+    padding-left: $sp-3;
   }
 
   pre {
@@ -109,218 +177,9 @@ figure.highlight {
   }
 }
 
-.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 //
-
-//
-// Code examples (rendered)
-//
-
-.code-example {
+// Code examples: html render of a code
+.code-example,
+.listingblock > .title {
   padding: $sp-3;
   margin-bottom: $sp-3;
   overflow: auto;
@@ -328,6 +187,8 @@ figure.highlight {
   border-radius: $border-radius;
 
   + .highlighter-rouge,
+  + .sectionbody .listingblock,
+  + .content,
   + figure.highlight {
     position: relative;
     margin-top: -$sp-4;
@@ -338,3 +199,29 @@ figure.highlight {
     border-top-right-radius: 0;
   }
 }
+
+// Mermaid diagram code blocks should be left unstyled.
+code.language-mermaid {
+  padding: 0;
+  background-color: inherit;
+  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,17 +1,32 @@
 $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;
 $search-result-preview-color: $grey-dk-000;
-
 $link-color: $blue-000;
 $btn-primary-color: $blue-200;
 $base-button-color: $grey-dk-250;
-
-$code-background-color: $grey-dk-250;
 $search-background-color: $grey-dk-250;
 $table-background-color: $grey-dk-250;
 $feedback-color: darken($sidebar-color, 3%);
+
+// The following highlight theme is more legible than that used for the light color scheme
+
+// @import "./vendor/OneDarkJekyll/syntax-one-dark";
+// $code-background-color: #282c34; // OneDarkJekyll default for syntax-one-dark
+// $code-linenumber-color: #abb2bf; // OneDarkJekyll .nf for syntax-one-dark
+
+@import "./vendor/OneDarkJekyll/syntax-one-dark-vivid";
+
+$code-background-color: #31343f; // OneDarkJekyll default for syntax-one-dark-vivid
+$code-linenumber-color: #dee2f7; // OneDarkJekyll .nf for syntax-one-dark-vivid
+
+// @import "./vendor/OneDarkJekyll/syntax-firewatch";
+// $code-background-color: #282c34; // OneDarkJekyll default for syntax-firewatch
+// $code-linenumber-color: #abb2bf; // OneDarkJekyll .nf for syntax-firewatch
+
+// @import "./vendor/OneDarkJekyll/syntax-firewatch-green";
+// $code-background-color: #282c34; // OneDarkJekyll default for syntax-firewatch-green
+// $code-linenumber-color: #abb2bf; // OneDarkJekyll .nf for syntax-firewatch-green

_sass/color_schemes/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/content.scss

@@ -1,9 +1,7 @@
 @charset "UTF-8";
 
-//
 // Styles for rendered markdown in the .main-content container
-//
-// stylelint-disable selector-no-type, max-nesting-depth, selector-max-compound-selectors, selector-max-type
+// stylelint-disable selector-no-type, max-nesting-depth, selector-max-compound-selectors, selector-max-type, selector-max-specificity, selector-max-id
 
 .main-content {
   line-height: $content-line-height;
@@ -21,7 +19,6 @@
   a {
     overflow: hidden;
     text-overflow: ellipsis;
-    white-space: nowrap;
   }
 
   ul,
@@ -59,7 +56,7 @@
       ol {
         counter-reset: sub-counter;
 
-        li {
+        > li {
           &::before {
             content: counter(sub-counter, lower-alpha);
             counter-increment: sub-counter;
@@ -82,14 +79,7 @@
     }
   }
 
-  .task-list {
-    padding-left: 0;
-  }
-
   .task-list-item {
-    display: flex;
-    align-items: center;
-
     &::before {
       content: "";
     }
@@ -97,6 +87,9 @@
 
   .task-list-item-checkbox {
     margin-right: 0.6em;
+    margin-left: -1.4em;
+
+    // The same margin-left is used above for ul > li::before
   }
 
   hr + * {
@@ -121,6 +114,7 @@
     grid-column: 1;
     font-weight: 500;
     text-align: right;
+
     &::after {
       content: ":";
     }
@@ -130,6 +124,7 @@
     grid-column: 2;
     margin-bottom: 0;
     margin-left: 1em;
+
     blockquote,
     div,
     dl,
@@ -188,6 +183,7 @@
   }
 
   .anchor-heading:hover,
+  .anchor-heading:focus,
   h1:hover > .anchor-heading,
   h2:hover > .anchor-heading,
   h3:hover > .anchor-heading,
@@ -208,24 +204,36 @@
   h3,
   h4,
   h5,
-  h6 {
+  h6,
+  #toctitle {
     position: relative;
     margin-top: 1.5em;
     margin-bottom: 0.25em;
 
-    &:first-child {
-      margin-top: $sp-2;
-    }
-
     + table,
     + .table-wrapper,
     + .code-example,
-    + .highlighter-rouge {
+    + .highlighter-rouge,
+    + .sectionbody .listingblock {
       margin-top: 1em;
     }
 
-    + p {
+    + p:not(.label) {
       margin-top: 0;
     }
   }
+
+  > h1:first-child,
+  > h2:first-child,
+  > h3:first-child,
+  > h4:first-child,
+  > h5:first-child,
+  > h6:first-child,
+  > .sect1:first-child > h2,
+  > .sect2:first-child > h3,
+  > .sect3:first-child > h4,
+  > .sect4:first-child > h5,
+  > .sect5:first-child > h6 {
+    margin-top: $sp-2;
+  }
 }

_sass/custom/custom.scss

@@ -0,0 +1 @@
+// custom SCSS (or CSS) goes here

_sass/custom/setup.scss

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

_sass/labels.scss

@@ -1,14 +1,9 @@
-//
 // Labels (not the form kind)
-//
 
 .label,
 .label-blue {
   display: inline-block;
-  padding-top: 0.16em;
-  padding-right: 0.56em;
-  padding-bottom: 0.16em;
-  padding-left: 0.56em;
+  padding: 0.16em 0.56em;
   margin-right: $sp-2;
   margin-left: $sp-2;
   color: $white;
@@ -16,6 +11,7 @@
   vertical-align: middle;
   background-color: $blue-100;
   @include fs-2;
+
   border-radius: 12px;
 }
 

_sass/layout.scss

@@ -1,6 +1,4 @@
-//
 // The basic two column layout
-//
 
 .side-bar {
   z-index: 0;
@@ -9,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;
   }
@@ -40,6 +37,7 @@
 
 .main-content-wrap {
   @include container;
+
   padding-top: $gutter-spacing-sm;
   padding-bottom: $gutter-spacing-sm;
 
@@ -111,6 +109,7 @@
 
 .site-title {
   @include container;
+
   flex-grow: 1;
   display: flex;
   height: 100%;
@@ -184,6 +183,7 @@ body {
 
 .site-footer {
   @include container;
+
   position: absolute;
   bottom: 0;
   left: 0;

_sass/modules.scss

@@ -1,11 +1,7 @@
-//
 // Import external dependencies
-//
-@import "./vendor/normalize.scss/normalize.scss";
+@import "./vendor/normalize.scss/normalize";
 
-//
 // Modules
-//
 @import "./base";
 @import "./layout";
 @import "./content";
@@ -18,3 +14,4 @@
 @import "./code";
 @import "./utilities/utilities";
 @import "./print";
+@import "./skiptomain";

_sass/navigation.scss

@@ -1,6 +1,4 @@
-//
 // Main nav, breadcrumb, etc...
-//
 // stylelint-disable selector-no-type, max-nesting-depth, selector-max-compound-selectors, selector-max-type, selector-max-specificity
 
 .nav-list {
@@ -11,6 +9,7 @@
 
   .nav-list-item {
     @include fs-4;
+
     position: relative;
     margin: 0;
 
@@ -44,6 +43,12 @@
         }
       }
 
+      &.external > svg {
+        width: $sp-4;
+        height: $sp-4;
+        vertical-align: text-bottom;
+      }
+
       &.active {
         font-weight: 600;
         text-decoration: none;
@@ -65,21 +70,16 @@
       @if $nav-list-expander-right {
         right: 0;
       }
+
       width: $nav-list-item-height-sm;
       height: $nav-list-item-height-sm;
-      padding-top: #{$nav-list-item-height-sm / 4};
-      padding-right: #{$nav-list-item-height-sm / 4};
-      padding-bottom: #{$nav-list-item-height-sm / 4};
-      padding-left: #{$nav-list-item-height-sm / 4};
+      padding: #{$nav-list-item-height-sm * 0.25};
       color: $link-color;
 
       @include mq(md) {
         width: $nav-list-item-height;
         height: $nav-list-item-height;
-        padding-top: #{$nav-list-item-height / 4};
-        padding-right: #{$nav-list-item-height / 4};
-        padding-bottom: #{$nav-list-item-height / 4};
-        padding-left: #{$nav-list-item-height / 4};
+        padding: #{$nav-list-item-height * 0.25};
       }
 
       &:hover {
@@ -132,19 +132,15 @@
 }
 
 .nav-category {
-  padding-top: $sp-2;
-  padding-right: $gutter-spacing-sm;
-  padding-bottom: $sp-2;
-  padding-left: $gutter-spacing-sm;
+  padding: $sp-2 $gutter-spacing-sm;
   font-weight: 600;
-  text-align: end;
+  text-align: start;
   text-transform: uppercase;
   border-bottom: $border $border-color;
   @include fs-2;
 
   @include mq(md) {
-    padding-right: $gutter-spacing;
-    padding-left: $gutter-spacing;
+    padding: $sp-2 $gutter-spacing;
     margin-top: $gutter-spacing-sm;
     text-align: start;
 
@@ -154,6 +150,26 @@
   }
 }
 
+.nav-list.nav-category-list {
+  > .nav-list-item {
+    margin: 0;
+
+    > .nav-list {
+      padding: 0;
+
+      > .nav-list-item {
+        > .nav-list-link {
+          color: $link-color;
+        }
+
+        > .nav-list-expander {
+          color: $link-color;
+        }
+      }
+    }
+  }
+}
+
 // Aux nav
 
 .aux-nav {

_sass/print.scss

@@ -1,4 +1,4 @@
-// stylelint-disable selector-max-specificity, selector-max-id, selector-max-type, selector-no-qualifying-type, primer/no-override,
+// stylelint-disable selector-max-specificity, selector-max-id, selector-max-type, selector-no-qualifying-type
 
 @media print {
   .site-footer,

_sass/search.scss

@@ -1,6 +1,4 @@
-//
 // Search input and autocomplete
-//
 
 .search {
   position: relative;
@@ -8,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;
@@ -26,7 +24,7 @@
   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);
-  transition: height linear #{$transition-duration / 2};
+  transition: height linear #{$transition-duration * 0.5};
 
   @include mq(md) {
     position: absolute;
@@ -43,11 +41,9 @@
   position: absolute;
   width: 100%;
   height: 100%;
-  padding-top: $sp-2;
-  padding-right: $gutter-spacing-sm;
-  padding-bottom: $sp-2;
-  padding-left: #{$gutter-spacing-sm + $sp-5};
+  padding: $sp-2 $gutter-spacing-sm $sp-2 #{$gutter-spacing-sm + $sp-5};
   font-size: 16px;
+  color: $body-text-color;
   background-color: $search-background-color;
   border-top: 0;
   border-right: 0;
@@ -56,12 +52,10 @@
   border-radius: 0;
 
   @include mq(md) {
-    padding-top: $gutter-spacing-sm;
-    padding-bottom: $gutter-spacing-sm;
-    padding-left: #{$gutter-spacing + $sp-5};
+    padding: $sp-2 $gutter-spacing-sm $sp-2 #{$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 {
@@ -81,7 +75,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 {
@@ -129,10 +123,7 @@
 
 .search-result {
   display: block;
-  padding-top: $sp-1;
-  padding-right: $sp-3;
-  padding-bottom: $sp-1;
-  padding-left: $sp-3;
+  padding: $sp-1 $sp-3;
 
   &:hover,
   &.active {
@@ -225,10 +216,7 @@
 }
 
 .search-no-result {
-  padding-top: $sp-2;
-  padding-right: $sp-3;
-  padding-bottom: $sp-2;
-  padding-left: $sp-3;
+  padding: $sp-2 $sp-3;
   @include fs-3;
 }
 
@@ -241,7 +229,7 @@
   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);
   align-items: center;
   justify-content: center;

_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 +1,9 @@
 @function rem($size, $unit: "") {
-  $remSize: $size / $root-font-size;
+  $rem-size: $size / $root-font-size;
 
-  @if ($unit == false) {
-    @return #{$remSize};
+  @if $unit == false {
+    @return #{$rem-size};
   } @else {
-    @return #{$remSize}rem;
+    @return #{$rem-size}rem;
   }
 }

_sass/support/_variables.scss

@@ -1,19 +1,15 @@
-//
 // Typography
-//
 
-$body-font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI",
-  Roboto, "Helvetica Neue", Arial, sans-serif !default;
-$mono-font-family: "SFMono-Regular", Menlo, Consolas, Monospace !default;
+$body-font-family: system-ui, -apple-system, blinkmacsystemfont, "Segoe UI",
+  roboto, "Helvetica Neue", arial, sans-serif !default;
+$mono-font-family: "SFMono-Regular", menlo, consolas, monospace !default;
 $root-font-size: 16px !default; // Base font-size for rems
 $body-line-height: 1.4 !default;
 $content-line-height: 1.6 !default;
 $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-sm: 10px !default;
@@ -28,55 +24,44 @@ $font-size-9: 36px !default;
 $font-size-10: 42px !default;
 $font-size-10-sm: 48px !default;
 
-//
 // Colors
-//
 
 $white: #fff !default;
-
 $grey-dk-000: #959396 !default;
 $grey-dk-100: #5c5962 !default;
 $grey-dk-200: #44434d !default;
 $grey-dk-250: #302d36 !default;
 $grey-dk-300: #27262b !default;
-
 $grey-lt-000: #f5f6fa !default;
 $grey-lt-100: #eeebee !default;
 $grey-lt-200: #ecebed !default;
 $grey-lt-300: #e6e1e8 !default;
-
 $purple-000: #7253ed !default;
 $purple-100: #5e41d0 !default;
 $purple-200: #4e26af !default;
 $purple-300: #381885 !default;
-
 $blue-000: #2c84fa !default;
 $blue-100: #2869e6 !default;
 $blue-200: #264caf !default;
 $blue-300: #183385 !default;
-
 $green-000: #41d693 !default;
 $green-100: #11b584 !default;
 $green-200: #009c7b !default;
 $green-300: #026e57 !default;
-
 $yellow-000: #ffeb82 !default;
 $yellow-100: #fadf50 !default;
 $yellow-200: #f7d12e !default;
 $yellow-300: #e7af06 !default;
-
 $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;
@@ -85,9 +70,7 @@ $link-color: $purple-000 !default;
 $btn-primary-color: $purple-100 !default;
 $base-button-color: #f7f7f7 !default;
 
-//
 // Spacing
-//
 
 $spacing-unit: 1rem; // 1rem == 16px
 
@@ -104,7 +87,6 @@ $spacers: (
   sp-9: $spacing-unit * 3.5,
   sp-10: $spacing-unit * 4,
 ) !default;
-
 $sp-1: map-get($spacers, sp-1) !default; // 0.25 rem == 4px
 $sp-2: map-get($spacers, sp-2) !default; // 0.5  rem == 8px
 $sp-3: map-get($spacers, sp-3) !default; // 0.75 rem == 12px
@@ -116,17 +98,13 @@ $sp-8: map-get($spacers, sp-8) !default; // 3    rem == 48px
 $sp-9: map-get($spacers, sp-9) !default; // 3.5  rem == 56px
 $sp-10: map-get($spacers, sp-10) !default; // 4  rem == 64px
 
-//
 // Borders
-//
 
 $border: 1px solid !default;
 $border-radius: 4px !default;
 $border-color: $grey-lt-100 !default;
 
-//
 // Grid system
-//
 
 $gutter-spacing: $sp-6 !default;
 $gutter-spacing-sm: $sp-4 !default;
@@ -140,9 +118,7 @@ $header-height: 60px !default;
 $search-results-width: $content-width - $nav-width !default;
 $transition-duration: 400ms;
 
-//
 // Media queries in pixels
-//
 
 $media-queries: (
   xs: 320px,

_sass/support/mixins/_layout.scss

@@ -10,7 +10,7 @@
   $value: map-get($media-queries, $name);
 
   // If the key exists in the map
-  @if $value != null {
+  @if $value {
     // Prints a media query based on the value
     @media (min-width: rem($value)) {
       @content;

_sass/tables.scss

@@ -1,6 +1,4 @@
-//
 // Tables
-//
 // stylelint-disable max-nesting-depth, selector-no-type, selector-max-type
 
 .table-wrapper {
@@ -22,11 +20,9 @@ table {
 th,
 td {
   @include fs-3;
+
   min-width: 120px;
-  padding-top: $sp-2;
-  padding-right: $sp-3;
-  padding-bottom: $sp-2;
-  padding-left: $sp-3;
+  padding: $sp-2 $sp-3;
   background-color: $table-background-color;
   border-bottom: $border rgba($border-color, 0.5);
   border-left: $border $border-color;

_sass/typography.scss

@@ -1,16 +1,16 @@
-//
 // Typography
-//
-// stylelint-disable primer/selector-no-utility, primer/no-override, selector-no-type, selector-max-type
+// stylelint-disable selector-no-type, selector-max-type, selector-max-specificity, selector-max-id
 
 h1,
 .text-alpha {
   @include fs-8;
+
   font-weight: 300;
 }
 
 h2,
-.text-beta {
+.text-beta,
+#toctitle {
   @include fs-6;
 }
 
@@ -22,6 +22,7 @@ h3,
 h4,
 .text-delta {
   @include fs-2;
+
   font-weight: 400;
   text-transform: uppercase;
   letter-spacing: 0.1em;
@@ -34,13 +35,11 @@ h4 code {
 h5,
 .text-epsilon {
   @include fs-3;
-  color: $grey-dk-200;
 }
 
 h6,
 .text-zeta {
   @include fs-2;
-  color: $grey-dk-200;
 }
 
 .text-small {

_sass/utilities/_colors.scss

@@ -1,6 +1,4 @@
-//
 // Utility classes for colors
-//
 
 // Text colors
 

_sass/utilities/_layout.scss

@@ -1,22 +1,23 @@
-// stylelint-disable primer/selector-no-utility, primer/no-override
-//
 // Utility classes for layout
-//
 
 // Display
 
 .d-block {
   display: block !important;
 }
+
 .d-flex {
   display: flex !important;
 }
+
 .d-inline {
   display: inline !important;
 }
+
 .d-inline-block {
   display: inline-block !important;
 }
+
 .d-none {
   display: none !important;
 }
@@ -78,18 +79,23 @@
 .v-align-baseline {
   vertical-align: baseline !important;
 }
+
 .v-align-bottom {
   vertical-align: bottom !important;
 }
+
 .v-align-middle {
   vertical-align: middle !important;
 }
+
 .v-align-text-bottom {
   vertical-align: text-bottom !important;
 }
+
 .v-align-text-top {
   vertical-align: text-top !important;
 }
+
 .v-align-top {
   vertical-align: top !important;
 }

_sass/utilities/_lists.scss

@@ -1,8 +1,6 @@
-//
 // Utility classes for lists
-//
 
-// stylelint-disable primer/selector-no-utility, primer/no-override, selector-max-type
+// stylelint-disable selector-max-type
 
 .list-style-none {
   padding: 0 !important;

_sass/utilities/_spacing.scss

@@ -1,9 +1,6 @@
-//
 // Utility classes for margins and padding
-//
 
-// scss-lint:disable SpaceAfterPropertyName
-// stylelint-disable block-opening-brace-space-after, block-opening-brace-space-before, primer/selector-no-utility, primer/no-override
+// stylelint-disable block-opening-brace-space-after, block-opening-brace-space-before
 
 // Margin spacer utilities
 

_sass/utilities/_typography.scss

@@ -1,8 +1,4 @@
-//
 // Utility classes for typography
-//
-
-// stylelint-disable primer/selector-no-utility, primer/no-override
 
 .fs-1 {
   @include fs-1;
@@ -87,5 +83,3 @@
 .text-uppercase {
   text-transform: uppercase !important;
 }
-
-// stylelint-enable primer/selector-no-utility

_sass/vendor/OneDarkJekyll/LICENSE

@@ -0,0 +1,21 @@
+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.

_sass/vendor/OneDarkJekyll/README.md

@@ -0,0 +1,25 @@
+# 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

@@ -0,0 +1,30 @@
+// 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-green.scss

@@ -0,0 +1,200 @@
+.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: #5ba473;
+}
+.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: #5ba473;
+}
+.highlight .kd {
+  color: #5ba473;
+}
+.highlight .kn {
+  color: #5ba473;
+}
+.highlight .kp {
+  color: #5ba473;
+}
+.highlight .kr {
+  color: #5ba473;
+}
+.highlight .kt {
+  color: #5ba473;
+}
+.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: #77b181;
+}
+.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: #77b181;
+}
+.highlight .il {
+  color: #d19a66;
+}
+.highlight .gu {
+  color: #75715e;
+}
+.highlight .gd {
+  color: #f92672;
+}
+.highlight .gi {
+  color: #a6e22e;
+}

_sass/vendor/OneDarkJekyll/syntax-firewatch.scss

@@ -0,0 +1,200 @@
+.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-vivid.scss

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

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

@@ -0,0 +1,200 @@
+.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

@@ -0,0 +1,56 @@
+@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

@@ -0,0 +1,93 @@
+/*
+  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/normalize.scss/normalize.scss

@@ -174,7 +174,8 @@ textarea {
  */
 
 button,
-input { /* 1 */
+input {
+  /* 1 */
   overflow: visible;
 }
 
@@ -184,7 +185,8 @@ input { /* 1 */
  */
 
 button,
-select { /* 1 */
+select {
+  /* 1 */
   text-transform: none;
 }
 

assets/js/just-the-docs.js

@@ -69,7 +69,7 @@ function initNav() {
 
 function initSearch() {
   var request = new XMLHttpRequest();
-  request.open('GET', '{{ "assets/js/search-data.json" | absolute_url }}', true);
+  request.open('GET', '{{ "assets/js/search-data.json" | relative_url }}', true);
 
   request.onload = function(){
     if (request.status >= 200 && request.status < 400) {
@@ -87,6 +87,7 @@ function initSearch() {
         this.metadataWhitelist = ['position']
 
         for (var i in docs) {
+          {% include lunr/custom-index.js %}
           this.add({
             id: i,
             title: docs[i].title,
@@ -217,6 +218,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>';
@@ -454,7 +456,19 @@ jtd.getTheme = function() {
 
 jtd.setTheme = function(theme) {
   var cssFile = document.querySelector('[rel="stylesheet"]');
-  cssFile.setAttribute('href', '{{ "assets/css/just-the-docs-" | absolute_url }}' + theme + '.css');
+  cssFile.setAttribute('href', '{{ "assets/css/just-the-docs-" | relative_url }}' + theme + '.css');
+}
+
+// Scroll site-nav to ensure the link to the current page is visible
+
+function scrollNav() {
+  const href = document.location.pathname;
+  const siteNav = document.getElementById('site-nav');
+  const targetLink = siteNav.querySelector('a[href="' + href + '"], a[href="' + href + '/"]');
+  if(targetLink){
+    const rect = targetLink.getBoundingClientRect();
+    siteNav.scrollBy(0, rect.top - 3*rect.height);
+  }
 }
 
 // Document ready
@@ -464,8 +478,51 @@ jtd.onReady(function(){
   {%- if site.search_enabled != false %}
   initSearch();
   {%- endif %}
+  scrollNav();
 });
 
+// Copy button on code
+
+
+{%- if site.enable_copy_code_button != false %}
+
+jtd.onReady(function(){
+
+  var codeBlocks = document.querySelectorAll('div.highlighter-rouge, div.listingblock, 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

@@ -3,7 +3,7 @@ permalink: /assets/js/search-data.json
 ---
 {
 {%- assign i = 0 -%}
-{%- assign pages_array = '' | split: '' -%}
+{%- assign pages_array = "" | split: "" -%}
 {%- assign pages_array = pages_array | push: site.html_pages -%}
 {%- if site.just_the_docs.collections -%}
   {%- for collection_entry in site.just_the_docs.collections -%}
@@ -50,7 +50,8 @@ permalink: /assets/js/search-data.json
     "doc": {{ page.title | jsonify }},
     "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 | absolute_url }}",
+    "url": "{{ url | relative_url }}",
+    {% include lunr/custom-data.json page=page %}
     "relUrl": "{{ url }}"
   }
         {%- assign i = i | plus: 1 -%}
@@ -61,7 +62,8 @@ permalink: /assets/js/search-data.json
     "doc": {{ page.title | jsonify }},
     "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 | absolute_url }}",
+    "url": "{{ page.url | relative_url }}",
+    {% include lunr/custom-data.json page=page %}
     "relUrl": "{{ page.url }}"
   }
         {%- assign i = i | plus: 1 -%}

docs/configuration.md

@@ -7,8 +7,7 @@ nav_order: 2
 # Configuration
 {: .no_toc }
 
-
-Just the Docs has some specific configuration parameters that can be defined in your Jekyll site's _config.yml file.
+Just the Docs has some specific configuration parameters that can be defined in your Jekyll site's \_config.yml file.
 {: .fs-6 .fw-300 }
 
 ## Table of contents
@@ -19,9 +18,7 @@ Just the Docs has some specific configuration parameters that can be defined in
 
 ---
 
-
-View this site's [_config.yml](https://github.com/pmarsceill/just-the-docs/tree/master/_config.yml) file as an example.
-
+View this site's [\_config.yml](https://github.com/just-the-docs/just-the-docs/tree/main/_config.yml) file as an example.
 
 ## Site logo
 
@@ -30,6 +27,15 @@ View this site's [_config.yml](https://github.com/pmarsceill/just-the-docs/tree/
 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
@@ -62,13 +68,32 @@ search:
   button: false
 ```
 
+## 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`:
+
+```yaml
+mermaid:
+  # Version of mermaid library
+  # Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/
+  version: "9.1.3"
+```
+
+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
 
 ```yaml
 # Aux links for the upper right navigation
 aux_links:
   "Just the Docs on GitHub":
-    - "//github.com/pmarsceill/just-the-docs"
+    - "//github.com/just-the-docs/just-the-docs"
 
 # Makes Aux links open in a new tab. Default is false
 aux_links_new_tab: false
@@ -84,6 +109,15 @@ aux_links_new_tab: false
 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]({% link docs/navigation-structure.md %}#external-navigation-links) for more details.
+
 ## Footer content
 
 ```yaml
@@ -91,7 +125,7 @@ heading_anchors: true
 # appears at the bottom of every page's main content
 # Note: The footer_content option is deprecated and will be removed in a future major release. Please use `_includes/footer_custom.html` for more robust
 markup / liquid-based content.
-footer_content: "Copyright &copy; 2017-2020 Patrick Marsceill. Distributed by an <a href=\"https://github.com/pmarsceill/just-the-docs/tree/master/LICENSE.txt\">MIT license.</a>"
+footer_content: "Copyright &copy; 2017-2020 Patrick Marsceill. Distributed by an <a href=\"https://github.com/just-the-docs/just-the-docs/tree/main/LICENSE.txt\">MIT license.</a>"
 
 # Footer last edited timestamp
 last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter
@@ -100,8 +134,8 @@ last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https:/
 # Footer "Edit this page on GitHub" link text
 gh_edit_link: true # show or hide edit this page link
 gh_edit_link_text: "Edit this page on GitHub."
-gh_edit_repository: "https://github.com/pmarsceill/just-the-docs" # the github URL for your repo
-gh_edit_branch: "master" # the branch that your docs is served from
+gh_edit_repository: "https://github.com/just-the-docs/just-the-docs" # the github URL for your repo
+gh_edit_branch: "main" # the branch that your docs is served from
 # gh_edit_source: docs # the source that your files originate from
 gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately
 ```
@@ -111,7 +145,7 @@ _note: `footer_content` is deprecated, but still supported. For a better experie
 - the "page last modified" data will only display if a page has a key called `last_modified_date`, formatted in some readable date format
 - `last_edit_time_format` uses Ruby's DateTime formatter; see examples and more information [at this link.](https://apidock.com/ruby/DateTime/strftime)
 - `gh_edit_repository` is the URL of the project's GitHub repository
-- `gh_edit_branch` is the branch that the docs site is served from; defaults to `master`
+- `gh_edit_branch` is the branch that the docs site is served from; defaults to `main`
 - `gh_edit_source` is the source directory that your project files are stored in (should be the same as [site.source](https://jekyllrb.com/docs/configuration/options/))
 - `gh_edit_view_mode` is `"tree"` by default, which brings the user to the github page; switch to `"edit"` to bring the user directly into editing mode
 
@@ -121,6 +155,7 @@ _note: `footer_content` is deprecated, but still supported. For a better experie
 # Color scheme supports "light" (default) and "dark"
 color_scheme: dark
 ```
+
 <button class="btn js-toggle-dark-mode">Preview dark color scheme</button>
 
 <script>
@@ -137,51 +172,135 @@ 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.:
+
+```yaml
+callouts:
+  warning:
+    title: Warning
+    color: red
+```
+
+This uses the color `$red-000` for the background of the callout, and `$red-300` for the title and box decoration.[^dark] You can then style a paragraph as a `warning` callout like this:
+
+```markdown
+{: .warning }
+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/setup.scss` file:
+
+```scss
+$pink-000: #f77ef1;
+$pink-100: #f967f1;
+$pink-200: #e94ee1;
+$pink-300: #dd2cd4;
+```
+
+You can override the default `opacity` of the background for a particular callout, e.g.:
+
+```yaml
+callouts:
+  custom:
+    color: pink
+    opacity: 0.3
+```
+
+You can change the default opacity (`0.2`) for all callouts, e.g.:
+
+```yaml
+callouts_opacity: 0.3
+```
+
+You can also adjust the overall level of callouts.
+The value of `callouts_level` is either `quiet` or `loud`;
+`loud` increases the saturation and lightness of the backgrounds.
+The default level is `quiet` when using the `light` or custom color schemes,
+and `loud` when using the `dark color scheme.`
+
+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
-ga_tracking: UA-5555555-55
-ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true by default)
+# Supports a CSV of tracking ID strings (eg. "UA-1234567-89,G-1AB234CDE5")
+ga_tracking: UA-2709176-10
+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
 
 By default, the navigation and search include normal [pages](https://jekyllrb.com/docs/pages/).
-Instead, you can also use [Jekyll collections](https://jekyllrb.com/docs/collections/) which group documents semantically together.
+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:
 
-For example, put all your documentation files in the `_docs` folder and create the `docs` collection:
 ```yaml
 # Define Jekyll collections
 collections:
-  # Define a collection named "docs", its documents reside in the "_docs" directory
-  docs:
+  # Define a collection named "tests", its documents reside in the "_tests" directory
+  tests:
     permalink: "/:collection/:path/"
     output: true
 
 just_the_docs:
   # Define which collections are used in just-the-docs
   collections:
-    # Reference the "docs" collection
-    docs:
+    # Reference the "tests" collection
+    tests:
       # Give the collection a name
-      name: Documentation
+      name: Tests
       # Exclude the collection from the navigation
       # Supports true or false (default)
-      nav_exclude: false
+      # nav_exclude: true
+      # Fold the collection in the navigation
+      # Supports true or false (default)
+      # nav_fold: true  # note: this option is new in v0.4
       # Exclude the collection from the search
       # Supports true or false (default)
-      search_exclude: false
+      # search_exclude: true
 ```
 
+The navigation for all your normal pages (if any) is displayed before those in collections.
+
 You can reference multiple collections.
 This creates categories in the navigation with the configured names.
+
 ```yaml
 collections:
-  docs:
+  tests:
     permalink: "/:collection/:path/"
     output: true
   tutorials:
@@ -190,9 +309,12 @@ collections:
 
 just_the_docs:
   collections:
-    docs:
-      name: Documentation
+    tests:
+      name: Tests
     tutorials:
       name: Tutorials
 ```
 
+When *all* your pages are in a single collection, its name is not displayed.
+
+The navigation for each collection is a separate name space for page titles: a page in one collection cannot be a child of a page in a different collection, or of a normal page.

docs/customization.md

@@ -16,10 +16,6 @@ nav_order: 6
 ---
 
 ## Color schemes
-{: .d-inline-block }
-
-New
-{: .label .label-green }
 
 Just the Docs supports two color schemes: light (default), and dark.
 
@@ -32,6 +28,7 @@ To enable a color scheme, set the `color_scheme` parameter in your site's `_conf
 # Color scheme supports "light" (default) and "dark"
 color_scheme: dark
 ```
+
 <button class="btn js-toggle-dark-mode">Preview dark color scheme</button>
 
 <script>
@@ -56,7 +53,18 @@ 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.
 
-Available variables are listed in the [_variables.scss](https://github.com/pmarsceill/just-the-docs/tree/master/_sass/support/_variables.scss) file.
+{: .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:
 
@@ -67,12 +75,17 @@ For example, to change the link color from the purple default to blue, include t
 $link-color: $blue-000;
 ```
 
+Keep in mind that changing a variable will not automatically change the value of other variables that depend on it.
+For example, the default link color (`$link-color`) is set to `$purple-000`. However, redefining `$purple-000` in a custom color scheme will not automatically change `$link-color` to match it.
+Instead, each variable that relies on previously-cascaded values must be manually reimplemented by copying the dependent rules from `_variables.scss` — in this case, rewriting `$link-color: $purple-000;`.
+
 _Note:_ Editing the variables directly in `_sass/support/variables.scss` is not recommended and can cause other dependencies to fail.
 Please use scheme files.
 
 ### Use a custom scheme
 
 To use the custom color scheme, only set the `color_scheme` parameter in your site's `_config.yml` file:
+
 ```yaml
 color_scheme: foo
 ```
@@ -80,7 +93,7 @@ color_scheme: foo
 ### Switchable custom scheme
 
 If you want to be able to change the scheme dynamically, for example via javascript, just add a file `assets/css/just-the-docs-foo.scss` (replace `foo` by your scheme name)
-with the following content:`
+with the following content:
 
 {% raw %}
     ---
@@ -91,12 +104,32 @@ with the following content:`
 This allows you to switch the scheme via the following javascript.
 
 ```js
-jtd.setTheme('foo');
+jtd.setTheme("foo")
 ```
 
+## Override and define new variables
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }
+
+To define new SCSS variables, functions, or override existing theme variables, place SCSS code in `_sass/custom/setup.scss`. This should *not* be used for defining custom styles (see the next section).
+
+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.
@@ -109,7 +142,256 @@ For example, if you'd like to add your own styles for printing a page, you could
 ```scss
 // Print-only styles.
 @media print {
-  .side-bar, .page-header { display: none; }
-  .main-content { max-width: auto; margin: 1em;}
+  .side-bar,
+  .page-header {
+    display: none;
+  }
+  .main-content {
+    max-width: auto;
+    margin: 1em;
+  }
 }
 ```
+
+## Override includes
+
+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. 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).
+
+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
+
+`_includes/footer_custom.html`
+
+This content appears at the bottom of every page's main content. More info for this include can be found in the [Configuration - Footer content]({% link docs/configuration.md %}#footer-content).
+
+### Custom Head
+
+`_includes/head_custom.html`
+
+Any HTML added to this file will be inserted before the closing `<head>` tag. This might include additional `<meta>`, `<link>`, or `<script>` tags.
+
+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`.
+
+### Custom Header
+
+`_includes/header_custom.html`
+
+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

@@ -4,6 +4,22 @@ title: Markdown kitchen sink
 nav_order: 99
 ---
 
+<button class="btn js-toggle-dark-mode">Preview dark color scheme</button>
+
+<script>
+const toggleDarkMode = document.querySelector('.js-toggle-dark-mode');
+
+jtd.addEvent(toggleDarkMode, 'click', function(){
+  if (jtd.getTheme() === 'dark') {
+    jtd.setTheme('light');
+    toggleDarkMode.textContent = 'Preview dark color scheme';
+  } else {
+    jtd.setTheme('dark');
+    toggleDarkMode.textContent = 'Return to the light side';
+  }
+});
+</script>
+
 Text can be **bold**, _italic_, or ~~strikethrough~~.
 
 [Link to another page](another-page).
@@ -53,6 +69,12 @@ end
 
 ###### [](#header-6)Header 6
 
+[This is a very long link which wraps and therefore doesn't overflow
+even when it comes at the beginning](.) of the line.
+
+- [This is a very long link which wraps and therefore doesn't overflow the line
+  when used first in an item ](.) in a list.
+
 | head1        | head two          | three |
 |:-------------|:------------------|:------|
 | ok           | good swedish fish | nice  |
@@ -78,6 +100,24 @@ end
 1.  Item three
 1.  Item four
 
+### And an ordered list, continued:
+
+1.  Item one
+1.  Item two
+
+Some text
+
+{:style="counter-reset:none"}
+1.  Item three
+1.  Item four
+
+### And an ordered list starting from 42:
+
+{:style="counter-reset:step-counter 41"}
+1.  Item 42
+1.  Item 43
+1.  Item 44
+
 ### And a nested list:
 
 - level 1 item
@@ -118,14 +158,62 @@ end
 - [ ] Hello, this is another TODO item
 - [x] Goodbye, this item is done
 
+### Nesting task lists
+
+- [ ] level 1 item (task)
+   - [ ] level 2 item (task)
+   - [ ] level 2 item (task)
+- [ ] level 1 item (task)
+- [ ] level 1 item (task)
+
+### Nesting a ul in a task list
+
+- [ ] level 1 item (task)
+   - level 2 item (ul)
+   - level 2 item (ul)
+- [ ] level 1 item (task)
+- [ ] level 1 item (task)
+
+### Nesting a task list in a ul
+
+- level 1 item (ul)
+   - [ ] level 2 item (task)
+   - [ ] level 2 item (task)
+- level 1 item (ul)
+- level 1 item (ul)
+
 ### Small image
 
-![](https://assets-cdn.github.com/images/icons/emoji/octocat.png)
+![](../../assets/images/small-image.jpg)
 
 ### Large image
 
-![](https://guides.github.com/activities/hello-world/branching.png)
+![](../../assets/images/large-image.jpg)
 
+"[Wroclaw University Library digitizing rare archival texts](https://www.flickr.com/photos/97810305@N08/9401451269)" by [j_cadmus](https://www.flickr.com/photos/97810305@N08) is marked with [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/?ref=openverse).
+
+### Labels
+
+I'm a label
+{: .label }
+
+blue
+{: .label .label-blue }
+green
+{: .label .label-green }
+purple
+{: .label .label-purple }
+yellow
+{: .label .label-yellow }
+red
+{: .label .label-red }
+
+**bold**
+{: .label }
+*italic*
+{: .label }
+***bold + italic***
+{: .label }
 
 ### Definition lists can be used with HTML syntax.
 
@@ -171,10 +259,58 @@ Term2
 
 ### More code
 
+```python{% raw %}
+def dump_args(func):
+    "This decorator dumps out the arguments passed to a function before calling it"
+    argnames = func.func_code.co_varnames[:func.func_code.co_argcount]
+    fname = func.func_name
+    def echo_func(*args,**kwargs):
+        print fname, ":", ', '.join(
+            '%s=%r' % entry
+            for entry in zip(argnames,args) + kwargs.items())
+        return func(*args, **kwargs)
+    return echo_func
+
+@dump_args
+def f1(a,b,c):
+    print a + b + c
+
+f1(1, 2, 3)
+
+def precondition(precondition, use_conditions=DEFAULT_ON):
+    return conditions(precondition, None, use_conditions)
+
+def postcondition(postcondition, use_conditions=DEFAULT_ON):
+    return conditions(None, postcondition, use_conditions)
+
+class conditions(object):
+    __slots__ = ('__precondition', '__postcondition')
+
+    def __init__(self, pre, post, use_conditions=DEFAULT_ON):
+        if not use_conditions:
+            pre, post = None, None
+
+        self.__precondition  = pre
+        self.__postcondition = post
+{% endraw %}```
+
 ```
 Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.
 ```
 
+### Mermaid Diagrams
+
+The following code is displayed as a diagram only when a `mermaid` key supplied in `_config.yml`.
+
+```mermaid
+graph TD;
+    A-->B;
+    A-->C;
+    B-->D;
+    C-->D;
+```
+
+
 ```
 The final element.
 ```

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

@@ -12,7 +12,7 @@ nav_order: 5
     Table of contents
   </summary>
   {: .text-delta }
-1. TOC
+- TOC
 {:toc}
 </details>
 
@@ -39,15 +39,15 @@ layout: default
 title: Customization
 nav_order: 4
 ---
+
 ```
 
 The parameter values determine the order of the top-level pages, and of child pages with the same parent. You can reuse the same parameter values (e.g., integers starting from 1) for the child pages of different parents.
 
-The parameter values can be numbers (integers, floats) and/or strings. 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.
-
-> *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. 
+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.
 
 ---
 
@@ -64,11 +64,12 @@ layout: default
 title: 404
 nav_exclude: true
 ---
+
 ```
 
 The `nav_exclude` parameter does not affect the [auto-generating list of child pages](#auto-generating-table-of-contents), which you can use to access pages excluded from the main navigation.
 
-Pages with no `title` are automatically excluded from the navigation. 
+Pages with no `title` are automatically excluded from the main navigation.
 
 ---
 
@@ -104,6 +105,7 @@ Sometimes you will want to create a page with many children (a section). First,
 ```
 
 On the parent pages, add this YAML front matter parameter:
+
 - `has_children: true` (tells us that this is a parent page)
 
 #### Example
@@ -116,11 +118,13 @@ title: UI Components
 nav_order: 2
 has_children: true
 ---
+
 ```
 
 Here we're setting up the UI Components landing page that is available at `/docs/ui-components`, which has children and is ordered second in the main nav.
 
 ### Child pages
+
 {: .text-gamma }
 
 On child pages, simply set the `parent:` YAML front matter to whatever the parent's page title is and set a nav order (this number is now scoped within the section).
@@ -135,10 +139,31 @@ title: Buttons
 parent: UI Components
 nav_order: 2
 ---
+
 ```
 
 The Buttons page appears as a child of UI Components and appears second in the UI Components section.
 
+### Ordering child pages
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }
+
+You can optionally add the following to the YAML front matter to reverse the default sort order of child pages:
+
+- `child_nav_order: reversed`
+
+#### Example
+{: .no_toc }
+```yaml
+---
+layout: default
+title: Reversed Child Pages
+child_nav_order: reversed
+---
+```
+
 ### Auto-generating Table of Contents
 
 By default, all pages with children will automatically append a Table of Contents which lists the child pages after the parent page's content. To disable this auto Table of Contents, set `has_toc: false` in the parent page's YAML front matter.
@@ -154,9 +179,11 @@ nav_order: 2
 has_children: true
 has_toc: false
 ---
+
 ```
 
 ### Children with children
+
 {: .text-gamma }
 
 Child pages can also have children (grandchildren). This is achieved by using a similar pattern on the child and grandchild pages.
@@ -175,6 +202,7 @@ parent: UI Components
 nav_order: 2
 has_children: true
 ---
+
 ```
 
 ```yaml
@@ -185,6 +213,7 @@ parent: Buttons
 grand_parent: UI Components
 nav_order: 1
 ---
+
 ```
 
 This would create the following navigation structure:
@@ -203,11 +232,14 @@ This would create the following navigation structure:
 +-- ..
 ```
 
+{: .note }
+Currently, the navigation structure is limited to 3 levels: grandchild pages cannot themselves have child pages.
+
 ---
 
 ## 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
 {: .no_toc }
@@ -216,11 +248,32 @@ To add auxiliary links to your site (in the upper right on all pages), add it to
 # Aux links for the upper right navigation
 aux_links:
   "Just the Docs on GitHub":
-    - "//github.com/pmarsceill/just-the-docs"
+    - "//github.com/just-the-docs/just-the-docs"
 ```
 
 ---
 
+## External Navigation Links
+
+To add external links to the navigation, add them to the `nav_external_links` [configuration]({% link docs/configuration.md %}) option in your site's `_config.yml` file.
+External links will appear in the navigation after the links to ordinary pages, but before any collections.
+
+#### Example
+{: .no_toc }
+
+```yaml
+# External navigation links
+nav_external_links:
+  - title: Just the Docs on GitHub
+    url: https://github.com/just-the-docs/just-the-docs
+    hide_icon: false # set to true to hide the external link icon - defaults to false
+```
+
+The external links are decorated by an icon, which distinguishes them from internal links.
+You can suppress the icon by setting `hide_icon: true`.
+
+---
+
 ## 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.