Merge branch 'main' into add-chromatic

This PR moves over the changes from https://github.com/just-the-docs/just-the-docs/pull/1112, namely making the `.gitignore` more descriptive and bringing it to parity with the recommendations from Jekyll.

---------

Co-authored-by: Peter Mosses <18308236+pdmosses@users.noreply.github.com>

.babelrc.json

@@ -0,0 +1,15 @@
+{
+  "sourceType": "unambiguous",
+  "presets": [
+    [
+      "@babel/preset-env",
+      {
+        "targets": {
+          "chrome": 100
+        }
+      }
+    ],
+    "@babel/preset-typescript"
+  ],
+  "plugins": []
+}

.github/workflows/chromatic.yml

@@ -0,0 +1,51 @@
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+name: 'Chromatic'
+
+jobs:
+  chromatic:
+    name: "Chromatic"
+    strategy:
+      matrix:
+        jekyll-version: [4.3]
+        os: [ ubuntu-latest ]
+        ruby-version: [3.1]
+        node-version: [18.x]
+    runs-on: ${{ matrix.os }}
+    steps:
+
+    # Ruby setup
+    - uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
+    - name: Setup Ruby ${{ matrix.ruby-version }}
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        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
+
+    # Node setup
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node-version }}
+    - run: npm install
+    - run: npm run build-storybook
+    - name: Publish to Chromatic
+      uses: chromaui/action@v1
+      env:
+        CHROMATIC_PROJECT_TOKEN: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}

.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
       matrix:
         jekyll-version: [3.9, 4.3]
         os: [ ubuntu-latest, macos-latest, windows-latest ]
-        ruby-version: [2.7, 3.1]
+        ruby-version: ["3.0", "3.1", "3.2"]
     runs-on: ${{ matrix.os }}
     steps:
     - uses: actions/checkout@v3
@@ -46,7 +46,7 @@ jobs:
     - name: Setup Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.1'
+        ruby-version: "3.2"
         bundler-cache: false
     - name: Bundle Install
       run: bundle install
@@ -57,6 +57,40 @@ jobs:
       env:
         BUNDLE_GEMFILE: fixtures/Gemfile-github-pages
 
+  validate:
+    name: Validate HTML
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ["3.2"]
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Setup Ruby ${{ matrix.ruby-version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+          cache-version: 0 # Increment this number if you need to re-download cached gems
+      - name: Cache HTMLProofer
+        id: cache-htmlproofer
+        uses: actions/cache@v2
+        with:
+          path: tmp/.htmlproofer
+          key: ${{ runner.os }}-htmlproofer
+      - name: Build Site
+        run: bundle exec jekyll build
+      - name: Test with Nu Validator
+        uses: Cyb3r-Jak3/html5validator-action@c7bb77a0fe3b0458583de50fd0f4dd819569b8a9
+        with:
+          root: _site
+          blacklist: line-numbers
+      - name: Test with html-proofer
+        run: bundle exec htmlproofer _site --ignore-urls "/github.com/,/web.archive.org/"
+        env:
+          NOKOGIRI_USE_SYSTEM_LIBRARIES: true
+
   assets:
     name: Test CSS and JS
     runs-on: ubuntu-latest

.github/workflows/deploy.yml

@@ -34,7 +34,7 @@ jobs:
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.1' # Not needed with a .ruby-version file
+          ruby-version: "3.2"
           bundler-cache: true # runs 'bundle install' and caches installed gems automatically
           cache-version: 0 # Increment this number if you need to re-download cached gems
       - name: Setup Pages

.github/workflows/publish-gem.yml

@@ -10,10 +10,10 @@ jobs:
 
     steps:
     - uses: actions/checkout@v3
-    - name: Set up Ruby 3.1
-      uses: actions/setup-ruby@v1
+    - name: Setup Ruby 3.2
+      uses: ruby/setup-ruby@v1
       with:
-        ruby-version: 3.1
+        ruby-version: "3.2"
 
     - name: Publish to GPR
       run: |

.gitignore

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

.storybook/main.js

@@ -0,0 +1,17 @@
+/** @type { import('@storybook/html-webpack5').StorybookConfig } */
+const config = {
+  stories: ["../stories/**/*.mdx", "../stories/**/*.stories.@(js|jsx|ts|tsx)"],
+  addons: [
+    "@storybook/addon-links",
+    "@storybook/addon-essentials",
+    "@storybook/addon-interactions",
+  ],
+  framework: {
+    name: "@storybook/html-webpack5",
+    options: {},
+  },
+  docs: {
+    autodocs: "tag",
+  },
+}
+export default config

.storybook/preview.js

@@ -0,0 +1,14 @@
+/** @type { import('@storybook/html').Preview } */
+const preview = {
+  parameters: {
+    actions: { argTypesRegex: "^on[A-Z].*" },
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/,
+      },
+    },
+  },
+}
+
+export default preview

CHANGELOG.md

@@ -15,16 +15,132 @@ The project underwent a major maintenance shift in March 2022.
 {: .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.5.2`!
-
 Code changes to `main` that are *not* in the latest release:
 
-- N/A
+- Fixed: Windows emoji font fallback by [@flanakin] in [#1337]
 
-Docs changes in `main` that are *not* in the latest release:
+[#1337]: https://github.com/just-the-docs/just-the-docs/pull/1337
 
-- N/A
+### New Contributors
+
+- [@flanakin] made their first contribution in [#1337]
+
+[@flanakin]: https://github.com/flanakin
+
+## Release v0.6.1
+
+Hi all, this is a small patch release that only includes one change: resolving a bug introduced in 0.6.0 that causes a JS error for pages excluded from navigation.
+
+### Bugfixes
+
+- Fixed: JS error for pages excluded from navigation by [@pdmosses] in [#1332]
+
+[#1332]: https://github.com/just-the-docs/just-the-docs/pull/1332
+
+## Release v0.6.0
+
+Hi all, this is a minor release that introduces performance improvements for build times on large sites, correctly sets the `color-scheme` property, and fixes invalid HTML. However, it introduces some potentially-breaking *internal* changes to undocumented features of the theme.
+
+### Migrating to `v0.6.0`
+
+**Migration**: users will need to migrate if:
+
+- they have an existing `_includes` file named `favicon.html`, `head_nav.html`, or `css/activation.scss.liquid`
+- they have code that refers to `#main-content-wrap`
+- they override the default `light` theme's code, or the theme-loading logic
+- they have different favicons for different pages
+
+For more, refer to the [migration guide](https://just-the-docs.com/MIGRATION/).
+
+### Using Release `v0.6.0`
+
+Users who have not pinned the theme version will be **automatically upgraded to `v0.6.0` the next time they build their site**.
+
+To use this release explicitly as a remote theme:
+
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.6.0
+```
+
+To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
+
+```ruby
+gem "just-the-docs", "0.6.0"
+```
+
+To use and pin a previous version of the theme, replace the `0.6.0` with the desired release tag.
+
+### New Features and Bugfixes
+
+- Added: `$color-scheme` theme variable to specify `color-scheme` for `:root` by [@sigv] in [#1280]
+- Fixed: build times for large sites by [@pdmosses] in [#1244]
+- Fixed: missing closing `</button>` tag in `sidebar.html` by [@mattxwang] in [#1304]
+- Fixed: removed duplicate `#main-content-wrap` minimal and default layouts by [@mattxwang] in [#1305]
+
+### Documentation
+
+{: .warning }
+The theme docs are unversioned, and already reflect the above changes.
+
+Docs changes:
+
+- A [footnote]({% link docs/configuration.md %}#fn:js-disabled) in the configuration docs explains how disabling JavaScript affects the display of navigation links when browsing folded collections.
+- Invalid HTML has been removed from most documentation examples.
+
+### New Contributors
+
+- [@sigv] made their first contribution in [#1280]
+
+[@sigv]: https://github.com/sigv
+[#1244]: https://github.com/just-the-docs/just-the-docs/pull/1244
+[#1280]: https://github.com/just-the-docs/just-the-docs/pull/1280
+[#1304]: https://github.com/just-the-docs/just-the-docs/pull/1304
+[#1305]: https://github.com/just-the-docs/just-the-docs/pull/1305
+
+## Release v0.5.4
+
+Hi all, this is a small patch release that only includes one change: fixing a style clash between Mermaid's labels and Just the Docs' labels.
+
+*Note: for subsequent patch releases, we will omit migration instructions (for brevity). In all cases, immediate migration should be backwards-compatible. Refer to previous major or minor update instructions for more information.*
+
+### Bugfixes
+
+- Fixed: Mermaid labels inheriting theme `.label` styling by [@mattxwang] in [#1278]
+
+[#1278]: https://github.com/just-the-docs/just-the-docs/pull/1278
+
+## Release v0.5.3
+
+Hi all, this is a minor patch release that only includes one change: changing all text-based CSS properties to use `rem` instead of hard-coded `px` values. This has two effects:
+
+1. All deprecation warnings are now fixed on build; you should now get a clean build with `jekyll build`.
+2. We have **deprecated the `$root-font-size` SCSS variable**. We will remove it in an upcoming release of the theme.
+
+If you use the stock Just the Docs theme, this release should have no impact on your final built site. If you change the `$root-font-size` SCSS variable, you might experience light layout shifts.
+
+### Using Release `v0.5.3`
+
+Users who have not pinned the theme version will be **automatically upgraded to `v0.5.3` the next time they build their site**.
+
+To use this release explicitly as a remote theme:
+
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.5.3
+```
+
+To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
+
+```ruby
+gem "just-the-docs", "0.5.3"
+```
+
+To use and pin a previous version of the theme, replace the `0.5.3` with the desired release tag.
+
+### Bugfixes
+
+- Fixed: font-size scaling for text-related CSS properties by using `rem` instead of fixed `px` values; deprecate `$root-font-size` by [@mattxwang] in [#1169]
+
+[#1169]: https://github.com/just-the-docs/just-the-docs/pull/1169
 
 ## Release v0.5.2
 

Gemfile

@@ -3,4 +3,6 @@ gemspec
 
 gem "jekyll-github-metadata", ">= 2.15"
 
-gem "webrick", "~> 1.7"
+gem "jekyll-include-cache", group: :jekyll_plugins
+
+gem "html-proofer", "~> 5.0", :group => :development

Gemfile.lock

@@ -0,0 +1,150 @@
+PATH
+  remote: .
+  specs:
+    just-the-docs (0.6.1)
+      jekyll (>= 3.8.5)
+      jekyll-include-cache
+      jekyll-seo-tag (>= 2.0)
+      rake (>= 12.3.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    Ascii85 (1.1.0)
+    addressable (2.8.4)
+      public_suffix (>= 2.0.2, < 6.0)
+    afm (0.2.2)
+    async (2.6.3)
+      console (~> 1.10)
+      fiber-annotation
+      io-event (~> 1.1)
+      timers (~> 4.1)
+    colorator (1.1.0)
+    concurrent-ruby (1.2.2)
+    console (1.23.2)
+      fiber-annotation
+      fiber-local
+    em-websocket (0.5.3)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0)
+    ethon (0.16.0)
+      ffi (>= 1.15.0)
+    eventmachine (1.2.7)
+    faraday (2.7.10)
+      faraday-net_http (>= 2.0, < 3.1)
+      ruby2_keywords (>= 0.0.4)
+    faraday-net_http (3.0.2)
+    ffi (1.15.5)
+    fiber-annotation (0.2.0)
+    fiber-local (1.0.0)
+    forwardable-extended (2.6.0)
+    google-protobuf (3.23.4-arm64-darwin)
+    google-protobuf (3.23.4-x86_64-linux)
+    hashery (2.1.2)
+    html-proofer (5.0.8)
+      addressable (~> 2.3)
+      async (~> 2.1)
+      nokogiri (~> 1.13)
+      pdf-reader (~> 2.11)
+      rainbow (~> 3.0)
+      typhoeus (~> 1.3)
+      yell (~> 2.0)
+      zeitwerk (~> 2.5)
+    http_parser.rb (0.8.0)
+    i18n (1.14.1)
+      concurrent-ruby (~> 1.0)
+    io-event (1.2.3)
+    jekyll (4.3.2)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 1.0)
+      jekyll-sass-converter (>= 2.0, < 4.0)
+      jekyll-watch (~> 2.0)
+      kramdown (~> 2.3, >= 2.3.1)
+      kramdown-parser-gfm (~> 1.0)
+      liquid (~> 4.0)
+      mercenary (>= 0.3.6, < 0.5)
+      pathutil (~> 0.9)
+      rouge (>= 3.0, < 5.0)
+      safe_yaml (~> 1.0)
+      terminal-table (>= 1.8, < 4.0)
+      webrick (~> 1.7)
+    jekyll-github-metadata (2.16.0)
+      jekyll (>= 3.4, < 5.0)
+      octokit (>= 4, < 7, != 4.4.0)
+    jekyll-include-cache (0.2.1)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-sass-converter (3.0.0)
+      sass-embedded (~> 1.54)
+    jekyll-seo-tag (2.8.0)
+      jekyll (>= 3.8, < 5.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    kramdown (2.4.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    liquid (4.0.4)
+    listen (3.8.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    mercenary (0.4.0)
+    nokogiri (1.15.4-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.15.4-x86_64-linux)
+      racc (~> 1.4)
+    octokit (6.1.1)
+      faraday (>= 1, < 3)
+      sawyer (~> 0.9)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    pdf-reader (2.11.0)
+      Ascii85 (~> 1.0)
+      afm (~> 0.2.1)
+      hashery (~> 2.0)
+      ruby-rc4
+      ttfunk
+    public_suffix (5.0.3)
+    racc (1.7.1)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rexml (3.2.6)
+    rouge (4.1.2)
+    ruby-rc4 (0.1.5)
+    ruby2_keywords (0.0.5)
+    safe_yaml (1.0.5)
+    sass-embedded (1.64.1-arm64-darwin)
+      google-protobuf (~> 3.23)
+    sass-embedded (1.64.1-x86_64-linux-gnu)
+      google-protobuf (~> 3.23)
+    sawyer (0.9.2)
+      addressable (>= 2.3.5)
+      faraday (>= 0.17.3, < 3)
+    terminal-table (3.0.2)
+      unicode-display_width (>= 1.1.1, < 3)
+    timers (4.3.5)
+    ttfunk (1.7.0)
+    typhoeus (1.4.0)
+      ethon (>= 0.9.0)
+    unicode-display_width (2.4.2)
+    webrick (1.8.1)
+    yell (2.2.2)
+    zeitwerk (2.6.11)
+
+PLATFORMS
+  arm64-darwin
+  x86_64-linux
+
+DEPENDENCIES
+  bundler (>= 2.3.5)
+  html-proofer (~> 5.0)
+  jekyll-github-metadata (>= 2.15)
+  jekyll-include-cache
+  just-the-docs!
+
+BUNDLED WITH
+   2.4.13

MIGRATION.md

@@ -43,6 +43,78 @@ This document contains instructions on how to migrate and upgrade Just the Docs
 
 [CHANGELOG]: {{ site.baseurl }}{% link CHANGELOG.md %}
 
+## v0.5.x - v0.6.0
+
+### POTENTIALLY-BREAKING CHANGES in v0.6.0
+
+There are some *very minor* potentially-breaking changes for users in version `v0.6.0`. **They do not affect the vast majority of users**; however, this may affect users of (undocumented) internal theme structure. They concern:
+
+1. the addition of new `_includes/favicon.html`, `_includes/head_nav.html`, and `_includes/css/activation.scss.liquid`
+  - **explicit migration only necessary if users have defined a custom file with the same name**
+2. removing `id="main-content-wrap` from wrapper `div` elements in default layouts
+  - **explicit migration only necessary if users have written code that depends on `#main-content-wrap`**
+3. loading the new `$color-scheme` variable (from the light scheme by default)
+  - **explicit migration only necessary if users have overridden the base light theme**
+4. caching the favicon for the entire site
+  - **explicit migration only necessary if users have different favicons for different pages**
+
+#### New Includes
+
+Version `v0.6.0` introduces three new `_includes` files:
+
+- `_includes/favicon.html`, which now contains logic previously in `_includes/head.html`: loading `favicon.ico` if no favicon is specified
+- `_includes/head_nav.html`, which generates CSS used for the new efficient navigation implementation
+- `_includes/css/activation.scss.liquid`, which is used by `head_nav` for navigation implementation
+
+If users have existing `_includes` files with this name, they should be renamed (and imported with their new name) prior to upgrading to `0.6.0`. No other change is necessary.
+
+#### Removed `#main-content-wrap`
+
+In `_layouts/default.html` and `_layouts/minimal.html`, the `id="main-content-wrap"` has been removed from the wrapper div (in part due to a bug with multiple `id`s on one element). Internally, our theme *does not use* these `id`s; for most users, this does not require any action.
+
+However, code that relies on this `id` must be changed. Each of the related elements still has the unique class `.main-content-wrap`, and can be selected with this class. For example, in CSS:
+
+```css
+/* OLD */
+#main-content-wrap { /* ... */ }
+
+/* NEW */
+.main-content-wrap { /* ... */ }
+```
+
+Or in JS:
+
+```js
+// OLD
+document.getElementById("main-content-wrap");
+
+// NEW
+document.getElementsByClassName("main-content-wrap")[0];
+```
+
+#### New `$color-scheme` variable
+
+The theme now properly sets the `color-scheme` property. To do so, the new `$color-scheme` SCSS variable has been created. The variable has been added to the default `light` scheme, which is *always* loaded by Just the Docs.
+
+Migration is only needed if:
+
+- the packaged `light` scheme has been *overridden* (this is *not* the same as using a custom scheme)
+- or, the scheme logic to always load `light` has been changed
+
+(neither of these behaviours are recommended by Just the Docs)
+
+In either of these cases, users should add a `$color-scheme` SCSS variable to their active scheme with the appropriate value (see: [MDN docs on `color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme)).
+
+```scss
+$color-scheme: light !default;
+```
+
+#### Cached favicon
+
+Version `v0.6.0` adds a new `_include` that caches the favicon for the entire site. This significantly improves page build times for large sites.
+
+However, some users may load different favicons for each page (and/or dynamically change the first favicon load). In this case, they should override the logic in `_includes/favicon.html` by **replacing** it with an empty file (this is *different* from deleting it). No further migration is necessary.
+
 ## v0.4.x - v0.5.0
 
 ### POTENTIALLY-BREAKING CHANGES in v0.5.0

_config.yml

@@ -48,6 +48,7 @@ exclude:
    - Dockerfile
  # theme test code
    - fixtures/
+   - stories/
 
 # Set a path/url to a logo that will be displayed instead of the title
 #logo: "/assets/images/just-the-docs.png"
@@ -102,7 +103,7 @@ heading_anchors: true
 # Aux links for the upper right navigation
 aux_links:
   "Just the Docs on GitHub":
-    - "//github.com/just-the-docs/just-the-docs"
+    - "https://github.com/just-the-docs/just-the-docs"
 
 # Makes Aux links open in a new tab. Default is false
 aux_links_new_tab: false
@@ -168,6 +169,7 @@ callouts:
 plugins:
   - jekyll-seo-tag
   - jekyll-github-metadata
+  - jekyll-include-cache
 
 kramdown:
   syntax_highlighter_opts:

_includes/components/sidebar.html

@@ -1,9 +1,21 @@
+{%- comment -%}
+  Include as: {%- include components/sidebar.html -%}
+  Depends on: page(?), site.
+  Results in: HTML for the side bar.
+  Includes:
+    title.html, nav.html, nav_footer_custom.html
+  Overwrites: 
+    pages_top_size, collections_size, collection_entry,
+    collection_key, collection_value, collection, nav_footer_custom.
+  Should not be cached, because nav_footer_custom.html might depend on page.
+{%- endcomment -%}
+
 <div class="side-bar">
   <div class="site-header" role="banner">
     <a href="{{ '/' | relative_url }}" class="site-title lh-tight">{% include title.html %}</a>
     <button id="menu-button" class="site-button btn-reset" aria-label="Toggle menu" aria-pressed="false">
       <svg viewBox="0 0 24 24" class="icon" aria-hidden="true"><use xlink:href="#svg-menu"></use></svg>
-    </a>
+    </button>
   </div>
   <nav aria-label="Main" id="site-nav" class="site-nav">
     {% assign pages_top_size = site.html_pages
@@ -12,7 +24,7 @@
           | where_exp:"item", "item.nav_exclude != true"
           | size %}
     {% if pages_top_size > 0 %}
-      {% include nav.html pages=site.html_pages key=nil %}
+      {% include_cached nav.html pages=site.html_pages %}
     {% endif %}
     {%- if site.nav_external_links -%}
       <ul class="nav-list">
@@ -43,15 +55,15 @@
                   </button>
                   {%- endif -%}
                   <div class="nav-category">{{ collection_value.name }}</div>
-                  {% include nav.html pages=collection key=collection_key %}
+                  {% include_cached nav.html pages=collection %}
                 </li>
               </ul>
             {% else %}
               <div class="nav-category">{{ collection_value.name }}</div>
-              {% include nav.html pages=collection key=collection_key %}
+              {% include_cached nav.html pages=collection %}
             {% endif %}
           {% else %}
-            {% include nav.html pages=collection key=collection_key %}
+            {% include_cached nav.html pages=collection %}
           {% endif %}
         {% endif %}
       {% endfor %}

_includes/css/activation.scss.liquid

@@ -0,0 +1,173 @@
+{%- comment -%}
+  Include as: {%- include css/activation.scss.liquid -%}
+  Depends on: page, site.
+  Results in: page-dependent SCSS rules for inclusion in a head style element.
+  Includes:
+    sorted_pages.html.
+  Overwrites: 
+    activation_pages, activation_pages_top_size, activation_page, activation_title,
+    activation_first_level, activation_second_level, activation_third_level,
+    activation_first_level_reversed, activation_second_level_reversed,
+    activation_first_level_index, activation_second_level_index, activation_third_level_index.
+  Should not be cached, because it depends on page.
+  (For a site with only top-level pages, the rendering of this file is always empty.
+  This property could be detected, and might halve the build time for such sites.)
+{%- endcomment -%}
+
+{%- unless page.title == nil or page.nav_exclude == true -%}
+
+{%- assign activation_pages = site[page.collection]
+      | default: site.html_pages
+      | where_exp: "item", "item.title != nil"
+      | where_exp: "item", "item.nav_exclude != true" -%}
+
+{%- assign activation_first_level_index = nil -%}
+{%- assign activation_second_level_index = nil -%}
+{%- assign activation_third_level_index = nil -%}
+{%- assign activation_first_level_reversed = nil -%}
+{%- assign activation_second_level_reversed = nil -%}
+
+{%- assign activation_title = page.grand_parent | default: page.parent | default: page.title -%}
+{%- assign activation_first_level = activation_pages
+      | where_exp: "item", "item.parent == nil" -%}
+{%- include sorted_pages.html pages = activation_first_level -%}
+{%- for activation_page in sorted_pages -%}
+  {%- if activation_page.title == activation_title -%}
+    {%- assign activation_first_level_index = forloop.index -%}
+    {%- assign activation_first_level_reversed = activation_page.child_nav_order -%}
+    {%- break -%}
+  {%- endif -%}
+{%- endfor -%}
+
+{%- unless activation_first_level_index == nil -%}
+
+{%- if page.grand_parent -%}
+  {%- assign activation_title = page.parent -%}
+  {%- assign activation_second_level = activation_pages
+        | where_exp: "item", "item.grand_parent == nil"
+        | where_exp: "item", "item.parent == page.grand_parent" -%}
+{%- elsif page.parent -%}
+  {%- assign activation_title = page.title -%}
+  {%- assign activation_second_level = activation_pages
+        | where_exp: "item", "item.grand_parent == nil"
+        | where_exp: "item", "item.parent == page.parent" -%}
+{%- endif -%}
+{%- if page.parent -%}
+  {%- include sorted_pages.html pages = activation_second_level -%}
+  {%- for activation_page in sorted_pages -%}
+    {%- if activation_page.title == activation_title -%}
+      {%- assign activation_second_level_index = forloop.index -%}
+      {%- assign activation_second_level_reversed = activation_page.child_nav_order -%}
+      {%- if activation_first_level_reversed -%}
+        {%- assign activation_second_level_index = sorted_pages | size | plus: 1 | minus: activation_second_level_index -%}
+      {%- endif -%}
+      {%- break -%}
+    {%- endif -%}
+  {%- endfor -%}
+{%- endif -%}
+
+{%- if page.grand_parent -%}
+  {%- assign activation_third_level = activation_pages
+        | where_exp: "item", "item.parent == page.parent"
+        | where_exp: "item", "item.grand_parent == page.grand_parent" -%}
+  {%- include sorted_pages.html pages = activation_third_level -%}
+  {%- assign activation_third_level = sorted_pages -%}
+  {%- for activation_page in sorted_pages -%}
+    {%- if activation_page.title == page.title -%}
+      {%- assign activation_third_level_index = forloop.index -%}
+      {%- if activation_second_level_reversed -%}
+        {%- assign activation_third_level_index = sorted_pages | size | plus: 1 | minus: activation_third_level_index -%}
+      {%- endif -%}
+      {%- break -%}
+    {%- endif -%}
+  {%- endfor -%}
+{%- endif -%}
+
+{%- unless activation_second_level_index == nil and activation_third_level_index -%}
+
+{%- if page.collection == nil -%}
+
+  {%- capture activation_collection_prefix -%}
+  .site-nav > .nav-list:nth-child(1):not(.nav-category-list) 
+  {%- endcapture -%}
+
+{%- else -%}
+
+  {%- for activation_collection in site.just_the_docs.collections -%}
+    {%- if activation_collection[0] == page.collection -%}
+      {%- assign activation_collection_index = forloop.index -%}
+      {%- break -%}
+    {%- endif -%}
+  {%- endfor -%}
+  {%- assign activation_index = activation_collection_index -%}
+  {%- assign activation_pages_top_size = site.html_pages
+          | where_exp:"item", "item.title != nil"
+          | where_exp:"item", "item.parent == nil"
+          | where_exp:"item", "item.nav_exclude != true"
+          | size -%}
+  {%- if activation_pages_top_size > 0  -%}
+    {%- assign activation_index = activation_index | plus: 1 -%}
+  {%- endif -%}
+  {%- if site.nav_external_links -%}
+    {%- assign activation_index = activation_index | plus: 1 -%}
+  {%- endif -%}
+  {%- capture activation_collection_prefix -%}
+  .site-nav > .nav-list:nth-of-type({{ activation_index }}){% if site.just_the_docs.collections[page.collection].nav_fold == true %} > .nav-list-item > .nav-list{% endif %}
+  {%- endcapture -%}
+  
+{%- endif -%}
+
+// Styling for the nav-list-link to the current page:
+{{ activation_collection_prefix }} {
+  > .nav-list-item:not(.external):nth-child({{ activation_first_level_index }}){%- if activation_second_level_index %} > .nav-list > .nav-list-item:nth-child({{ activation_second_level_index }}){%- if activation_third_level_index %} > .nav-list > .nav-list-item:nth-child({{ activation_third_level_index }}){% endif %}{% endif %} {
+    > .nav-list-link {
+      display: block;
+      font-weight: 600;
+      text-decoration: none;
+      background-image: linear-gradient(
+        -90deg,
+        rgba($feedback-color, 1) 0%,
+        rgba($feedback-color, 0.8) 80%,
+        rgba($feedback-color, 0) 100%
+      );
+    }
+  }
+}
+
+// Styling for nav-list-expanders at first and second levels,
+// suppressed when a click has deactivated the expander (making the nav-list-item .passive):
+{{ activation_collection_prefix }} {
+  > .nav-list-item:not(.passive):nth-child({{ activation_first_level_index }}){%- if activation_second_level_index %},
+  > .nav-list-item:not(.passive):nth-child({{ activation_first_level_index }}) > .nav-list > .nav-list-item:not(.passive):nth-child({{ activation_second_level_index }}){% endif %} {
+    > .nav-list-expander svg {
+      @if $nav-list-expander-right {
+        transform: rotate(-90deg);
+      } @else {
+        transform: rotate(90deg);
+      }
+    }
+
+    > .nav-list {
+      display: block;
+    }
+  }
+}
+
+// Styling for nav-list-expander for categories:
+.site-nav > .nav-category-list > .nav-list-item:not(.passive) {
+  > .nav-list-expander svg {
+    @if $nav-list-expander-right {
+      transform: rotate(-90deg);
+    } @else {
+      transform: rotate(90deg);
+    }
+  }
+
+  > .nav-list {
+    display: block;
+  }
+}
+
+{%- endunless -%}
+{%- endunless -%}
+{%- endunless -%}

_includes/favicon.html

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

_includes/head.html

@@ -1,9 +1,23 @@
+{%- comment -%}
+  Include as: {%- include head.html -%}
+  Depends on: site.ga_tracking, site.ga_tracking_anonymize_ip,
+    site.search_enabled, site.static_files, site.favicon_ico.
+  Results in: HTML for the head element.
+  Includes:
+    head_nav.html, head_custom.html.
+  Overwrites: 
+    ga_tracking_ids, ga_property, file, favicon.
+  Should not be cached, because included files depend on page.
+{%- endcomment -%}
+
 <head>
   <meta charset="UTF-8">
   <meta http-equiv="X-UA-Compatible" content="IE=Edge">
 
   <link rel="stylesheet" href="{{ '/assets/css/just-the-docs-default.css' | relative_url }}">
   
+  {% include head_nav.html %}
+
   {% if site.ga_tracking != nil %}
     {% assign ga_tracking_ids = site.ga_tracking | split: "," %}
     <script async src="https://www.googletagmanager.com/gtag/js?id={{ ga_tracking_ids.first }}"></script>
@@ -26,14 +40,7 @@
 
   <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 %}
+  {% include_cached favicon.html %}
 
   {% seo %}
 

_includes/head_nav.html

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

_includes/nav.html

@@ -1,6 +1,6 @@
 {%- comment -%}
-  Include as: {%- include nav.html pages = pages key = key -%}
-  Depends on: include.pages, include.key, page, site.
+  Include as: {%- include_cached nav.html pages=pages -%}
+  Depends on: include.pages.
   Results in: HTML for the navigation panel.
   Includes:
     sorted_pages.html
@@ -15,6 +15,10 @@
 
 {%- include sorted_pages.html pages = nav_pages -%}
 
+{%- comment -%}
+  It might be more efficient to sort the pages at each level separately.
+{%- endcomment -%}
+
 {%- assign first_level_pages = sorted_pages
     | where_exp: "item", "item.parent == nil" -%}
 {%- assign second_level_pages = sorted_pages
@@ -23,84 +27,49 @@
 {%- assign third_level_pages = sorted_pages
     | where_exp: "item", "item.grand_parent != nil" -%}
 
-{%- comment -%}
-  The order of sibling pages in `sorted_pages` determines the order of display of
-  links to them in lists of navigation links.
-
-  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 -%}
-
 <ul class="nav-list">
 {%- for node in first_level_pages -%}
-    {%- unless node.nav_exclude -%}
-      <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 -%}
-        <button class="nav-list-expander btn-reset" aria-label="toggle items in {{ node.title }} category" aria-pressed="{% 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 %}true{% else %}false{% endif %}">
-          <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg>
-        </button>
-        {%- endif -%}
-        <a href="{{ node.url | relative_url }}" class="nav-list-link{% if page.url == node.url %} active{% endif %}">{{ node.title }}</a>
-        {%- if node.has_children -%}
-          {%- assign children_list = second_level_pages
-                | where: "parent", node.title -%}
-          {%- if node.child_nav_order == 'desc' or node.child_nav_order == 'reversed' -%}
-            {%- assign children_list = children_list | reverse -%}
+  <li class="nav-list-item">
+    {%- if node.has_children -%}
+    <button class="nav-list-expander btn-reset" aria-label="toggle items in {{ node.title }} category" aria-pressed="false">
+      <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg>
+    </button>
+    {%- endif -%}
+    <a href="{{ node.url | relative_url }}" class="nav-list-link">{{ node.title }}</a>
+    {%- if node.has_children -%}
+      {%- assign children_list = second_level_pages
+            | where: "parent", node.title -%}
+      {%- if node.child_nav_order == 'desc' or node.child_nav_order == 'reversed' -%}
+        {%- assign children_list = children_list | reverse -%}
+      {%- endif -%}
+      <ul class="nav-list">
+      {%- for child in children_list -%}
+        <li class="nav-list-item">
+          {%- if child.has_children -%}
+          <button class="nav-list-expander btn-reset" aria-label="toggle items in {{ child.title }} category" aria-pressed="false">
+            <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg>
+          </button>
           {%- endif -%}
-          <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 -%}
-                <button class="nav-list-expander btn-reset" aria-label="toggle items in {{ child.title }} category" aria-pressed="{% if page.url == child.url or page.parent == child.title %}true{% else %}false{% endif %}">
-                  <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg>
-                </button>
-              {%- endif -%}
-              <a href="{{ child.url | relative_url }}" class="nav-list-link{% if page.url == child.url %} active{% endif %}">{{ child.title }}</a>
-              {%- if child.has_children -%}
-                {%- assign grand_children_list = third_level_pages
-                      | where: "parent", child.title
-                      | where: "grand_parent", node.title -%}
-                {%- if child.child_nav_order == 'desc' or child.child_nav_order == 'reversed' -%}
-                  {%- assign grand_children_list = grand_children_list | reverse -%}
-                {%- endif -%}
-                <ul class="nav-list">
-                {%- for grand_child in grand_children_list -%}
-                  {%- unless grand_child.nav_exclude -%}
-                  <li class="nav-list-item {% if page.url == grand_child.url %} active{% endif %}">
-                    <a href="{{ grand_child.url | relative_url }}" class="nav-list-link{% if page.url == grand_child.url %} active{% endif %}">{{ grand_child.title }}</a>
-                  </li>
-                  {%- endunless -%}
-                {%- endfor -%}
-                </ul>
-              {%- endif -%}
-            </li>
-            {%- endunless -%}
-          {%- endfor -%}
-          </ul>
-        {%- endif -%}
-      </li>
-    {%- endunless -%}
+          <a href="{{ child.url | relative_url }}" class="nav-list-link">{{ child.title }}</a>
+          {%- if child.has_children -%}
+            {%- assign grand_children_list = third_level_pages
+                  | where: "parent", child.title
+                  | where: "grand_parent", node.title -%}
+            {%- if child.child_nav_order == 'desc' or child.child_nav_order == 'reversed' -%}
+              {%- assign grand_children_list = grand_children_list | reverse -%}
+            {%- endif -%}
+            <ul class="nav-list">
+            {%- for grand_child in grand_children_list -%}
+              <li class="nav-list-item">
+                <a href="{{ grand_child.url | relative_url }}" class="nav-list-link">{{ grand_child.title }}</a>
+              </li>
+            {%- endfor -%}
+            </ul>
+          {%- endif -%}
+        </li>
+      {%- endfor -%}
+      </ul>
+    {%- endif -%}
+  </li>
 {%- endfor -%}
 </ul>

_includes/sorted_pages.html

@@ -1,9 +1,9 @@
 {%- comment -%}
-  Include as: {%- include sorted_pages.html pages = pages -%}
+  Include as: {%- include sorted_pages.html pages=array_of_pages -%}
   Depends on: include.pages.
   Assigns to: sorted_pages.
   Overwrites: 
-    nav_order_pages, title_order_pages, 
+    nav_order_pages, title_order_pages, double_quote, empty_array,
     nav_number_pages, nav_string_pages, nav_order_groups, group,
     title_number_pages, title_string_pages, title_order_groups.
 {%- endcomment -%}
@@ -29,29 +29,55 @@
 {%- endcomment -%}
 
 {%- assign nav_order_pages = include.pages
-    | where_exp: "item", "item.nav_order != nil" -%}
+      | where_exp: "item", "item.nav_order != nil" -%}
 {%- assign title_order_pages = include.pages
-    | where_exp: "item", "item.nav_order == nil" -%}
+      | where_exp: "item", "item.nav_order == nil" -%}
 
 {%- comment -%}
-  Divide the arrays of `nav_order_pages` and `title_order_pages` according to
-  the type of value.
+  First, filter `nav_order_pages` and `title_order_pages` according to the type
+  of value to be used for sorting.
   
-  The first character of the result of `jsonify` is `"` only for strings.
-  Grouping by a single character also ensures the number of groups is small.
+  The first character of the result of filtering with `jsonify` is `"` only for
+  strings. Removing `"` from its `slice : 0` has size 0 for strings and 1 for
+  numbers, so grouping the pages gives at most two groups.
 {%- endcomment -%}
 
-{%- assign 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" -%}
-{%- for group in nav_order_groups -%}
-  {%- if group.name == '"' -%}
-    {%- assign nav_string_pages = group.items -%}
-  {%- else -%}
-    {%- assign nav_number_pages = nav_number_pages | concat: group.items -%}
-  {%- endif -%}
-{%- endfor -%}
+{%- assign double_quote = '"' -%}
+{%- assign empty_array = "" | split: "" -%}
+
+{%- assign nav_string_pages = empty_array -%}
+{%- assign nav_number_pages = empty_array -%}
+{%- unless nav_order_pages == empty -%}
+  {%- assign nav_order_groups = nav_order_pages
+        | group_by_exp: "item",
+            "item.nav_order | jsonify | slice: 0 | remove: double_quote | size" -%}
+  {%- for group in nav_order_groups -%}
+    {%- if group.name == 0 -%}
+      {%- assign nav_string_pages = group.items -%}
+    {%- elsif group.name == 1 -%}
+      {%- assign nav_number_pages = group.items -%}
+    {%- endif -%}
+  {%- endfor -%}
+{%- endunless -%}
+
+{%- assign title_string_pages = empty_array -%}
+{%- assign title_number_pages = empty_array -%}
+{%- unless title_order_pages == empty -%}
+  {%- assign title_order_groups = title_order_pages
+        | group_by_exp: "item",
+            "item.title | jsonify | slice: 0 | remove: double_quote | size" -%}
+  {%- for group in title_order_groups -%}
+    {%- if group.name == 0 -%}
+      {%- assign title_string_pages = group.items -%}
+    {%- elsif group.name == 1 -%}
+      {%- assign title_number_pages = group.items -%}
+    {%- endif -%}
+  {%- endfor -%}
+{%- endunless -%}
+
+{%- comment -%}
+  Now sort each array of pages separately, then concatenate the sorted arrays.
+{%- endcomment -%}
 
 {%- unless nav_number_pages == empty -%}
   {%- assign nav_number_pages = nav_number_pages | sort: "nav_order" -%}
@@ -65,18 +91,6 @@
   {%- 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 -%}
@@ -90,6 +104,6 @@
 {%- endunless -%}
 
 {%- assign sorted_pages = nav_number_pages
-    | concat: nav_string_pages
-    | concat: title_number_pages
-    | concat: title_string_pages -%}
+      | concat: nav_string_pages
+      | concat: title_number_pages
+      | concat: title_string_pages -%}

_layouts/default.html

@@ -12,7 +12,7 @@ layout: table_wrappers
   {% include components/sidebar.html %}
   <div class="main" id="top">
     {% include components/header.html %}
-    <div id="main-content-wrap" class="main-content-wrap">
+    <div class="main-content-wrap">
       {% include components/breadcrumbs.html %}
       <div id="main-content" class="main-content">
         <main>

_layouts/minimal.html

@@ -9,7 +9,7 @@ layout: table_wrappers
 <body>
   <a class="skip-to-main" href="#main-content">Skip to main content</a>
   {% include icons/icons.html %}
-  <div id="main-content-wrap" class="main-content-wrap" id="top">
+  <div class="main-content-wrap" id="top">
     {% include components/breadcrumbs.html %}
     <div id="main-content" class="main-content" role="main">
       {% if site.heading_anchors != false %}

_sass/base.scss

@@ -1,6 +1,10 @@
 // Base element style overrides
 // stylelint-disable selector-no-type, selector-max-type, selector-max-specificity, selector-max-id
 
+:root {
+  color-scheme: $color-scheme;
+}
+
 * {
   box-sizing: border-box;
 }
@@ -104,6 +108,6 @@ blockquote {
   // resets user-agent stylesheets for blockquotes
   margin-block-start: 0;
   margin-inline-start: 0;
-  padding-left: 15px;
+  padding-left: 1rem;
   border-left: 3px solid $border-color;
 }

_sass/buttons.scss

@@ -17,7 +17,9 @@
   background-color: $base-button-color;
   border-width: 0;
   border-radius: $border-radius;
-  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
+  box-shadow:
+    0 1px 2px rgba(0, 0, 0, 0.12),
+    0 3px 10px rgba(0, 0, 0, 0.08);
   appearance: none;
 
   &:focus {
@@ -87,7 +89,9 @@
   &:focus {
     text-decoration: none;
     outline: none;
-    box-shadow: inset 0 0 0 2px $grey-dk-100, 0 0 0 3px rgba(blue, 0.25);
+    box-shadow:
+      inset 0 0 0 2px $grey-dk-100,
+      0 0 0 3px rgba(blue, 0.25);
   }
 
   &:focus:hover,
@@ -101,7 +105,7 @@
 }
 
 .btn-purple {
-  @include btn-color($white, $purple-100);
+  @include btn-color($white, $purple-300);
 }
 
 .btn-blue {

_sass/color_schemes/dark.scss

@@ -1,3 +1,4 @@
+$color-scheme: dark;
 $body-background-color: $grey-dk-300;
 $body-heading-color: $grey-lt-000;
 $body-text-color: $grey-lt-300;

_sass/color_schemes/light.scss

@@ -1,3 +1,4 @@
+$color-scheme: light !default;
 $body-background-color: $white !default;
 $body-heading-color: $grey-dk-300 !default;
 $body-text-color: $grey-dk-100 !default;

_sass/labels.scss

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

_sass/print.scss

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

_sass/search.scss

@@ -23,7 +23,9 @@
   height: $sp-8;
   overflow: hidden;
   border-radius: $border-radius;
-  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
+  box-shadow:
+    0 1px 2px rgba(0, 0, 0, 0.12),
+    0 3px 10px rgba(0, 0, 0, 0.08);
   transition: height linear #{$transition-duration * 0.5};
 
   @include mq(md) {
@@ -42,7 +44,7 @@
   width: 100%;
   height: 100%;
   padding: $sp-2 $gutter-spacing-sm $sp-2 #{$gutter-spacing-sm + $sp-5};
-  font-size: 16px;
+  font-size: 1rem;
   color: $body-text-color;
   background-color: $search-background-color;
   border-top: 0;
@@ -53,7 +55,7 @@
 
   @include mq(md) {
     padding: $sp-2 $gutter-spacing-sm $sp-2 #{$gutter-spacing + $sp-5};
-    font-size: 14px;
+    font-size: 0.875rem;
     background-color: $body-background-color;
     transition: padding-left linear #{$transition-duration * 0.5};
   }
@@ -96,7 +98,9 @@
   background-color: $search-background-color;
   border-bottom-right-radius: $border-radius;
   border-bottom-left-radius: $border-radius;
-  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
+  box-shadow:
+    0 1px 2px rgba(0, 0, 0, 0.12),
+    0 3px 10px rgba(0, 0, 0, 0.08);
 
   @include mq(md) {
     top: 100%;
@@ -230,7 +234,9 @@
   background-color: $search-background-color;
   border: 1px solid rgba($link-color, 0.3);
   border-radius: #{$sp-9 * 0.5};
-  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
+  box-shadow:
+    0 1px 2px rgba(0, 0, 0, 0.12),
+    0 3px 10px rgba(0, 0, 0, 0.08);
   align-items: center;
   justify-content: center;
 }
@@ -244,7 +250,9 @@
   height: 0;
   background-color: rgba(0, 0, 0, 0.3);
   opacity: 0;
-  transition: opacity ease $transition-duration, width 0s $transition-duration,
+  transition:
+    opacity ease $transition-duration,
+    width 0s $transition-duration,
     height 0s $transition-duration;
 }
 
@@ -264,7 +272,9 @@
 
     @include mq(md) {
       width: $search-results-width;
-      box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
+      box-shadow:
+        0 1px 2px rgba(0, 0, 0, 0.12),
+        0 3px 10px rgba(0, 0, 0, 0.08);
     }
   }
 
@@ -290,7 +300,10 @@
     width: 100%;
     height: 100%;
     opacity: 1;
-    transition: opacity ease $transition-duration, width 0s, height 0s;
+    transition:
+      opacity ease $transition-duration,
+      width 0s,
+      height 0s;
   }
 
   @include mq(md) {

_sass/support/_functions.scss

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

_sass/support/_variables.scss

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

_sass/support/mixins/_buttons.scss

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

_sass/support/mixins/_layout.scss

@@ -12,7 +12,7 @@
   // If the key exists in the map
   @if $value {
     // Prints a media query based on the value
-    @media (min-width: rem($value)) {
+    @media (min-width: $value) {
       @content;
     }
   } @else {

_sass/support/support.scss

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

_sass/tables.scss

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

assets/js/just-the-docs.js

@@ -31,7 +31,10 @@ function initNav() {
     }
     if (target) {
       e.preventDefault();
-      target.ariaPressed = target.parentNode.classList.toggle('active');
+      const active = target.parentNode.classList.toggle('active');
+      const passive = target.parentNode.classList.toggle('passive');
+      if (active && passive) target.parentNode.classList.toggle('passive');
+      target.ariaPressed = active;
     }
   });
 
@@ -39,6 +42,8 @@ function initNav() {
   const mainHeader = document.getElementById('main-header');
   const menuButton = document.getElementById('menu-button');
   
+  disableHeadStyleSheet();
+
   jtd.addEvent(menuButton, 'click', function(e){
     e.preventDefault();
 
@@ -66,6 +71,16 @@ function initNav() {
   {%- endif %}
 }
 
+// The page-specific <style> in the <head> is needed only when JS is disabled.
+// Moreover, it incorrectly overrides dynamic stylesheets set by setTheme(theme). 
+// The page-specific stylesheet is assumed to have index 1 in the list of stylesheets.
+
+function disableHeadStyleSheet() {
+  if (document.styleSheets[1]) {
+    document.styleSheets[1].disabled = true;
+  }
+}
+
 {%- if site.search_enabled != false %}
 // Site search
 
@@ -461,15 +476,55 @@ jtd.setTheme = function(theme) {
   cssFile.setAttribute('href', '{{ "assets/css/just-the-docs-" | relative_url }}' + theme + '.css');
 }
 
+// Note: pathname can have a trailing slash on a local jekyll server
+// and not have the slash on GitHub Pages
+
+function navLink() {
+  var href = document.location.pathname;
+  if (href.endsWith('/') && href != '/') {
+    href = href.slice(0, -1);
+  }
+  return document.getElementById('site-nav').querySelector('a[href="' + href + '"], a[href="' + href + '/"]');
+}
+
 // 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 targetLink = navLink();
+  if (targetLink) {
     const rect = targetLink.getBoundingClientRect();
-    siteNav.scrollBy(0, rect.top - 3*rect.height);
+    document.getElementById('site-nav').scrollBy(0, rect.top - 3*rect.height);
+  }
+}
+
+// Find the nav-list-link that refers to the current page
+// then make it and all enclosing nav-list-item elements active,
+// and make all other folded collections passive
+
+function activateNav() {
+  var target = navLink();
+  if (target) {
+    target.classList.toggle('active', true);
+  }
+  while (target) {
+    while (target && !(target.classList && target.classList.contains('nav-list-item'))) {
+      target = target.parentNode;
+    }
+    if (target) {
+      target.classList.toggle('active', true);
+      target = target.parentNode;
+    }
+  }
+  const elements = document.getElementsByClassName("nav-category-list");
+  for (const element of elements) {
+    const item = element.children[0];
+    const active = item.classList.toggle('active');
+    if (active) {
+      item.classList.toggle('active', false);
+      item.classList.toggle('passive', true);
+    } else {
+      item.classList.toggle('active', true);
+    }
   }
 }
 
@@ -480,6 +535,7 @@ jtd.onReady(function(){
   {%- if site.search_enabled != false %}
   initSearch();
   {%- endif %}
+  activateNav();
   scrollNav();
 });
 

docs/configuration.md

@@ -295,6 +295,16 @@ just_the_docs:
 
 The navigation for all your normal pages (if any) is displayed before those in collections.
 
+<span>New (v0.4.0)</span>{: .label .label-green }
+Including `nav_fold: true` in a collection configuration *folds* that collection:
+an expander symbol appears next to the collection name,
+and clicking it displays/hides the links to the top-level pages of the collection.[^js-disabled]
+
+[^js-disabled]: <span>New (v0.6.0)</span>{: .label .label-green }
+    When JavaScript is disabled in the browser, all folded collections are automatically expanded,
+    since clicking expander symbols has no effect.
+    (In previous releases, navigation into folded collections required JavaScript to be enabled.)
+
 You can reference multiple collections.
 This creates categories in the navigation with the configured names.
 

docs/index-test.md

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

docs/search.md

@@ -15,7 +15,7 @@ nav_order: 7
 
 ---
 
-Just the Docs uses [lunr.js](http://lunrjs.com) to add a client-side search interface powered by a JSON index that Jekyll generates.
+Just the Docs uses [lunr.js](https://lunrjs.com) to add a client-side search interface powered by a JSON index that Jekyll generates.
 All search results are shown in an auto-complete style interface (there is no search results page).
 By default, all generated HTML pages are indexed using the following data points:
 

docs/ui-components/buttons.md

@@ -21,22 +21,22 @@ nav_order: 2
 ### Links that look like buttons
 
 <div class="code-example" markdown="1">
-[Link button](http://example.com/){: .btn }
+[Link button](https://just-the-docs.com){: .btn }
 
-[Link button](http://example.com/){: .btn .btn-purple }
-[Link button](http://example.com/){: .btn .btn-blue }
-[Link button](http://example.com/){: .btn .btn-green }
+[Link button](https://just-the-docs.com){: .btn .btn-purple }
+[Link button](https://just-the-docs.com){: .btn .btn-blue }
+[Link button](https://just-the-docs.com){: .btn .btn-green }
 
-[Link button](http://example.com/){: .btn .btn-outline }
+[Link button](https://just-the-docs.com){: .btn .btn-outline }
 </div>
 ```markdown
-[Link button](http://example.com/){: .btn }
+[Link button](https://just-the-docs.com){: .btn }
 
-[Link button](http://example.com/){: .btn .btn-purple }
-[Link button](http://example.com/){: .btn .btn-blue }
-[Link button](http://example.com/){: .btn .btn-green }
+[Link button](https://just-the-docs.com){: .btn .btn-purple }
+[Link button](https://just-the-docs.com){: .btn .btn-blue }
+[Link button](https://just-the-docs.com){: .btn .btn-green }
 
-[Link button](http://example.com/){: .btn .btn-outline }
+[Link button](https://just-the-docs.com){: .btn .btn-outline }
 ```
 
 ### Button element
@@ -60,20 +60,20 @@ Wrap the button in a container that uses the [font-size utility classes]({% link
 
 <div class="code-example" markdown="1">
 <span class="fs-6">
-[Big ass button](http://example.com/){: .btn }
+[Big ass button](https://just-the-docs.com){: .btn }
 </span>
 
 <span class="fs-3">
-[Tiny ass button](http://example.com/){: .btn }
+[Tiny ass button](https://just-the-docs.com){: .btn }
 </span>
 </div>
 ```markdown
 <span class="fs-8">
-[Link button](http://example.com/){: .btn }
+[Link button](https://just-the-docs.com){: .btn }
 </span>
 
 <span class="fs-3">
-[Tiny ass button](http://example.com/){: .btn }
+[Tiny ass button](https://just-the-docs.com){: .btn }
 </span>
 ```
 
@@ -82,16 +82,16 @@ Wrap the button in a container that uses the [font-size utility classes]({% link
 Use the [margin utility classes]({% link docs/utilities/layout.md %}#spacing) to add spacing between two buttons in the same block.
 
 <div class="code-example" markdown="1">
-[Button with space](http://example.com/){: .btn .btn-purple .mr-2 }
-[Button](http://example.com/){: .btn .btn-blue }
+[Button with space](https://just-the-docs.com){: .btn .btn-purple .mr-2 }
+[Button](https://just-the-docs.com){: .btn .btn-blue }
 
-[Button with more space](http://example.com/){: .btn .btn-green .mr-4 }
-[Button](http://example.com/){: .btn .btn-blue }
+[Button with more space](https://just-the-docs.com){: .btn .btn-green .mr-4 }
+[Button](https://just-the-docs.com){: .btn .btn-blue }
 </div>
 ```markdown
-[Button with space](http://example.com/){: .btn .btn-purple .mr-2 }
-[Button](http://example.com/){: .btn .btn-blue }
+[Button with space](https://just-the-docs.com){: .btn .btn-purple .mr-2 }
+[Button](https://just-the-docs.com){: .btn .btn-blue }
 
-[Button with more space](http://example.com/){: .btn .btn-green .mr-4 }
-[Button](http://example.com/){: .btn .btn-blue }
+[Button with more space](https://just-the-docs.com){: .btn .btn-green .mr-4 }
+[Button](https://just-the-docs.com){: .btn .btn-blue }
 ```

docs/ui-components/code.md

@@ -68,22 +68,22 @@ To demonstrate front end code, sometimes it's useful to show a rendered example
 
 <div class="code-example" markdown="1">
 
-[Link button](http://example.com/){: .btn }
+[Link button](https://just-the-docs.com){: .btn }
 
 </div>
 ```markdown
-[Link button](http://example.com/){: .btn }
+[Link button](https://just-the-docs.com){: .btn }
 ```
 
 </div>
 {% highlight markdown %}
 <div class="code-example" markdown="1">
 
-[Link button](http://example.com/){: .btn }
+[Link button](https://just-the-docs.com){: .btn }
 
 </div>
 ```markdown
-[Link button](http://example.com/){: .btn }
+[Link button](https://just-the-docs.com){: .btn }
 ```
 {% endhighlight %}
 
@@ -115,7 +115,7 @@ Additional configuration options are loaded through `_includes/mermaid_config.js
 
 This loads the default settings.
 
-The contents of this object should follow [mermaid's configuration API](https://mermaid-js.github.io/mermaid/#/./Setup?id=configuration). For example, to override the theme, change `_includes/mermaid_config.js` to:
+The contents of this object should follow [mermaid's configuration API](https://mermaid.js.org/config/configuration.html). For example, to override the theme, change `_includes/mermaid_config.js` to:
 
 ```js
 // _includes/mermaid_config.js
@@ -185,7 +185,7 @@ graph TD;
 ++++
 {% endhighlight %}
 
-Alternatively, community member [@flyx](https://.github.com/flyx) has contributed a Ruby extension that does not require extra markup. The extension is available [as a GitHub Gist](https://gist.github.com/flyx/9fff080cf4edc95d495bc661a002232c). Thank you to [@flyx](https://.github.com/flyx)!
+Alternatively, community member [@flyx](https://github.com/flyx) has contributed a Ruby extension that does not require extra markup. The extension is available [as a GitHub Gist](https://gist.github.com/flyx/9fff080cf4edc95d495bc661a002232c). Thank you to [@flyx](https://github.com/flyx)!
 
 The [asciidoctor-diagram](https://docs.asciidoctor.org/diagram-extension/latest/) extension which also supports mermaid is not recommended for use with Just the Docs, since it requires separate configuration e.g. for theming, and is known to not be trivial to set up.
 

docs/ui-components/line-nos.md

@@ -115,6 +115,9 @@ end
 {% include fix_linenos.html code=code %}
 {% assign code = nil %}
 
+{: .warning }
+The following generates **incorrect** and **invalid** HTML. It should not be used as a positive example; the improper layout (with the broken HTML tags) is intentional.
+
 ❌ With the compression options used for the theme docs, the following example illustrates
 the **incorrect** formatting arising from the incompatibility of HTML compression
 and the non-conforming HTML produced by Jekyll for line numbers:

docs/ui-components/typography.md

@@ -21,7 +21,7 @@ nav_order: 1
 By default, Just the Docs uses a native system font stack for sans-serif fonts:
 
 ```scss
-system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif
+system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Segoe UI Emoji"
 ```
 
 ABCDEFGHIJKLMNOPQRSTUVWXYZ
@@ -97,12 +97,12 @@ Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor
 <div class="code-example" markdown="1">
 Text can be **bold**, _italic_, or ~~strikethrough~~.
 
-[Link to another page](another-page).
+[Link to another page]({{site.baseurl}}/).
 </div>
 ```markdown
 Text can be **bold**, _italic_, or ~~strikethrough~~.
 
-[Link to another page](another-page).
+[Link to another page]({{site.baseurl}}/).
 ```
 
 ---

fixtures/Gemfile-jekyll-3.9

@@ -5,6 +5,8 @@ gem "jekyll", "~> 3.9"
 gem "jekyll-seo-tag", ">= 2.0"
 gem "rake", ">= 12.3.1"
 
+gem "jekyll-include-cache", group: :jekyll_plugins
+
 # required for Jekyll 3
 gem "webrick", "~> 1.7"
 gem "kramdown-parser-gfm", '~> 1.1'

fixtures/Gemfile-jekyll-4.3

@@ -5,5 +5,7 @@ gem "jekyll", "~> 4.3"
 gem "jekyll-seo-tag", ">= 2.0"
 gem "rake", ">= 12.3.1"
 
+gem "jekyll-include-cache", group: :jekyll_plugins
+
 # docs-only
 gem "jekyll-github-metadata", ">= 2.15"

index.md

@@ -49,7 +49,7 @@ See the theme [README][Just the Docs README] for how to use the theme as a gem w
 
 ## About the project
 
-Just the Docs is © 2017-{{ "now" | date: "%Y" }} by [Patrick Marsceill](http://patrickmarsceill.com).
+Just the Docs is © 2017-{{ "now" | date: "%Y" }} by [Patrick Marsceill](https://patrickmarsceill.com).
 
 ### License
 

just-the-docs.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name          = "just-the-docs"
-  spec.version       = "0.5.2"
+  spec.version       = "0.6.1"
   spec.authors       = ["Patrick Marsceill", "Matthew Wang"]
   spec.email         = ["patrick.marsceill@gmail.com", "matt@matthewwang.me"]
 
@@ -22,5 +22,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", ">= 2.3.5"
   spec.add_runtime_dependency "jekyll", ">= 3.8.5"
   spec.add_runtime_dependency "jekyll-seo-tag", ">= 2.0"
+  spec.add_runtime_dependency "jekyll-include-cache"
   spec.add_runtime_dependency "rake", ">= 12.3.1"
 end

package.json

@@ -1,22 +1,43 @@
 {
   "name": "just-the-docs",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "description": "A modern Jekyll theme for documentation",
-  "repository": "just-the-docs/just-the-docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/just-the-docs/just-the-docs.git"
+  },
   "license": "MIT",
-  "bugs": "https://github.com/just-the-docs/just-the-docs/issues",
+  "bugs": {
+    "url": "https://github.com/just-the-docs/just-the-docs/issues"
+  },
   "devDependencies": {
+    "@babel/preset-env": "^7.21.4",
+    "@babel/preset-typescript": "^7.21.4",
+    "@storybook/addon-essentials": "^7.0.7",
+    "@storybook/addon-interactions": "^7.0.7",
+    "@storybook/addon-links": "^7.0.7",
+    "@storybook/blocks": "^7.0.7",
+    "@storybook/html": "^7.0.7",
+    "@storybook/html-webpack5": "^7.0.7",
+    "@storybook/testing-library": "^0.0.14-next.2",
+    "chromatic": "^6.17.3",
     "npm-run-all": "^4.1.5",
-    "prettier": "^2.8.8",
-    "stylelint": "^15.7.0",
-    "stylelint-config-standard-scss": "^9.0.0"
+    "prettier": "^3.0.3",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "storybook": "^7.0.7",
+    "stylelint": "^15.10.3",
+    "stylelint-config-standard-scss": "^10.0.0"
   },
   "scripts": {
     "lint": "npm-run-all --parallel --continue-on-error lint:*",
     "lint:css": "stylelint '**/*.scss'",
     "lint:formatting": "prettier --check '**/*.{scss,js,json}'",
     "format": "prettier --write '**/*.{scss,js,json}'",
-    "test": "npm run lint"
+    "test": "npm run lint",
+    "storybook": "bundle exec jekyll build && storybook dev -p 6006",
+    "build-storybook": "bundle exec jekyll build && storybook build",
+    "chromatic": "npx chromatic --project-token=9355f489c51b -d storybook-static"
   },
   "stylelint": {
     "ignoreFiles": [
@@ -43,5 +64,7 @@
     "singleQuote": false,
     "tabWidth": 2,
     "trailingComma": "es5"
-  }
+  },
+  "homepage": "https://just-the-docs.com",
+  "_id": "just-the-docs@0.5.0"
 }

stories/Introduction.mdx

@@ -0,0 +1,7 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Example/Introduction" />
+
+# Storybook for Just the Docs
+
+A WIP [Storybook](https://storybook.js.org/) for Just the Docs.

stories/ui-components/Button.js

@@ -0,0 +1,11 @@
+import "../../_site/assets/css/just-the-docs-default.css"
+
+export const createButton = ({ variant = "default", label, size = "4" }) => {
+  const btn = document.createElement("button")
+  btn.type = "button"
+  btn.innerText = label
+
+  btn.className = ["btn", `btn-${variant}`, `fs-${size}`].join(" ")
+
+  return btn
+}

stories/ui-components/Button.stories.js

@@ -0,0 +1,68 @@
+import { createButton } from "./Button"
+
+export default {
+  title: "UI Components/Button",
+  tags: ["autodocs"],
+  render: ({ label, ...args }) => {
+    return createButton({ label, ...args })
+  },
+  argTypes: {
+    label: { control: "text" },
+    size: {
+      control: { type: "select" },
+      options: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+    },
+    variant: {
+      control: { type: "select" },
+      options: ["default", "primary", "purple", "blue", "green", "outline"],
+    },
+  },
+}
+
+export const Default = {
+  args: {
+    variant: "default",
+    label: "Button",
+    size: 4,
+  },
+}
+
+export const Primary = {
+  args: {
+    variant: "primary",
+    label: "Button",
+    size: 4,
+  },
+}
+
+export const Purple = {
+  args: {
+    variant: "purple",
+    label: "Button",
+    size: 4,
+  },
+}
+
+export const Blue = {
+  args: {
+    variant: "blue",
+    label: "Button",
+    size: 4,
+  },
+}
+
+export const Green = {
+  args: {
+    variant: "green",
+    label: "Button",
+    size: 4,
+  },
+}
+
+export const Outline = {
+  args: {
+    variant: "outline",
+    label: "Button",
+    size: 4,
+  },
+}

stories/ui-components/Label.js

@@ -0,0 +1,10 @@
+import "../../_site/assets/css/just-the-docs-default.css"
+
+export const createLabel = ({ variant = "default", label, size = "4" }) => {
+  const btn = document.createElement("span")
+  btn.innerText = label
+
+  btn.className = ["label", `label-${variant}`, `fs-${size}`].join(" ")
+
+  return btn
+}

stories/ui-components/Label.stories.js

@@ -0,0 +1,68 @@
+import { createLabel } from "./Label"
+
+export default {
+  title: "UI Components/Label",
+  tags: ["autodocs"],
+  render: ({ label, ...args }) => {
+    return createLabel({ label, ...args })
+  },
+  argTypes: {
+    label: { control: "text" },
+    size: {
+      control: { type: "select" },
+      options: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+    },
+    variant: {
+      control: { type: "select" },
+      options: ["default", "purple", "blue", "green", "red", "yellow"],
+    },
+  },
+}
+
+export const Default = {
+  args: {
+    variant: "default",
+    label: "Label",
+    size: 4,
+  },
+}
+
+export const Purple = {
+  args: {
+    variant: "purple",
+    label: "Label",
+    size: 4,
+  },
+}
+
+export const Blue = {
+  args: {
+    variant: "blue",
+    label: "Label",
+    size: 4,
+  },
+}
+
+export const Green = {
+  args: {
+    variant: "green",
+    label: "Label",
+    size: 4,
+  },
+}
+
+export const Red = {
+  args: {
+    variant: "red",
+    label: "Label",
+    size: 4,
+  },
+}
+
+export const Yellow = {
+  args: {
+    variant: "yellow",
+    label: "Label",
+    size: 4,
+  },
+}