Prep for v0.4.2

In the conversation for #1166, I noticed that the import order for `setup.scss` disagrees with our docs.

> In particular, the [docs for `setup.scss`](https://just-the-docs.com/docs/customization/#override-and-define-new-variables) reads:
> 
> > To define new SCSS variables, functions, or override existing theme variables, place SCSS code in `_sass/custom/setup.scss`
> 
> But, this is not true - `setup.scss` is loaded *before* all of the themes, so it doesn't override existing theme variables. 
> 
> In my opinion, the solution here is to move `setup.scss` after all the `color_scheme` SCSS. This way, `setup.scss` properly allows theme overrides. In addition, users who previously defined variables in `setup.scss` and then used them in their custom color schemes can shift those declarations to be entirely in the theme code.

This is a one-liner that fixes the behaviour to be in-line with what our docs state.

.github/workflows/ci.yml

@@ -5,23 +5,25 @@ on:
   pull_request:
     branches:
       - main
-      - 'v**'
 
 name: CI
 
 jobs:
   jekyll-build:
-    name: Build Jekyll site
+    name: Build (jekyll gem)
-    runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
         jekyll-version: [3.9, 4.3]
+        os: [ ubuntu-latest, macos-latest, windows-latest ]
+        ruby-version: [2.7, 3.1]
+    runs-on: ${{ matrix.os }}
     steps:
     - uses: actions/checkout@v3
-    - name: Setup Ruby
+    - name: Setup Ruby ${{ matrix.ruby-version }}
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.1' # Not needed with a .ruby-version file
+        ruby-version: ${{ matrix.ruby-version }}
         bundler-cache: false
     - name: Bundle Install
       run: bundle install
@@ -32,6 +34,21 @@ jobs:
     - name: Build Site
       run: bundle exec jekyll build
 
+  github-pages-build:
+    name: Build (github-pages gem)
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Setup Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.1'
+        bundler-cache: false
+    - name: Bundle Install
+      run: BUNDLE_GEMFILE=fixtures/Gemfile-github-pages bundle install
+    - name: Build Site
+      run: BUNDLE_GEMFILE=fixtures/Gemfile-github-pages bundle exec jekyll build
+
   assets:
     name: Test CSS and JS
     runs-on: ubuntu-latest

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

.prettierignore

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

.prettierrc

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

.stylelintrc.json

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

CHANGELOG.md

@@ -16,11 +16,450 @@ The project underwent a major maintenance shift in March 2022.
 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.rc4` and `v0.3.3`!
+This website includes docs for some new features that are not available in `v0.4.2`!
 
-Changes to `main` that are *not* in the latest pre-release:
+Code changes to `main` that are *not* in the latest release:
 
-- n/a
+- N/A
+
+Docs changes in `main` that are *not* in the latest release:
+
+- N/A
+
+## Release v0.4.2
+
+Hello! We're back again with another small release. Like `v0.4.1`, this release is a [semver patch](https://semver.org/): it only includes bugfixes, and is fully backwards-compatible.
+
+The big highlight of this theme is fixing our light scheme code highlighting contrast issues; this was one of our most-requested features! This change is fully backwards-compatible; users can [opt-in to our old highlighting theme](https://just-the-docs.github.io/just-the-docs/docs/customization/#deprecated-legacy_light) by using `legacy_light` instead of `light`.
+
+As always, we'd love your feedback. [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) for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs!
+
+### Using Release `v0.4.2`
+
+Users who have not pinned the theme version will be **automatically upgraded to `v0.4.2` 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.4.2
+```
+
+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.2"
+```
+
+To use and pin a previous version of the theme, replace the `0.4.2` with the desired release tag.
+
+### Bugfixes
+
+- Fixed: light scheme code highlighting contrast issues; updated to use Atom's One Light colors, consolidate theme variables by [@mattxwang] in [#1166]
+- Fixed: duplicate import of `color_schemes` by [@mattxwang] in [#1173]
+- Fixed: import order for `setup.scss` by [@mattxwang] in [#1184]
+- Removed: unused dark syntax themes by [@mattxwang] in [#1192]
+
+### Documentation
+
+- Added: docs for using mermaid with AsciiDoc by [@flyx] in [#1182]
+
+**Full Changelog**: [https://github.com/just-the-docs/just-the-docs/compare/v0.4.1...v0.4.2](https://github.com/just-the-docs/just-the-docs/compare/v0.4.1...v0.4.2)
+
+[#1166]: https://github.com/just-the-docs/just-the-docs/pull/1166
+[#1173]: https://github.com/just-the-docs/just-the-docs/pull/1173
+[#1182]: https://github.com/just-the-docs/just-the-docs/pull/1182
+[#1184]: https://github.com/just-the-docs/just-the-docs/pull/1184
+[#1192]: https://github.com/just-the-docs/just-the-docs/pull/1192
+
+## Release v0.4.1
+
+Hello! We hope you've been enjoying the new `v0.4.0`; we appreciate all the feedback we've gotten already! As promised, future releases will be small with simple steps to upgrade. This is one of them! `v0.4.1` is a [semver patch](https://semver.org/): it only includes bugfixes, and is fully backwards-compatible.
+
+As always, we'd love your feedback. [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) for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs!
+
+### Using Release `v0.4.1`
+
+Users who have not pinned the theme version will be **automatically upgraded to `v0.4.1` 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.4.1
+```
+
+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.1"
+```
+
+To use and pin a previous version of the theme, replace the `0.4.1` with the desired release tag.
+
+### Bugfixes
+
+- Fixed: allow later versions of `bundler` by [@mattxwang] in [#1165]
+- Fixed: AsciiDoc code block styling by [@flyx] in [#1168]
+- Fixed: main content negative margin for viewports in `[$md, $nav-width + $content-width]` by [@Dima-369] in [#1177]
+- Removed: unused `OneDarkJekyll` files by [@mattxwang] in [#1167]
+
+### Documentation
+
+- Fixed: re-add `jekyll-github-metadata` to docs site by [@mattxwang] in [#1108]
+
+### New Contributors
+
+- [@flyx] made their first contribution in [#1168]
+- [@Dima-369] made their first contribution in [#1177]
+
+[#1108]: https://github.com/just-the-docs/just-the-docs/pull/1108
+[#1165]: https://github.com/just-the-docs/just-the-docs/pull/1165
+[#1167]: https://github.com/just-the-docs/just-the-docs/pull/1167
+[#1168]: https://github.com/just-the-docs/just-the-docs/pull/1168
+[#1177]: https://github.com/just-the-docs/just-the-docs/pull/1177
+
+[@flyx]: https://github.com/flyx
+[@Dima-369]: https://github.com/Dima-369
+
+**Full Changelog**: [https://github.com/just-the-docs/just-the-docs/compare/v0.4.0...v0.4.1](https://github.com/just-the-docs/just-the-docs/compare/v0.4.0...v0.4.1)
+
+## Release v0.4.0
+
+We're so excited to release Just the Docs `v0.4.0`. This release has been almost a year in the making - after our new maintenance team has taken over the project, we've added two years of backlogged features and bugfixes to modernize the theme. This CHANGELOG will summarize some of the key changes, discuss migrations strategies, and outline broad future plans for this theme.
+
+### Brief Overview - Highlighted Changes
+
+`v0.4.0` contains many new features and bugfixes. We enumerate all of them in further sections in this changelog; however, we'd like to call out some of the most-requested changes:
+
+- better support for dark theme: dark highlighting, search input color
+- [callouts](https://just-the-docs.github.io/just-the-docs/docs/ui-components/callouts/), a new design component to highlight content
+- [configuring mermaid.js](https://just-the-docs.github.io/just-the-docs/docs/ui-components/code/#mermaid-diagram-code-blocks), a markdown-native diagram visualization library
+- [copy code button](https://just-the-docs.github.io/just-the-docs/docs/ui-components/code/#copy-button) for code snippets
+- [external navigation links](https://just-the-docs.github.io/just-the-docs/docs/navigation-structure/#external-navigation-links)
+- major improvements to nav generation efficiency and robustness
+- minor improvements to built-in accessibility (SVG icons, nav titles, skip to main content)
+- [modularized site components](https://just-the-docs.github.io/just-the-docs/docs/customization/#custom-layouts-and-includes) (advanced feature)
+- [new custom includes](https://just-the-docs.github.io/just-the-docs/docs/customization/#override-includes): table of contents heading, navigation panel footer, search placeholder, lunr search indices
+- bugfixes involving WEBrick and Ruby 3, Liquid processing in CSS comments, nested task lists, relative URLs, scroll navigation, corrupted search data from rake, breadcrumbs, and more!
+- more documentation for [custom includes](https://just-the-docs.github.io/just-the-docs/docs/customization/#override-includes), this changelog, and the [migration guide](https://just-the-docs.github.io/just-the-docs/MIGRATION/)
+
+*After usage instructions and the roadmap, we enumerate all changes from `v0.3.3`.*
+
+### Using Release `v0.4.0`
+
+Unlike pre-releases, `v0.4.0` is a new semver minor release for the theme. That means that users who have not pinned the theme version will be **automatically upgraded to `v0.4.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.4.0
+```
+
+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"
+```
+
+If you would prefer to not upgrade, you can enforce that explicitly:
+
+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
+```
+
+### Migration Guide and Strategies
+
+We've developed a new [migration guide](https://just-the-docs.github.io/just-the-docs/MIGRATION/) for users to migrate from version `v0.3.3` to `v0.4.0`. It outlines major changes in project maintenance (e.g. new repository link, team) as well as breaking changes that may break your site (and potential solutions). We suggest that all users refer to the guide before manually upgrading their site.
+
+**For the vast majority of users, we do not anticipate that this will be a breaking change.** The major touch points are surrounding new includes, navigation (ordering, pages, and collections), the favicon, and a shift to relative URLs. However, users who heavily customize the theme (primarily by overriding includes) will likely have to make minor changes.
+
+Given the length of features added in this release, users may want to incrementally upgrade through the pre-releases. To follow this approach, read this changelog from `v0.4.0.rc1` to `v0.4.0.rc5`; this breaks down the release into small chunks, each of which should be easier to upgrade. `v0.4.0.rc5` is identical to this release.
+
+For support with migrating to `v0.4.0`, [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!
+
+### Roadmap (What's Next?)
+
+Moving forward, we plan to release more frequently with smaller, bite-sized changes. This should make it easier for users to upgrade in the future!
+
+Broadly, many features are still on the radar. We anticipate the rest of `v0.4.x` to be bugfixes surrounding this new release.
+
+For version `v0.5`, our roadmap includes:
+
+- a theme toggle (light/dark mode), with automatic theme switching based on browser preferences
+- better GDPR compliance for analytics
+- multi-level/recursive navigation (unlimited hierarchy of child pages)
+
+In future versions, we also plan on:
+
+- adding better dark theme defaults
+- adding better internationalization support
+- exploring offline PDF generation
+- improving accessibility within the theme
+- improving search functionality
+- refactoring and improving the robustness of our codebase
+
+Have ideas for what's next, or want to get involved? [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! We're looking for more contributors and maintainers to help us develop the theme.
+
+### New 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]
+- 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]
+- Added: styling for `<blockquote>` by [@mattxwang] in [#965]
+- Added: custom include for TOC heading by [@pdmosses] in [#980]
+- Added: experimental nav optimization for simple cases by [@pdmosses] in [#992]
+- 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]
+- 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
+
+- 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]
+- Fixed: exclude `vendor/` in Jekyll config by [@manuelhenke] in [#941]
+- Fixed: improve build time of navigation panel by [@pdmosses] in [#956]
+- 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]
+- 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]
+- 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]
+
+### 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]
+- Deleted: unused script directory by [@mattxwang] in [#937]
+- Vendor: update `jekyll-anchor-headings`, `lunr.js` by [@mattxwang] in [#1071]
+
+### 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]
+- Added: docs load mermaid.js by default by [@mattxwang] in [#935]
+- Added: warning about mandatory `_`-prefix for collections by [@max06] in [#1091]
+- Added:  migration guide by [@pdmosses] in [#1059]
+- Added: label new features introduced in `v0.4` by [@mattxwang] in [#1138]
+- 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]
+- 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]
+- Fixed: typo in changelog links [@koppor] in [#1000]
+- Fixed: two bugs in "Customization" (custom favicon, new annotation) by [@mattxwang] in [#1090]
+- Fixed: "View Typography Utilities" link by [@agabrys] in [#1130]
+- Fixed: broken relative page links by [@mattxwang] in [#1106]
+- Fixed: clarify steps to add custom `lunr` index code by [@diablodale] in [#1139]
+- Updated: homepage (focus: new features, conciseness, deduplication) by [@pdmosses] in [#1018]
+- Updated: README (focus: new features, conciseness, deduplication) by [@pdmosses] in [#1019]
+- Updated: `README` demo video by [@codewithfan] in [#1097]
+
+### 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]
+- [@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]
+- [@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]
+- [@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]
+
+## 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
 
@@ -53,14 +492,14 @@ 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
+```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
+```ruby
 gem "just-the-docs", "0.3.3"
 ```
 2. freeze the `remote_theme`, like so
@@ -174,14 +613,14 @@ 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
+```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
+```ruby
 gem "just-the-docs", "0.3.3"
 ```
 2. freeze the `remote_theme`, like so
@@ -250,14 +689,14 @@ 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
+```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
+```ruby
 gem "just-the-docs", "0.3.3"
 ```
 2. freeze the `remote_theme`, like so
@@ -338,7 +777,7 @@ 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
+```ruby
 gem "just-the-docs", "0.4.0.rc1"
 ```
 
@@ -349,7 +788,7 @@ If you're not ready to make the switch, that's alright! If your version of just-
 If you have not pinned your theme version, you should either:
 
 1. pin your gem version in your `Gemfile`, like so
-```Ruby
+```ruby
 gem "just-the-docs", "0.3.3"
 ```
 2. freeze the `remote_theme`, like so

Gemfile

@@ -1,4 +1,6 @@
 source "https://rubygems.org"
 gemspec
 
+gem "jekyll-github-metadata", ">= 2.15"
+
 gem "webrick", "~> 1.7"

MIGRATION.md

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

@@ -9,7 +9,9 @@
     <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
 

_config.yml

@@ -17,6 +17,7 @@ title: Just the Docs
 description: A Jekyll theme for documentation
 baseurl: "/just-the-docs" # the subpath of your site, e.g. /blog
 url: "https://just-the-docs.github.io" # the base hostname & protocol for your site, e.g. http://example.com
+repository: just-the-docs/just-the-docs # for github-metadata
 
 permalink: pretty
 
@@ -42,6 +43,8 @@ exclude:
    - package-lock.json
    - Rakefile
    - README.md
+ # theme test code
+   - fixtures/
 
 # Set a path/url to a logo that will be displayed instead of the title
 #logo: "/assets/images/just-the-docs.png"
@@ -76,7 +79,7 @@ search:
 # For copy button on code
 enable_copy_code_button: true
 
-# To disable support for mermaid diagrams (https://mermaid-js.github.io/mermaid/),
+# 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:
@@ -85,6 +88,8 @@ 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
@@ -157,6 +162,7 @@ callouts:
 
 plugins:
   - jekyll-seo-tag
+  - jekyll-github-metadata
 
 kramdown:
   syntax_highlighter_opts:

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

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

_includes/head.html

@@ -23,8 +23,12 @@
   {% endif %}
 
   {% 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>
 

_includes/icons/code_copy.html

@@ -1,4 +1,4 @@
-<!-- Feather. MIT License: https://github.com/twbs/icons/blob/main/LICENSE.md -->
+<!-- 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">

_includes/nav.html

@@ -174,7 +174,7 @@
           {%- if node.child_nav_order == 'desc' or node.child_nav_order == 'reversed' -%}
             {%- assign children_list = children_list | reverse -%}
           {%- endif -%}
-          <ul class="nav-list ">
+          <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 %}">

_sass/code.scss

@@ -50,6 +50,11 @@ a:visited code {
 // Kramdown line_numbers = true: fences have a wider gutter than with Liquid?
 
 // ```[LANG]...```
+// or in AsciiDoc:
+//
+//     ----
+//     ...
+//     ----
 
 // the code may appear with 3 different types:
 // container \ case:  default case,          code with line number,   code with html rendering
@@ -59,6 +64,7 @@ a:visited code {
 // last level:        code,                  pre,                     code (optionality)
 // highlighter level: span,                  span,                    span
 // the spacing are only in the second level for case 1, 3 and in the third level for case 2
+// in AsciiDoc, there is a parent container that contains optionally a title and the content.
 
 // select top level container
 div.highlighter-rouge,
@@ -111,17 +117,17 @@ figure.highlight {
 }
 
 // setting the spacing and scrollbar on the second level for the first case
-// remove all space on the second and thirt level
+// remove all space on the second and third level
-div.highlighter-rouge,
+// this is a mixin to accommodate for the slightly different structures generated via Markdown vs AsciiDoc
-div.listingblock {
+@mixin scroll-and-spacing($code-div, $pre-select) {
-  div.highlight {
+  #{$code-div} {
     overflow-x: auto;
     padding: $sp-3;
     margin: 0;
     border: 0;
   }
 
-  pre.highlight,
+  #{$pre-select},
   code {
     padding: 0;
     margin: 0;
@@ -129,6 +135,19 @@ div.listingblock {
   }
 }
 
+// for Markdown
+div.highlighter-rouge {
+  @include scroll-and-spacing("div.highlight", "pre.highlight");
+}
+
+// for AsciiDoc. we also need to fix the margins for its parent container.
+div.listingblock {
+  @include scroll-and-spacing("div.content", "div.content > pre");
+
+  margin-top: 0;
+  margin-bottom: $sp-3;
+}
+
 // {% highlight LANG %}...{% endhighlight %},
 // {% highlight LANG linenos %}...{% endhighlight %}:
 
@@ -207,4 +226,21 @@ code.language-mermaid {
   border: 0;
 }
 
+// Override OneDarkJekyll Colors for Code Blocks
+.highlight,
+pre.highlight {
+  background: $code-background-color; // Code Background
+  // For Backwards Compatibility Before $code-linenumber-color was added
+  @if variable-exists(code-linenumber-color) {
+    color: $code-linenumber-color; // Code Line Numbers
+  } @else {
+    color: $body-text-color; // Code Line Numbers
+  }
+}
+
+// Override OneDarkJekyll Colors for Code Blocks
+.highlight pre {
+  background: $code-background-color; // Code Background
+}
+
 // {% endraw %}

_sass/color_schemes/dark.scss

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

_sass/color_schemes/legacy_light.scss

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

_sass/color_schemes/light.scss

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

_sass/custom/custom.scss

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

_sass/custom/setup.scss

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

_sass/layout.scss

@@ -29,9 +29,13 @@
   }
 
   @include mq(lg) {
-    margin-left: calc(
+    // stylelint-disable function-name-case
-      (100% - #{$nav-width + $content-width}) / 2 + #{$nav-width}
+    // disable for Max(), we want to use the CSS max() function
+    margin-left: Max(
+      #{$nav-width},
+      calc((100% - #{$nav-width + $content-width}) / 2 + #{$nav-width})
     );
+    // stylelint-enable function-name-case
   }
 }
 

_sass/search.scss

@@ -123,7 +123,7 @@
 
 .search-result {
   display: block;
-  padding-top: $sp-1 $sp-3;
+  padding: $sp-1 $sp-3;
 
   &:hover,
   &.active {

_sass/support/_variables.scss

@@ -56,19 +56,6 @@ $red-000: #f77e7e !default;
 $red-100: #f96e65 !default;
 $red-200: #e94c4c !default;
 $red-300: #dd2e2e !default;
-$body-background-color: $white !default;
-$sidebar-color: $grey-lt-000 !default;
-$search-background-color: $white !default;
-$table-background-color: $white !default;
-$code-background-color: $grey-lt-000 !default;
-$feedback-color: darken($sidebar-color, 3%) !default;
-$body-text-color: $grey-dk-100 !default;
-$body-heading-color: $grey-dk-300 !default;
-$search-result-preview-color: $grey-dk-000 !default;
-$nav-child-link-color: $grey-dk-100 !default;
-$link-color: $purple-000 !default;
-$btn-primary-color: $purple-100 !default;
-$base-button-color: #f7f7f7 !default;
 
 // Spacing
 

_sass/support/mixins/_layout.scss

@@ -16,8 +16,7 @@
       @content;
     }
   } @else {
-    @warn "No value could be retrieved from `#{$media-query}`. "
+    @warn "No value could be retrieved from `#{$media-query}`. Please make sure it is defined in `$media-queries` map.";
-      + "Please make sure it is defined in `$media-queries` map.";
   }
 }
 

_sass/typography.scss

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

_sass/vendor/OneDarkJekyll/README.md

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

_sass/vendor/OneDarkJekyll/colors.less

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

_sass/vendor/OneDarkJekyll/syntax-firewatch.scss

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

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

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

_sass/vendor/OneDarkJekyll/syntax-variables.less

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

_sass/vendor/OneDarkJekyll/syntax.less

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

_sass/vendor/OneDarkJekyll/syntax.scss

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

_sass/vendor/OneLightJekyll/LICENSE

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

_sass/vendor/OneLightJekyll/syntax.scss

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

assets/js/just-the-docs.js

@@ -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,
@@ -487,7 +488,7 @@ jtd.onReady(function(){
 
 jtd.onReady(function(){
 
-  var codeBlocks = document.querySelectorAll('div.highlighter-rouge, div.listingblock, figure.highlight');
+  var codeBlocks = document.querySelectorAll('div.highlighter-rouge, div.listingblock > div.content, figure.highlight');
 
   // note: the SVG svg-copied and svg-copy is only loaded as a Jekyll include if site.enable_copy_code_button is true; see _includes/icons/icons.html
   var svgCopied =  '<svg viewBox="0 0 24 24" class="copy-icon"><use xlink:href="#svg-copied"></use></svg>';
@@ -503,7 +504,7 @@ jtd.onReady(function(){
 
     copyButton.addEventListener('click', function () {
       if(timeout === null) {
-        var code = codeBlock.querySelector('pre:not(.lineno)').innerText;
+        var code = (codeBlock.querySelector('pre:not(.lineno, .highlight)') || codeBlock.querySelector('code')).innerText;
         window.navigator.clipboard.writeText(code);
 
         copyButton.innerHTML = svgCopied;

assets/js/zzzz-search-data.json

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

docs/configuration.md

@@ -69,6 +69,10 @@ search:
 ```
 
 ## 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`:
 
@@ -79,7 +83,9 @@ mermaid:
   version: "9.1.3"
 ```
 
-See [the Code documentation]({{ site.baseurl }}{% link docs/ui-components/code.md %}#mermaid-diagram-code-blocks) for more configuration options and information.
+Provide a `path` instead of a `version` key to load the mermaid library from a local file.
+
+See [the Code documentation]({% link docs/ui-components/code.md %}#mermaid-diagram-code-blocks) for more configuration options and information.
 
 ## Aux links
 
@@ -104,9 +110,13 @@ heading_anchors: true
 ```
 
 ## External navigation links
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }
 
 External links can be added to the navigation through the `nav_external_links` option.
-See [Navigation Structure]({{ site.baseurl }}{% link docs/navigation-structure.md %}#external-navigation-links) for more details.
+See [Navigation Structure]({% link docs/navigation-structure.md %}#external-navigation-links) for more details.
 
 ## Footer content
 
@@ -162,9 +172,13 @@ jtd.addEvent(toggleDarkMode, 'click', function(){
 });
 </script>
 
-See [Customization]({{ site.baseurl }}{% link docs/customization.md %}) for more information.
+See [Customization]({% link docs/customization.md %}) for more information.
 
 ## Callouts
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }
 
 To use this feature, you need to configure a `color` and (optionally) `title` for each kind of callout you want to use, e.g.:
 
@@ -185,7 +199,7 @@ A paragraph...
 [^dark]:
     If you use the `dark` color scheme, this callout uses `$red-300` for the background, and `$red-000` for the title.
 
-The colors `grey-lt`, `grey-dk`, `purple`, `blue`, `green`, `yellow`, and `red` are predefined; to use a custom color, you need to define its `000` and `300` levels in your SCSS files. For example, to use `pink`, add the following to your `_sass/custom/custom.scss` file:
+The colors `grey-lt`, `grey-dk`, `purple`, `blue`, `green`, `yellow`, and `red` are predefined; to use a custom color, you need to define its `000` and `300` levels in your SCSS files. For example, to use `pink`, add the following to your `_sass/custom/setup.scss` file:
 
 ```scss
 $pink-000: #f77ef1;
@@ -215,7 +229,7 @@ The value of `callouts_level` is either `quiet` or `loud`;
 The default level is `quiet` when using the `light` or custom color schemes,
 and `loud` when using the `dark color scheme.`
 
-See [Callouts]({{ site.baseurl }}{% link docs/ui-components/callouts.md %}) for more information.
+See [Callouts]({% link docs/ui-components/callouts.md %}) for more information.
 
 ## Google Analytics
 
@@ -231,6 +245,12 @@ 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
@@ -267,7 +287,7 @@ just_the_docs:
       # nav_exclude: true
       # Fold the collection in the navigation
       # Supports true or false (default)
-      # nav_fold: true
+      # nav_fold: true  # note: this option is new in v0.4
       # Exclude the collection from the search
       # Supports true or false (default)
       # search_exclude: true

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.
 
@@ -49,6 +45,15 @@ jtd.addEvent(toggleDarkMode, 'click', function(){
 });
 </script>
 
+### deprecated: `legacy_light`
+{: .d-inline-block .no_toc }
+
+New (v0.4.2)
+{: .label .label-green }
+
+
+In Just the Docs version `0.4.2`, we changed the default syntax highlighting theme for the `light` color scheme to have higher contrast. Users who are want to use the old highlighting need to explicitly opt-in with the deprecated `legacy_light` color scheme. In a future major release of Just the Docs, we will remove this color scheme.
+
 ## Custom schemes
 
 ### Define a custom scheme
@@ -111,9 +116,29 @@ This allows you to switch the scheme via the following javascript.
 jtd.setTheme("foo")
 ```
 
+## Override and define new variables
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }
+
+To define new SCSS variables, 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.
@@ -146,10 +171,14 @@ To do this, create an `_includes` directory and make a copy of the specific file
 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]({{ site.baseurl }}{% link docs/navigation-structure.md %}#auto-generating-table-of-contents) after the page's content.
+If the page has any child pages, and `has_toc` is not set to `false`, this content appears as a heading above the [auto-generating list of child pages]({% link docs/navigation-structure.md %}#auto-generating-table-of-contents) after the page's content.
 
 #### Example
 {: .no_toc }
@@ -165,7 +194,7 @@ The (optional) `text-delta` class makes the heading appear as **Contents**{:.tex
 
 `_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]({{ site.baseurl }}{% link docs/configuration.md %}#footer-content).
+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
 
@@ -182,12 +211,20 @@ The `<head>` tag automatically includes a link to an existing favicon if you set
 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`
 

docs/navigation-structure.md

@@ -145,6 +145,10 @@ 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:
 
@@ -235,7 +239,7 @@ Currently, the navigation structure is limited to 3 levels: grandchild pages can
 
 ## 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 }
@@ -250,8 +254,12 @@ aux_links:
 ---
 
 ## External Navigation Links
+{: .d-inline-block }
 
-To add external links to the navigation, add them to the `nav_external_links` [configuration]({{ site.baseurl }}{% link docs/configuration.md %}) option in your site's `_config.yml` file.
+New (v0.4.0)
+{: .label .label-green }
+
+To add external links to the navigation, add them to the `nav_external_links` [configuration]({% link docs/configuration.md %}) option in your site's `_config.yml` file.
 External links will appear in the navigation after the links to ordinary pages, but before any collections.
 
 #### Example

docs/search.md

@@ -96,7 +96,7 @@ search.button: true
 
 ## Hiding pages from search
 
-Sometimes you might have a page that you don't want to be indexed for the search nor to show up in search results, e.g, a 404 page.
+Sometimes you might have a page that you don't want to be indexed for the search nor to show up in search results, e.g., a 404 page.
 To exclude a page from search, add the `search_exclude: true` parameter to the page's YAML front matter:
 
 #### Example
@@ -125,3 +125,43 @@ $ bundle exec just-the-docs rake search:init
 
 This command creates the `assets/js/zzzz-search-data.json` file that Jekyll uses to create your search index.
 Alternatively, you can create the file manually with [this content]({{ site.github.repository_url }}/blob/main/assets/js/zzzz-search-data.json).
+
+## Custom content for search index
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }
+
+Advanced
+{: .label .label-yellow }
+
+By default, the search feature indexes a page's `.content`, `.title`, and *some* headers within the `.content`. Other data (e.g. front matter, files in `_data` and `assets`) is not indexed. Users can customize what is indexed.
+
+{: .warning }
+> Customizing search indices is an advanced feature that requires Javascript and Liquid knowledge.
+
+1. When Just the Docs is a local or gem theme, ensure `assets/js/zzzz-search-data.json` is up-to-date with [Generate search index when used as a gem](#generate-search-index-when-used-as-a-gem).
+2. Add a new file named `_includes/lunr/custom-data.json`. Insert custom Liquid code that reads your data (e.g. the page object at `include.page`) then generates custom Javascript fields that hold the custom data you want to index. Verify these fields in the generated `assets/js/search-data.json`.
+3. Add a new file named `_includes/lunr/custom-index.js`. Insert custom Javascript code that reads your custom Javascript fields and inserts them into the search index. You may want to inspect `assets/js/just-the-docs.js` to better understand the code.
+
+#### Example
+
+This example adds front matter `usage` and `examples` fields to the search index.
+
+`_includes/lunr/custom-data.json` custom code reads the page `usage` and `examples` fields, normalizes the text, and writes the text to custom Javascript `myusage` and `myexamples` fields. Javascript fields are similar yet [not the same as JSON](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON#javascript_and_json_differences). `jsonify` will probably work for most scenarios.
+
+{% raw %}
+```liquid
+{%- capture newline %}
+{% endcapture -%}
+"myusage": {{ include.page.usage | markdownify | replace:newline,' ' | strip_html | normalize_whitespace | strip | jsonify }},
+"myexamples": {{ include.page.examples | markdownify | replace:newline,' ' | strip_html | normalize_whitespace | strip | jsonify }},
+```
+{% endraw %}
+
+`_includes/lunr/custom-index.js` custom code is inserted into the Javascript loop of `assets/js/just-the-docs.js`. All custom Javascript fields are accessed as fields of `docs[i]` such as `docs[i].myusage`. Finally, append your custom fields on to the already existing `docs[i].content`.
+
+```javascript
+const content_to_merge = [docs[i].content, docs[i].myusage, docs[i].myexamples];
+docs[i].content = content_to_merge.join(' ');
+```

docs/ui-components/buttons.md

@@ -56,7 +56,7 @@ GitHub Flavored Markdown does not support the `button` element, so you'll have t
 
 ### Button size
 
-Wrap the button in a container that uses the [font-size utility classes]({{ site.baseurl }}{% link docs/utilities/typography.md %}) to scale buttons:
+Wrap the button in a container that uses the [font-size utility classes]({% link docs/utilities/typography.md %}) to scale buttons:
 
 <div class="code-example" markdown="1">
 <span class="fs-6">
@@ -79,7 +79,7 @@ Wrap the button in a container that uses the [font-size utility classes]({{ site
 
 ### Spacing between buttons
 
-Use the [margin utility classes]({{ site.baseurl }}{% link docs/utilities/layout.md %}#spacing) to add spacing between two buttons in the same block.
+Use the [margin utility classes]({% link docs/utilities/layout.md %}#spacing) to add spacing between two buttons in the same block.
 
 <div class="code-example" markdown="1">
 [Button with space](http://example.com/){: .btn .btn-purple .mr-2 }

docs/ui-components/callouts.md

@@ -6,6 +6,10 @@ nav_order: 7
 ---
 
 # Callouts
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }
 
 Markdown does not include support for callouts. However, you can style text as a callout using a Markdown extension supported by kramdown: [*block IALs*](https://kramdown.gettalong.org/quickref.html#block-attributes).
 
@@ -14,7 +18,7 @@ Common kinds of callouts include `highlight`, `important`, `new`, `note`, and `w
 {: .warning }
 These callout names are *not* pre-defined by the theme: you need to define your own names.
 
-When you have [configured]({{ site.baseurl }}{% link docs/configuration.md %}#callouts) the  `color` and (optional) `title` for a callout, you can apply it to a paragraph, or to a block quote with several paragraphs, as illustrated below.[^postfix]
+When you have [configured]({% link docs/configuration.md %}#callouts) the  `color` and (optional) `title` for a callout, you can apply it to a paragraph, or to a block quote with several paragraphs, as illustrated below.[^postfix]
 
 [^postfix]:
     You can put the callout markup either before or after its content.

docs/ui-components/code.md

@@ -90,6 +90,10 @@ To demonstrate front end code, sometimes it's useful to show a rendered example
 ---
 
 ## Mermaid diagram code blocks
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }
 
 [Mermaid](https://mermaid-js.github.io/mermaid/) allows you to add diagrams and visualizations using Markdown code blocks. **It is disabled by default**. However, you can turn on support for mermaid by adding a `mermaid` key to your `_config.yml`.
 
@@ -144,7 +148,42 @@ graph TD;
 
 *Note: for demonstration purposes, we've enabled mermaid on this site. It is still disabled by default, and users need to opt-in to use it.*
 
+### Using a local mermaid library
+
+In order to use a local version of the mermaid library instead of one provided by jsDelivr, you can specify a `path` key in the mermaid configuration instead of a `version` key.
+
+```yaml
+mermaid:
+  # 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"
+```
+
+### Using mermaid with AsciiDoc
+
+Users of [AsciiDoc](https://asciidoc.org/) (e.g. via [jekyll-asciidoc](https://github.com/asciidoctor/jekyll-asciidoc)) may need additional configuration to use mermaid.
+
+By default, AsciiDoc generates HTML markup that mermaid cannot properly parse. The simplest way to resolve this is to use a [passthrough block](https://docs.asciidoctor.org/asciidoc/latest/pass/pass-block/):
+{% highlight asciidoc %}
+++++
+<pre class="language-mermaid">
+graph TD;
+    A-->B;
+    A-->C;
+    B-->D;
+    C-->D;
+</pre>
+++++
+{% endhighlight %}
+
+Alternatively, community member [@flyx](https://.github.com/flyx) has contributed a Ruby extension that does not require extra markup. The extension is available [as a GitHub Gist](https://gist.github.com/flyx/9fff080cf4edc95d495bc661a002232c). Thank you to [@flyx](https://.github.com/flyx)!
+
+The [asciidoctor-diagram](https://docs.asciidoctor.org/diagram-extension/latest/) extension which also supports mermaid is not recommended for use with Just the Docs, since it requires separate configuration e.g. for theming, and is known to not be trivial to set up.
+
 ## Copy button
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }
 
 The copy button for code blocks can be enabled or disabled via the `enable_copy_code_button` key in `_config.yml`. By default, the value of this key is `false`; users need to opt-in.
 

docs/ui-components/typography.md

@@ -111,4 +111,4 @@ Text can be **bold**, _italic_, or ~~strikethrough~~.
 
 There are a number of specific typographic CSS classes that allow you to override default styling for font size, font weight, line height, and capitalization.
 
-[View typography utilities]({{ site.baseurl }}{% link docs/utilities/utilities.md %}#typography){: .btn .btn-outline }
+[View typography utilities]({% link docs/utilities/typography.md %}){: .btn .btn-outline }

fixtures/Gemfile-github-pages

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gem 'github-pages', group: :jekyll_plugins

fixtures/README.md

@@ -0,0 +1,3 @@
+# Test Fixtures
+
+These files are used by Just the Docs maintainers to test *the theme itself*. **If you are using Just the Docs as a theme, you should not copy these files over.**

index.md

@@ -18,7 +18,7 @@ Just the Docs gives your documentation a jumpstart with a responsive Jekyll them
 ---
 
 {: .warning }
-> This website documents the features of the current `main` branch of the Just the Docs theme. See [the CHANGELOG]({{ site.baseurl }}{% link CHANGELOG.md %}) for a list of releases, new features, and bug fixes. 
+> This website documents the features of the current `main` branch of the Just the Docs theme. See [the CHANGELOG]({% link CHANGELOG.md %}) for a list of releases, new features, and bug fixes.
 
 Just the Docs is a theme for generating static websites with [Jekyll]. You can write source files for your web pages using [Markdown], the [Liquid] templating language, and HTML.[^1] Jekyll builds your site by converting all files that have [front matter] to HTML. Your [Jekyll configuration] file determines which theme to use, and sets general parameters for your site, such as the URL of its home page.
 
@@ -95,5 +95,5 @@ Just the Docs is committed to fostering a welcoming community.
 [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/
-[customize]: {{ site.baseurl }}{% link docs/customization.md %}
+[customize]: {% link docs/customization.md %}
 [use the template]: https://github.com/just-the-docs/just-the-docs-template/generate

just-the-docs.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |spec|
   spec.name          = "just-the-docs"
-  spec.version       = "0.4.0.rc4"
+  spec.version       = "0.4.2"
   spec.authors       = ["Patrick Marsceill", "Matthew Wang"]
   spec.email         = ["patrick.marsceill@gmail.com", "matt@matthewwang.me"]
 
-  spec.summary       = %q{A modern, highly customizable, and responsive Jekyll theme for documention with built-in search.}
+  spec.summary       = %q{A modern, highly customizable, and responsive Jekyll theme for documentation with built-in search.}
   spec.homepage      = "https://github.com/just-the-docs/just-the-docs"
   spec.license       = "MIT"
   spec.metadata      = {
@@ -16,10 +16,10 @@ Gem::Specification.new do |spec|
     "source_code_uri"   => "https://github.com/just-the-docs/just-the-docs",
   }
 
-  spec.files         = `git ls-files -z`.split("\x0").select { |f| f.match(%r{^(assets|bin|_layouts|_includes|lib|Rakefile|_sass|LICENSE|README|CHANGELOG|favicon)}i) }
+  spec.files         = `git ls-files -z ':!:*.jpg' ':!:*.png'`.split("\x0").select { |f| f.match(%r{^(assets|bin|_layouts|_includes|lib|Rakefile|_sass|LICENSE|README|CHANGELOG|favicon)}i) }
   spec.executables   << 'just-the-docs'
 
-  spec.add_development_dependency "bundler", "~> 2.3.5"
+  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 "rake", ">= 12.3.1"

lib/tasks/search.rake

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

package.json

@@ -6,15 +6,41 @@
   "license": "MIT",
   "bugs": "https://github.com/just-the-docs/just-the-docs/issues",
   "devDependencies": {
-    "prettier": "^2.8.1",
+    "npm-run-all": "^4.1.5",
-    "stylelint": "^14.16.1",
+    "prettier": "^2.8.4",
-    "stylelint-config-prettier-scss": "0.0.1",
+    "stylelint": "^15.2.0",
-    "stylelint-config-standard-scss": "^6.1.0",
+    "stylelint-config-standard-scss": "^7.0.1"
-    "stylelint-prettier": "^2.0.0"
   },
   "scripts": {
-    "test": "stylelint '**/*.scss'",
+    "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}'",
-    "stylelint-check": "stylelint-config-prettier-check"
+    "test": "npm run lint"
+  },
+  "stylelint": {
+    "ignoreFiles": [
+      "assets/css/just-the-docs-default.scss",
+      "assets/css/just-the-docs-light.scss",
+      "assets/css/just-the-docs-dark.scss",
+      "_sass/vendor/**/*.scss"
+    ],
+    "extends": [
+      "stylelint-config-standard-scss"
+    ],
+    "rules": {
+      "alpha-value-notation": null,
+      "at-rule-empty-line-before": null,
+      "color-function-notation": null,
+      "no-descending-specificity": null,
+      "scss/no-global-function-names": null
+    }
+  },
+  "prettier": {
+    "endOfLine": "lf",
+    "semi": false,
+    "singleQuote": false,
+    "tabWidth": 2,
+    "trailingComma": "es5"
   }
 }