prep for v0.4.0.rc3

* Optimize simple navigation cases

Fix inefficiency reported in feedback on v0.4.0.rc2 (see discussion #958).

This PR:

* essentially reverts `_includes/nav.html` to v0.4.0.rc1
* preserves the ARIA labels added by #950
* adds a test to optimize builds of sites that rely on `title` fields to order pages.

Building the `endoflife.date` site (130 pages) now takes only about 7 seconds.

Building the `machinetranslate.org` site ( 350 pages) takes about 7 minutes. (Without the added test, it takes just over 5 minutes: the condition of the test is merely to compare the size of two arrays, but that is apparently enough to prevent Jekyll from applying some optimization).

A warning is added to the docs about the need for numbers to be in quotes when used as title values.

* Update navigation-structure.md

A clarification is added to the docs about the need for numbers to be in quotes when used as title values.

* Simplify the control and data flow

- Defer concatenation of `string_order_pages` with `title_order_pages` until needed.
- Replace tests on size with tests for `empty`.
- Rename variables accordingly.

* Fix child nav order

This PR started from the navigation in RC1. Some cosmetic improvements had been made in RC2. This commit adds some of those changes to this PR.

It also fixes a bug (revealed by a new regression test) due to a reference to `node.child_nav_order` instead of `child.child_nav_order`, which prevented reversal of the order in children of children. Presumably a top-level reversal should apply only to direct children, and not to grandchildren. The latter interpretation would be very confusing in a deep multi-level hierarchy.

* Allow pages with numeric titles

An omitted `nav_order` value should default to the `title` value, regardless of its type. Jekyll 3 gives build errors when numbers and strings are sorted together. This commit drops the assumption that `title` values are always strings – a 404 page naturally has a numeric title. It updates the docs page accordingly.

The extra code does not affect the build time for the `endoflife.date` site (7 seconds). For the `machinetranslate` site, changing the title of the 404 page to a number increases the build time from 7 minutes to 9 minutes – the `nav_order` numbers on that site are program-generated in the range 1..1000, which might be atypical.

This commit has not yet been checked using the regression tests.

The gemspec used for testing specifies `spec.add_runtime_dependency "jekyll", "~> 3.8.5"`, and `Gemfile.lock` shows `jekyll (3.8.7)`.

* Update nav.html

Add comment about an optimization that will be possible in Jekyll 4.

* Update nav.html

- Update the comment about optimization possibility.
- TEMPORARILY add Jekyll 3 code for conditionally optimizing.

* Update nav.html

Minor improvements and cosmetic changes.

* Major revision

This update is based on extensive experimentation and profiling with alternative versions of the Liquid code used to build the main navigation panel.

Due to the fragility of Jekyll's optimizations, combining alternative approaches with conditionals turned out to be too expensive: merely adding a condition to check whether some array of pages is empty can add about 20% to the build time!

The current code avoids sorting pages on `nav_order` and `title` fields together. The standard way of doing that in Jekyll is to use the `group_by` filter; but extracting the sorted pages from the groups turned out to be too inefficient (as seen in RC1), as was generating links directly from the groups (in RC2).

Making all pages with `nav_order` values come before all those ordered by their `title` values is not ideal (it doesn't support tweaking the relative order of two pages in a list of pages ordered by their titles) but it appears to be necessary for efficient builds on large sites.

This version has not yet been fully tested for regression, but otherwise seems to give the expected navigation on the endoflife.date and machinetranslate websites. (I'm unable to install the Python-based how2data repository on my laptop, due to package version issues on Apple silicon).

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

CHANGELOG.md

@@ -1,29 +1,204 @@
-# Changelog
+---
+title: CHANGELOG
+layout: default
+---
+
+# CHANGELOG
 
 All notable changes to this project are documented in this file.
 
-*Note:* the project underwent a maintenance shift in the creation of v0.4.0.
+{: .highlight }
+The project underwent a major maintenance shift in March 2022.
 
-## v0.4.0.rc1
+## HEAD
+
+{: .note }
+This website is built from the `HEAD` of the `main` branch of the theme repository.
+
+{: .warning }
+This website includes docs for some new features that are not available in `v0.4.0.rc2` and `v0.3.3`!
+
+Changes to `main` that are *not* in the latest pre-release:
+
+- N/A
+
+## Pre-release v0.4.0.rc3
+
+Hi there! This is (actually) hopefully the last prerelease before `v0.4.0`; in particular, if we find that this prerelease is stable, we'll re-release it as `v0.4.0`.
+
+In general, this is a more mature pre-release; there are few new features. However, we'll highlight [@pdmosses]'s work in [#992] to better optimize nav generation for large sites (ex 100+ pages). We don't expect this to affect most users; however, **it is technically a breaking change**, and we suggest testing your site before upgrading to this prerelease.
+
+We want your feedback! Please [open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know!
+
+As soon as we get stable test results from major downstream users, we'll push out a `v0.4.0` ASAP - closing out almost 2 years of backlogged work!
+
+### Trying out pre-release `v0.4.0.rc3`
+
+Simlar to the prior release, `v0.4.0.rc3` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc3`.
+
+To use this RC explicitly as a remote theme:
+
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.4.0.rc3
+```
+
+To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
+
+```Ruby
+gem "just-the-docs", "0.4.0.rc3"
+```
+
+By default, **users will not be upgraded to `0.4.0.rc3`**. To enforce that explicitly, either:
+
+1. pin your gem version in your `Gemfile`, like so
+```Ruby
+gem "just-the-docs", "0.3.3"
+```
+2. freeze the `remote_theme`, like so
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.3.3
+```
+
+### Features
+
+Broadly, this prerelease is feature-light!
+
+- Added: styling for `<blockquote>` by [@mattxwang] in [#965]
+- Added: custom include for TOC heading by [@pdmosses] in [#980]
+
+### Bugfixes and Experimental Features
+
+*Note*: experimental nav optimization may be unstable. Please give us feedback!
+
+- Added: experimental nav optimization for simple cases by [@pdmosses] in [#992]
+- Fixed: spacing issue when search is disabled by [@henryiii] in [#960]
+- Fixed: active grandchild link class by [@pdmosses] in [#962]
+- Fixed: HTML validation issues (W3C validator) by [@mattxwang] in [#964]
+- Fixed: link styling now uses `text-decoration` values by [@mattxwang] in [#967]
+- Fixed: cleaning up Jekyll excludes by [@pdmosses] in [#985]
+- Fixed: docs, narrow styling for code highlighting with line numbers by [@pdmosses] in [#974]
+- Fixed: default syntax highlighting in custom color schemes [@pdmosses] in [#986]
+
+[#965]: https://github.com/just-the-docs/just-the-docs/pull/965
+[#960]: https://github.com/just-the-docs/just-the-docs/pull/960
+[#962]: https://github.com/just-the-docs/just-the-docs/pull/962
+[#964]: https://github.com/just-the-docs/just-the-docs/pull/964
+[#967]: https://github.com/just-the-docs/just-the-docs/pull/967
+[#974]: https://github.com/just-the-docs/just-the-docs/pull/974
+[#980]: https://github.com/just-the-docs/just-the-docs/pull/980
+[#985]: https://github.com/just-the-docs/just-the-docs/pull/985
+[#986]: https://github.com/just-the-docs/just-the-docs/pull/986
+[#992]: https://github.com/just-the-docs/just-the-docs/pull/992
+
+[@henryiii]: https://github.com/henryiii
+
+**Full Changelog**: https://github.com/just-the-docs/just-the-docs/compare/v0.4.0.rc2...v0.4.0.rc3
+
+## Pre-release v0.4.0.rc2
+
+{: .warning }
+This website includes docs for some new features that are not available in `v0.4.0.rc1` and `v0.3.3`!
+
+Hey there! This is likely the last pre-release before releasing `v0.4.0`, which we plan on doing soon (i.e. before the end of the month) - very exciting! Some new additions to highlight:
+
+- significant improvement on build time of navigation panel by [@pdmosses]
+  - this is big: for a community member with over 300 pages, we shortened the build time from 3 minutes to 30 seconds!
+- improved accessibility features led by [@JPrevost]
+- more docs!
+
+The intention of this release candidate is to gather even more feedback on a potential `v0.4.0`. As it stands, we have not encountered any breaking changes with early adopters of `v0.4.0.rc1`. If you encounter any - for either of our pre-releases - please let us know!
+
+### Trying out pre-release `v0.4.0.rc2`
+
+Simlar to the prior release, `v0.4.0.rc2` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc2`.
+
+To use this RC explicitly as a remote theme:
+
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.4.0.rc2
+```
+
+To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
+
+```Ruby
+gem "just-the-docs", "0.4.0.rc2"
+```
+
+By default, **users will not be upgraded to `0.4.0.rc2`**. To enforce that explicitly, either:
+
+1. pin your gem version in your `Gemfile`, like so
+```Ruby
+gem "just-the-docs", "0.3.3"
+```
+2. freeze the `remote_theme`, like so
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.3.3
+```
+
+### Features
+
+- Added: accessible titles to nested page nav toggle by [@JPrevost] in [#950]
+- Added: better title styling for AsciiDoc examples by [@alyssais] in [#944]
+- Added: docs for custom search placeholder by [@mattxwang] in [#939]
+- Added: provide ability to skip to main content by [@JPrevost] in [#949]
+- Fixed: exclude `vendor/` in Jekyll config by [@manuelhenke] in [#941]
+- Fixed: improve build time of navigation panel by [@pdmosses] in [#956]
+
+[#950]: https://github.com/just-the-docs/just-the-docs/pull/950
+[#944]: https://github.com/just-the-docs/just-the-docs/pull/944
+[#939]: https://github.com/just-the-docs/just-the-docs/pull/939
+[#949]: https://github.com/just-the-docs/just-the-docs/pull/949
+[#941]: https://github.com/just-the-docs/just-the-docs/pull/941
+[#956]: https://github.com/just-the-docs/just-the-docs/pull/956
+
+[@alyssais]: https://github.com/alyssais
+
+### Documentation and Maintenance
+
+- Added: docs load mermaid.js by default by [@mattxwang] in [#935]
+- Fixed: table of contents on search docs by [@robinpokorny] in [#940]
+- Fixed: broken docs link (custom footer) by [@olgarithms] in [#951]
+- Fixed: clarify version docs by [@pdmosses] in [#955]
+- Deleted: unused script directory by [@mattxwang] in [#937]
+
+[#935]: https://github.com/just-the-docs/just-the-docs/pull/935
+[#940]: https://github.com/just-the-docs/just-the-docs/pull/940
+[#951]: https://github.com/just-the-docs/just-the-docs/pull/951
+[#955]: https://github.com/just-the-docs/just-the-docs/pull/955
+[#937]: https://github.com/just-the-docs/just-the-docs/pull/937
+
+### New Contributors
+
+* [@robinpokorny] made their first contribution in [#940]
+* [@olgarithms] made their first contribution in [#951]
+* [@manuelhenke] made their first contribution in [#941]
+* [@JPrevost] made their first contribution in [#950]
+
+[@robinpokorny]: https://github.com/robinpokorny
+[@olgarithms]: https://github.com/olgarithms
+[@manuelhenke]: https://github.com/manuelhenke
+[@JPrevost]: https://github.com/JPrevost
+
+## Pre-release v0.4.0.rc1
 
 ### We're back!
 
-Hi all! The Just the Docs team is excited to have our first release in over two years! This release is jam-packed with features and bugfixes that have been requested by the community since 2020. They include:
+Hi all! The Just the Docs team is excited to have our first pre-release in over two years! It is jam-packed with features and bugfixes that have been requested by the community since 2020. They include:
 
 - The new callouts component
 - Allowing pages and collections to coexist on the navigation pane
 - New styling: dark syntax highlighting, support for jekyll-asciidoc, word-wrapping instead of overflow for various elements
 - More customization: external nav links, custom nav footers, favicon includes, search color and placeholder configuration, mermaid.js support, and nav sorting
 - Over 20 bugfixes! Big ones include fixing the `rake` command, using `relative_url`, and search input color
-- More documentation, especially on using custom includes.
+- More documentation, especially on using custom includes
 - Updating core dependencies to stable Ruby versions
 - A WIP [template repository](https://github.com/just-the-docs/just-the-docs-template) that allows you to setup your own repository using Just the Docs and GitHub Pages with one click - give it a shot! More documentation, etc. is on the way!
 
 We want your feedback! Are these changes helpful? Are our docs easy to understand? Should new features like `mermaid` be opt-in or opt-out? Please [open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know!
 
-### Trying out `v0.4.0.rc1`
+### Trying out pre-release `v0.4.0.rc1`
 
-Due to the massive scope of these changes, we're releasing `v0.4.0.rc1` as a **release candidate** for the theme, with `v0.4.0` coming soon. We want your help in testing the theme! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc1` - if your version of Just the Docs is not pinned, you'll see the changes the next time you build / run `bundle install` (if you don't use a `Gemfile.lock`) or `bundle update just-the-docs` (if you do).
+Due to the massive scope of these changes, we're making `v0.4.0.rc1` avaialble as a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc1`.
 
 To use this RC explicitly as a remote theme:
 
@@ -31,7 +206,7 @@ To use this RC explicitly as a remote theme:
 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`:
+To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
 
 ```Ruby
 gem "just-the-docs", "0.4.0.rc1"
@@ -52,128 +227,238 @@ gem "just-the-docs", "0.3.3"
 remote_theme: just-the-docs/just-the-docs@v0.3.3
 ```
 
-**Warning**: Use of branches for closed PRs (e.g., https://github.com/just-the-docs/just-the-docs/pull/466, https://github.com/just-the-docs/just-the-docs/pull/578) is now deprecated, as those branches have been (directly or indirectly) merged, and they will be deleted after the release of `v0.4.0.rc1`.
+{: .warning }
+Use of branches for closed PRs (e.g., [#466], [#578]) is now deprecated, as those branches have been (directly or indirectly) merged, and they may be deleted after the pre-release of `v0.4.0.rc1`.
 
 ### Maintenance
 
-Internally, our maintainer team has expanded: [Patrick Marsceill](https://github.com/pmarsceill), the original maintainer, has stepped down from an active role after almost 4 years! We're very thankful for the work that he's done to create and maintain one of the most popular Jekyll themes. Please join us in giving him thanks!
+Internally, our maintainer team has expanded: [Patrick Marsceill][@pmarsceill], the original maintainer, has stepped down from an active role after almost 4 years! We're very thankful for the work that he's done to create and maintain one of the most popular Jekyll themes. Please join us in giving him thanks!
 
-The new core team currently consists of @mattxwang, @pdmosses, @skullface, @dougaitken, and @max06. Over the past six months, we've been triaging and merging in PRs, as well as contributing our own fixes. We'll continue to address open issues, merge in PRs from the community, and plan out the future of Just the Docs. If you'd like to contribute, now is a great time!
+The new core team currently consists of [@mattxwang], [@pdmosses], [@skullface], [@dougaitken], and [@max06]. Over the past six months, we've been triaging and merging in PRs, as well as contributing our own fixes. We'll continue to address open issues, merge in PRs from the community, and plan out the future of Just the Docs. If you'd like to contribute, now is a great time!
+
+[@mattxwang]: https://github.com/mattxwang
+[@pdmosses]: https://github.com/pdmosses
+[@skullface]: https://github.com/skullface
+[@dougaitken]: https://github.com/dougaitken
+[@max06]: https://github.com/max06
 
 ### Roadmap
 
-In the short-term, we're committed to tidying up everything for a `v0.4.0` release. This involves fixing bugs reported from the community in this release, as well as continually merging in minor PRs.
+In the short-term, we're committed to tidying up everything for a `v0.4.0` release. This involves fixing bugs reported from the community in this pre-release, as well as continually merging in minor PRs.
 
 We're also scoping out medium and long-term projects, and want to keep you in the loop. These include:
 
 - upgrading to Jekyll 4, and stopping support for Jekyll 3
-- improved accessibility - issues [#566](https://github.com/just-the-docs/just-the-docs/issues/566), [#870](https://github.com/just-the-docs/just-the-docs/issues/870)
+- versioned docs - issue [#728]
-- internationalization (i18n) - issue [#59](https://github.com/just-the-docs/just-the-docs/issues/59)
+- improved accessibility - issues [#566], [#870]
-- recursive/multi-level navigation - PR [#462](https://github.com/just-the-docs/just-the-docs/pull/462)
+- internationalization (i18n) - issue [#59]
-- toggleable dark mode - issue [#234](https://github.com/just-the-docs/just-the-docs/issues/234)
+- recursive/multi-level navigation - PR [#462]
+- toggleable dark mode - issue [#234]
 
 as well as DX improvements like better regression tests, CI, and tooling. If you're interested in any of these, please join us [on GitHub](https://github.com/just-the-docs/just-the-docs) - any contribution (raising an issue, writing docs, or submitting a PR) is welcome!
 
+[#728]: https://github.com/just-the-docs/just-the-docs/issues/728
+[#566]: https://github.com/just-the-docs/just-the-docs/issues/566
+[#870]: https://github.com/just-the-docs/just-the-docs/issues/870
+[#59]: https://github.com/just-the-docs/just-the-docs/issues/59
+[#462]: https://github.com/just-the-docs/just-the-docs/pull/462
+[#234]: https://github.com/just-the-docs/just-the-docs/issues/234
+
 ### Features
 
-* Added: Combination by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/578
+* Added: Combination by [@pdmosses] in [#578]
-  - Added: dark highlighting in https://github.com/just-the-docs/just-the-docs/pull/463
+  - Added: dark highlighting in [#463]
-  - Added: pages and collections in https://github.com/just-the-docs/just-the-docs/pull/448
+  - Added: pages and collections in [#448]
-  - Added: callouts in https://github.com/just-the-docs/just-the-docs/pull/466
+  - Added: callouts in [#466]
-  - Fixed: breadcrumb behaviour … by @AdityaTiwari2102 in https://github.com/just-the-docs/just-the-docs/pull/477
+  - Fixed: breadcrumb behaviour … by [@AdityaTiwari2102] in [#477]
-  - Fixed: prevent rake command corrupting search data in https://github.com/just-the-docs/just-the-docs/pull/495 (also listed below)
+  - Fixed: prevent rake command corrupting search data in [#495] (also listed below)
-  - Fixed: nested lists in https://github.com/just-the-docs/just-the-docs/pull/496
+  - Fixed: nested lists in [#496]
-  - Fixed: set color for search input in https://github.com/just-the-docs/just-the-docs/pull/498 (also listed below)
+  - 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 https://github.com/just-the-docs/just-the-docs/pull/494
+  - 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 https://github.com/just-the-docs/just-the-docs/pull/639
+  - 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 https://github.com/just-the-docs/just-the-docs/pull/544
+  - Fixed: Replace all uses of `absolute_url` by `relative_url`, by [@svrooij] in [#544]
-* Added: custom favicon `_includes` by @burner1024 in https://github.com/just-the-docs/just-the-docs/pull/364
+* Added: custom favicon `_includes` by [@burner1024] in [#364]
-* Added: set color for search input by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/498
+* Added: set color for search input by [@pdmosses] in [#498]
-* Added: search placeholder configuration by @mattxwang in https://github.com/just-the-docs/just-the-docs/pull/613
+* 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 https://github.com/just-the-docs/just-the-docs/pull/726
+* 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 https://github.com/just-the-docs/just-the-docs/pull/474
+* Added: `nav_footer_custom` include by [@nathanjessen] in [#474]
-* Added: style fixes for jekyll-asciidoc by @alyssais in https://github.com/just-the-docs/just-the-docs/pull/829
+* Added: style fixes for jekyll-asciidoc by [@alyssais] in [#829]
-* Added: mermaid.js support by @nascosto in https://github.com/just-the-docs/just-the-docs/pull/857
+* Added: mermaid.js support by [@nascosto] in [#857]
-* Added: support for external navigation links by @SPGoding in https://github.com/just-the-docs/just-the-docs/pull/876
+* 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 https://github.com/just-the-docs/just-the-docs/pull/909
+* Added: refactor `mermaid` config to use `mermaid_config.js` include, only require `mermaid.version` in `_config.yml` by [@mattxwang] in [#909]
-* Fixed: prepend `site.collections_dir` if exists by @alexsegura in https://github.com/just-the-docs/just-the-docs/pull/519
+* Fixed: prepend `site.collections_dir` if exists by [@alexsegura] in [#519]
-* Fixed: nested task lists (#517) by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/855
+* Fixed: nested task lists (#517) by [@pdmosses] in [#855]
-* Fixed: suppress Liquid processing in CSS comments by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/686
+* Fixed: suppress Liquid processing in CSS comments by [@pdmosses] in [#686]
-* Fixed: prevent rake command from corrupting search data by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/495
+* Fixed: prevent rake command from corrupting search data by [@pdmosses] in [#495]
-* Fixed: anchor heading links should be visible on focus by @jacobhq in https://github.com/just-the-docs/just-the-docs/pull/846
+* Fixed: anchor heading links should be visible on focus by [@jacobhq] in [#846]
-* Fixed: add `overflow-x: auto` to `figure.highlight` by @iridazzle in https://github.com/just-the-docs/just-the-docs/pull/727
+* Fixed: add `overflow-x: auto` to `figure.highlight` by [@iridazzle] in [#727]
-* Fixed: add `overflow-wrap: word-break` to `body` by @iridazzle in https://github.com/just-the-docs/just-the-docs/pull/889
+* Fixed: add `overflow-wrap: word-break` to `body` by [@iridazzle] in [#889]
-* Fixed: vertical alignment for consecutive labels by @Eisverygoodletter in https://github.com/just-the-docs/just-the-docs/pull/893
+* Fixed: vertical alignment for consecutive labels by [@Eisverygoodletter] in [#893]
-* Fixed: allow links to wrap by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/905
+* Fixed: allow links to wrap by [@pdmosses] in [#905]
-* Fixed: nav scroll feature and absolute/relative URLs by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/898
+* Fixed: nav scroll feature and absolute/relative URLs by [@pdmosses] in [#898]
+
+[#578]: https://github.com/just-the-docs/just-the-docs/pull/578
+[#463]: https://github.com/just-the-docs/just-the-docs/pull/463
+[#448]: https://github.com/just-the-docs/just-the-docs/pull/448
+[#466]: https://github.com/just-the-docs/just-the-docs/pull/466
+[#477]: https://github.com/just-the-docs/just-the-docs/pull/477
+[#495]: https://github.com/just-the-docs/just-the-docs/pull/495
+[#496]: https://github.com/just-the-docs/just-the-docs/pull/496
+[#498]: https://github.com/just-the-docs/just-the-docs/pull/498
+[#494]: https://github.com/just-the-docs/just-the-docs/pull/494
+[#639]: https://github.com/just-the-docs/just-the-docs/pull/639
+[#544]: https://github.com/just-the-docs/just-the-docs/pull/544
+[#364]: https://github.com/just-the-docs/just-the-docs/pull/364
+[#498]: https://github.com/just-the-docs/just-the-docs/pull/498
+[#613]: https://github.com/just-the-docs/just-the-docs/pull/613
+[#726]: https://github.com/just-the-docs/just-the-docs/pull/726
+[#474]: https://github.com/just-the-docs/just-the-docs/pull/474
+[#829]: https://github.com/just-the-docs/just-the-docs/pull/829
+[#857]: https://github.com/just-the-docs/just-the-docs/pull/857
+[#876]: https://github.com/just-the-docs/just-the-docs/pull/876
+[#909]: https://github.com/just-the-docs/just-the-docs/pull/909
+[#519]: https://github.com/just-the-docs/just-the-docs/pull/519
+[#855]: https://github.com/just-the-docs/just-the-docs/pull/855
+[#686]: https://github.com/just-the-docs/just-the-docs/pull/686
+[#495]: https://github.com/just-the-docs/just-the-docs/pull/495
+[#846]: https://github.com/just-the-docs/just-the-docs/pull/846
+[#727]: https://github.com/just-the-docs/just-the-docs/pull/727
+[#889]: https://github.com/just-the-docs/just-the-docs/pull/889
+[#893]: https://github.com/just-the-docs/just-the-docs/pull/893
+[#905]: https://github.com/just-the-docs/just-the-docs/pull/905
+[#898]: https://github.com/just-the-docs/just-the-docs/pull/898
 
 ### Documentation
 
-* Added: docs on how to break an `ol` by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/856
+* Added: docs on how to break an `ol` by [@pdmosses] in [#856]
-* Added: docs for custom includes by @nathanjessen in https://github.com/just-the-docs/just-the-docs/pull/806
+* Added: docs for custom includes by [@nathanjessen] in [#806]
-* Added: document caveat about variable dependencies by @waldyrious in https://github.com/just-the-docs/just-the-docs/pull/555
+* 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 https://github.com/just-the-docs/just-the-docs/pull/814
+* Added: docs on how to use `custom_head` to add a custom favicon by [@UnclassedPenguin] in [#814]
-* Fixed: `ol` on `index.md` by @pmarsceill in https://github.com/just-the-docs/just-the-docs/pull/778
+* Fixed: `ol` on `index.md` by [@pmarsceill] in [#778]
-* Fixed: image link in Markdown kitchen sink by @JeffGuKang in https://github.com/just-the-docs/just-the-docs/pull/221
+* Fixed: image link in Markdown kitchen sink by [@JeffGuKang] in [#221]
-* Fixed: images in Markdown kitchen sink by @dougaitken in https://github.com/just-the-docs/just-the-docs/pull/782
+* Fixed: images in Markdown kitchen sink by [@dougaitken] in [#782]
-* Fixed: clearer label of link to Jekyll quickstart by @waldyrious in https://github.com/just-the-docs/just-the-docs/pull/549
+* Fixed: clearer label of link to Jekyll quickstart by [@waldyrious] in [#549]
-* Fixed: remove extra spaces in component docs by @MichelleBlanchette in https://github.com/just-the-docs/just-the-docs/pull/554
+* Fixed: remove extra spaces in component docs by [@MichelleBlanchette] in [#554]
-* Fixed: double "your" typo in `index.md` by @sehilyi in https://github.com/just-the-docs/just-the-docs/pull/499
+* Fixed: double "your" typo in `index.md` by [@sehilyi] in [#499]
-* Fixed: "you" -> "your" typo in `index.md` by @nathanjessen in https://github.com/just-the-docs/just-the-docs/pull/473
+* Fixed: "you" -> "your" typo in `index.md` by [@nathanjessen] in [#473]
-* Fixed: spacing in toc example by @henryiii in https://github.com/just-the-docs/just-the-docs/pull/835
+* Fixed: spacing in toc example by [@henryiii] in [#835]
-* Fixed: typo in `README` on `_config.yml` by @ivanskodje in https://github.com/just-the-docs/just-the-docs/pull/891
+* Fixed: typo in `README` on `_config.yml` by [@ivanskodje] in [#891]
-* Fixed: missing code fence in navigation structure docs by @mattxwang in https://github.com/just-the-docs/just-the-docs/pull/906
+* Fixed: missing code fence in navigation structure docs by [@mattxwang] in [#906]
+
+[#856]: https://github.com/just-the-docs/just-the-docs/pull/856
+[#806]: https://github.com/just-the-docs/just-the-docs/pull/806
+[#555]: https://github.com/just-the-docs/just-the-docs/pull/555
+[#814]: https://github.com/just-the-docs/just-the-docs/pull/814
+[#778]: https://github.com/just-the-docs/just-the-docs/pull/778
+[#221]: https://github.com/just-the-docs/just-the-docs/pull/221
+[#782]: https://github.com/just-the-docs/just-the-docs/pull/782
+[#549]: https://github.com/just-the-docs/just-the-docs/pull/549
+[#554]: https://github.com/just-the-docs/just-the-docs/pull/554
+[#499]: https://github.com/just-the-docs/just-the-docs/pull/499
+[#473]: https://github.com/just-the-docs/just-the-docs/pull/473
+[#835]: https://github.com/just-the-docs/just-the-docs/pull/835
+[#891]: https://github.com/just-the-docs/just-the-docs/pull/891
+[#906]: https://github.com/just-the-docs/just-the-docs/pull/906
 
 ### Maintenance
 
-* Added: VScode devcontainer by @max06 in https://github.com/just-the-docs/just-the-docs/pull/783
+* Added: VScode devcontainer by [@max06] in [#783]
-* Added: `webrick` to `Gemfile` by @mattxwang in https://github.com/just-the-docs/just-the-docs/pull/799
+* Added: `webrick` to `Gemfile` by [@mattxwang] in [#799]
-* Added: 'This site is powered by Netlify.' to the footer by @mattxwang in https://github.com/just-the-docs/just-the-docs/pull/797
+* Added: 'This site is powered by Netlify.' to the footer by [@mattxwang] in [#797]
-* Updated: new repo path by @pmarsceill in https://github.com/just-the-docs/just-the-docs/pull/775
+* Updated: new repo path by [@pmarsceill] in [#775]
-* Updated: rename `master` -> `main` by @pmarsceill in https://github.com/just-the-docs/just-the-docs/pull/776
+* Updated: rename `master` -> `main` by [@pmarsceill] in [#776]
-* Updated: README by @pmarsceill in https://github.com/just-the-docs/just-the-docs/pull/777
+* Updated: README by [@pmarsceill] in [#777]
-* Updated: Code of Conduct to Contributor Covenant v2.1 by @mattxwang in https://github.com/just-the-docs/just-the-docs/pull/790
+* Updated: Code of Conduct to Contributor Covenant v2.1 by [@mattxwang] in [#790]
-* Updated: CI files, Ruby & Node Versions by @mattxwang in https://github.com/just-the-docs/just-the-docs/pull/820
+* 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 https://github.com/just-the-docs/just-the-docs/pull/821
+* Updated: Stylelint to v14, extend SCSS plugins, remove primer-* configs, resolve issues by [@mattxwang] in [#821]
+
+[#783]: https://github.com/just-the-docs/just-the-docs/pull/783
+[#799]: https://github.com/just-the-docs/just-the-docs/pull/799
+[#797]: https://github.com/just-the-docs/just-the-docs/pull/797
+[#775]: https://github.com/just-the-docs/just-the-docs/pull/775
+[#776]: https://github.com/just-the-docs/just-the-docs/pull/776
+[#777]: https://github.com/just-the-docs/just-the-docs/pull/777
+[#790]: https://github.com/just-the-docs/just-the-docs/pull/790
+[#820]: https://github.com/just-the-docs/just-the-docs/pull/820
+[#821]: https://github.com/just-the-docs/just-the-docs/pull/821
 
 ### Dependencies
-* Upgrade to GitHub-native Dependabot by @dependabot-preview in https://github.com/just-the-docs/just-the-docs/pull/627
+
-* [Security] Bump y18n from 3.2.1 to 3.2.2 by @dependabot-preview in https://github.com/just-the-docs/just-the-docs/pull/606
+* Upgrade to GitHub-native Dependabot by @dependabot-preview in [#627]
-* [Security] Bump hosted-git-info from 2.7.1 to 2.8.9 by @dependabot-preview in https://github.com/just-the-docs/just-the-docs/pull/641
+* [Security] Bump y18n from 3.2.1 to 3.2.2 by @dependabot-preview in [#606]
-* [Security] Bump lodash from 4.17.19 to 4.17.21 by @dependabot-preview in https://github.com/just-the-docs/just-the-docs/pull/640
+* [Security] Bump hosted-git-info from 2.7.1 to 2.8.9 by @dependabot-preview in [#641]
-* [Security] Bump ini from 1.3.5 to 1.3.8 by @dependabot-preview in https://github.com/just-the-docs/just-the-docs/pull/511
+* [Security] Bump lodash from 4.17.19 to 4.17.21 by @dependabot-preview in [#640]
-* Bump path-parse from 1.0.6 to 1.0.7 by @dependabot in https://github.com/just-the-docs/just-the-docs/pull/699
+* [Security] Bump ini from 1.3.5 to 1.3.8 by @dependabot-preview in [#511]
-* Bump ajv from 6.10.0 to 6.12.6 by @dependabot in https://github.com/just-the-docs/just-the-docs/pull/766
+* Bump path-parse from 1.0.6 to 1.0.7 by @dependabot in [#699]
-* Bump prettier from 2.1.2 to 2.5.1 by @dependabot in https://github.com/just-the-docs/just-the-docs/pull/787
+* Bump ajv from 6.10.0 to 6.12.6 by @dependabot in [#766]
-* Bump prettier from 2.5.1 to 2.6.2 by @dependabot in https://github.com/just-the-docs/just-the-docs/pull/809
+* Bump prettier from 2.1.2 to 2.5.1 by @dependabot in [#787]
-* Bump prettier from 2.6.2 to 2.7.1 by @dependabot in https://github.com/just-the-docs/just-the-docs/pull/864
+* Bump prettier from 2.5.1 to 2.6.2 by @dependabot in [#809]
+* Bump prettier from 2.6.2 to 2.7.1 by @dependabot in [#864]
+
+[#627]: https://github.com/just-the-docs/just-the-docs/pull/627
+[#606]: https://github.com/just-the-docs/just-the-docs/pull/606
+[#641]: https://github.com/just-the-docs/just-the-docs/pull/641
+[#640]: https://github.com/just-the-docs/just-the-docs/pull/640
+[#511]: https://github.com/just-the-docs/just-the-docs/pull/511
+[#699]: https://github.com/just-the-docs/just-the-docs/pull/699
+[#766]: https://github.com/just-the-docs/just-the-docs/pull/766
+[#787]: https://github.com/just-the-docs/just-the-docs/pull/787
+[#809]: https://github.com/just-the-docs/just-the-docs/pull/809
+[#864]: https://github.com/just-the-docs/just-the-docs/pull/864
 
 ### New Contributors
-* @alexsegura made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/519
+
-* @burner1024 made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/364
+* [@AdityaTiwari2102] made their first contribution in [#477]
-* @JeffGuKang made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/221
+* [@svrooij] made their first contribution in [#544]
-* @dougaitken made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/782
+* [@alexsegura] made their first contribution in [#519]
-* @max06 made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/783
+* [@burner1024] made their first contribution in [#364]
-* @sehilyi made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/499
+* [@JeffGuKang] made their first contribution in [#221]
-* @nathanjessen made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/473
+* [@dougaitken] made their first contribution in [#782]
-* @waldyrious made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/549
+* [@max06] made their first contribution in [#783]
-* @MichelleBlanchette made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/554
+* [@sehilyi] made their first contribution in [#499]
-* @henryiii made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/835
+* [@nathanjessen] made their first contribution in [#473]
-* @jmertic made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/726
+* [@waldyrious] made their first contribution in [#549]
-* @jacobhq made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/846
+* [@MichelleBlanchette] made their first contribution in [#554]
-* @UnclassedPenguin made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/814
+* [@henryiii] made their first contribution in [#835]
-* @alyssais made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/829
+* [@jmertic] made their first contribution in [#726]
-* @nascosto made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/857
+* [@jacobhq] made their first contribution in [#846]
-* @SPGoding made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/876
+* [@UnclassedPenguin] made their first contribution in [#814]
-* @iridazzle made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/727
+* [@alyssais] made their first contribution in [#829]
-* @ivanskodje made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/891
+* [@nascosto] made their first contribution in [#857]
-* @Eisverygoodletter made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/893
+* [@SPGoding] made their first contribution in [#876]
+* [@iridazzle] made their first contribution in [#727]
+* [@ivanskodje] made their first contribution in [#891]
+* [@Eisverygoodletter] made their first contribution in [#893]
+
+[@AdityaTiwari2102]: https://githhub.com/AdityaTiwari2102
+[@svrooij]: https://githhub.com/svrooij
+[@alexsegura]: https://githhub.com/alexsegura
+[@burner1024]: https://githhub.com/burner1024
+[@JeffGuKang]: https://githhub.com/JeffGuKang
+[@dougaitken]: https://githhub.com/dougaitken
+[@max06]: https://githhub.com/max06
+[@sehilyi]: https://githhub.com/sehilyi
+[@nathanjessen]: https://githhub.com/nathanjessen
+[@waldyrious]: https://githhub.com/waldyrious
+[@MichelleBlanchette]: https://githhub.com/MichelleBlanchette
+[@henryiii]: https://githhub.com/henryiii
+[@jmertic]: https://githhub.com/jmertic
+[@jacobhq]: https://githhub.com/jacobhq
+[@UnclassedPenguin]: https://githhub.com/UnclassedPenguin
+[@alyssais]: https://githhub.com/alyssais
+[@nascosto]: https://githhub.com/nascosto
+[@SPGoding]: https://githhub.com/SPGoding
+[@iridazzle]: https://githhub.com/iridazzle
+[@ivanskodje]: https://githhub.com/ivanskodje
+[@Eisverygoodletter]: https://githhub.com/Eisverygoodletter
 
 **Full Changelog**: https://github.com/just-the-docs/just-the-docs/compare/v0.3.3...v0.4.0.rc1
 
+[@pmarsceill]: https://githhub.com/pmarsceill
+
 ## v0.3.3
 
 ### 🚀 Features

README.md

@@ -61,7 +61,6 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/just-t
 - Open a [Pull Request](https://github.com/just-the-docs/just-the-docs/pulls)
 - Ensure all CI tests pass
 - Await code review
-- Bump the version number in `just-the-docs.gemspec` and `package.json` according to [semantic versioning](https://semver.org/).
 
 ### Design and development principles of this theme:
 

_config.yml

@@ -19,7 +19,29 @@ 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
 
 permalink: pretty
-exclude: ["node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json",  "script/", "LICENSE.txt", "lib/", "bin/", "README.md", "Rakefile"]
+
+exclude:
+ # from https://github.com/jekyll/jekyll/blob/master/lib/site_template/_config.yml:
+   - .sass-cache/
+   - .jekyll-cache/
+   - gemfiles/
+   - Gemfile
+   - Gemfile.lock
+   - node_modules/
+   - vendor/bundle/
+   - vendor/cache/
+   - vendor/gems/
+   - vendor/ruby/
+ # specific to the theme website:
+   - bin/
+   - lib/
+   - "*.gemspec"
+   - "*.gem"
+   - LICENSE.txt
+   - package.json
+   - package-lock.json
+   - Rakefile
+   - README.md
 
 # Set a path/url to a logo that will be displayed instead of the title
 #logo: "/assets/images/just-the-docs.png"
@@ -51,14 +73,15 @@ search:
   # Supports true or false (default)
   button: false
 
-# To enable support for mermaid diagrams (https://mermaid-js.github.io/mermaid/),
+# To disable support for mermaid diagrams (https://mermaid-js.github.io/mermaid/),
-# uncomment the `mermaid` and `version` keys below
+# comment out the `mermaid` and `version` keys below
-# mermaid:
+# By default, consuming the theme as a gem leaves mermaid disabled; it is opt-in
-#   # Version of mermaid library
+mermaid:
-#   # Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/
+  # Version of mermaid library
-#   version: "9.1.3"
+  # Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/
-#   # Put any additional configuration, such as setting the theme, in _includes/mermaid_config.js
+  version: "9.1.6"
-#   # See also docs/ui-components/code
+  # Put any additional configuration, such as setting the theme, in _includes/mermaid_config.js
+  # See also docs/ui-components/code
 
 # Enable or disable heading anchors
 heading_anchors: true
@@ -106,6 +129,23 @@ gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into t
 # Color scheme currently only supports "dark", "light"/nil (default), or a custom scheme that you define
 color_scheme: nil
 
+callouts_level: quiet # or loud
+callouts:
+  highlight:
+    color: yellow
+  important:
+    title: Important
+    color: blue
+  new:
+    title: New
+    color: green
+  note:
+    title: Note
+    color: purple
+  warning:
+    title: Warning
+    color: red
+
 # Google Analytics Tracking (optional)
 # e.g, UA-1234567-89
 ga_tracking: UA-2709176-10

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

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

_includes/head.html

@@ -27,14 +27,14 @@
   {% endif %}
 
   {% if site.search_enabled != false %}
-    <script type="text/javascript" src="{{ '/assets/js/vendor/lunr.min.js' | relative_url }}"></script>
+    <script src="{{ '/assets/js/vendor/lunr.min.js' | relative_url }}"></script>
   {% endif %}
 
   {% if site.mermaid %}
     <script src="https://cdn.jsdelivr.net/npm/mermaid@{{ site.mermaid.version }}/dist/mermaid.min.js"></script>
   {% endif %}
 
-  <script type="text/javascript" src="{{ '/assets/js/just-the-docs.js' | relative_url }}"></script>
+  <script src="{{ '/assets/js/just-the-docs.js' | relative_url }}"></script>
 
   <meta name="viewport" content="width=device-width, initial-scale=1">
 

_includes/nav.html

@@ -1,89 +1,169 @@
-<ul class="nav-list">
+{%- comment -%}
-  {%- assign titled_pages = include.pages
+  The `nav_order` values of pages affect the order in which they are shown in
-        | where_exp:"item", "item.title != nil" -%}
+  the navigation panel and in the automatically generated tables of contents.
+  Sibling pages with the same `nav_order` value may be shown in any order.
+  Sibling pages with no `nav_order` value are shown after all pages that have
+  explicit `nav_order` values, ordered by their `title` values.
   
-  {%- comment -%}
+  The `nav_order` and `title` values can be numbers or strings. To avoid build
-    The values of `title` and `nav_order` can be numbers or strings.
+  failures, we sort numbers and strings separately. We sort numbers by their
-    Jekyll gives build failures when sorting on mixtures of different types,
+  values, and strings lexicographically. The case-sensitivity of string sorting
-    so numbers and strings need to be sorted separately.
+  is determined by the configuration setting of `nav_sort`. Pages with no `title`
+  value are excluded from the navigation.
 
-    Here, numbers are sorted by their values, and come before all strings.
+  Note: Numbers used as `title` or `nav_order` values should not be in quotes,
-    An omitted `nav_order` value is equivalent to the page's `title` value
+  unless you intend them to be lexicographically ordered. Numbers are written
-    (except that a numerical `title` value is treated as a string).
+  without spaces or thousands-separators. Negative numbers are preceded by `-`.
+  Floats are written with the integral and fractional parts separated by `.`.
+  (Bounds on the magnitude and precision are presumably the same as in Liquid.)
+{%- endcomment -%}
 
-    The case-sensitivity of string sorting is determined by `site.nav_sort`.
+{%- assign title_pages = include.pages
-  {%- endcomment -%}
+      | where_exp: "item", "item.title != nil" -%}
 
-  {%- assign string_ordered_pages = titled_pages
+{%- comment -%}
-        | where_exp:"item", "item.nav_order == nil" -%}
+  A page with `nav_exclude: true` does not appear in the main navigation.
-  {%- assign nav_ordered_pages = titled_pages
+  If it has a `parent`, it may appear in the parent's table of contents.
-        | where_exp:"item", "item.nav_order != nil"  -%}
+  If it specifies `has_children: true`, it should appear in the breadcrumbs
+  of the child pages, but its order in relation to other pages is irrelevant.
+  Pages that never appear can be removed from the pages that need to be sorted.
+  This optimisation can be significant on a site with many pages.
   
-  {%- comment -%}
+  In Jekyll 4, the pages to be sorted can be filtered by:
-    The nav_ordered_pages have to be added to number_ordered_pages and
+  
-    string_ordered_pages, depending on the nav_order value.
+  {%- assign title_pages = title_pages
-    The first character of the jsonify result is `"` only for strings.
+        | where_exp: "item", "item.nav_exclude != true or item.parent != nil" -%}
-  {%- endcomment -%}
+  
-  {%- assign nav_ordered_groups = nav_ordered_pages
+  That filter is not allowed in Jekyll 3. The following iterative code gives the
-        | group_by_exp:"item", "item.nav_order | jsonify | slice: 0" -%}
+  same effect, but it is activated only when it will filter more than 50% of the
-  {%- assign number_ordered_pages = "" | split:"X" -%}
+  pages.
-  {%- for group in nav_ordered_groups -%}
+{%- endcomment -%}
+
+{%- assign unsorted_pages = title_pages
+      | where_exp: "item", "item.parent == nil" 
+      | where_exp: "item", "item.nav_exclude == true"-%}
+{%- assign title_pages_size = title_pages.size -%}
+{%- assign unsorted_pages_percent = unsorted_pages.size
+      | times: 100 | divided_by: title_pages_size -%}
+{%- if unsorted_pages_percent > 50 -%}
+  {%- assign sorted_pages = "" | split: "" -%}
+  {%- for item in title_pages -%}
+    {%- if item.nav_exclude != true or item.parent -%}
+      {%- assign sorted_pages = sorted_pages | push: item -%}
+    {%- endif -%}
+  {%- endfor -%}
+  {%- assign title_pages = sorted_pages -%}
+{%- endif -%}
+
+{%- assign nav_order_pages = title_pages
+      | where_exp: "item", "item.nav_order != nil"  -%}
+{%- assign title_order_pages = title_pages
+      | where_exp: "item", "item.nav_order == nil" -%}
+
+{%- comment -%}
+  Divide the arrays of `nav_order_pages` and `title_order_pages` according to
+  the type of value.
+  
+  The first character of the result of `jsonify` is `"` only for strings.
+  Grouping by a single character also ensures the number of groups is small.
+{%- endcomment -%}
+
+{%- assign nav_number_pages = "" | split: "" -%}
+{%- assign nav_string_pages = "" | split: "" -%}
+{%- assign nav_order_groups = nav_order_pages
+      | group_by_exp: "item", "item.nav_order | jsonify | slice: 0" -%}
+{%- for group in nav_order_groups -%}
   {%- if group.name == '"' -%}
-      {%- assign string_ordered_pages = string_ordered_pages | concat: group.items -%}
+    {%- assign nav_string_pages = group.items -%}
   {%- else -%}
-      {%- assign number_ordered_pages = number_ordered_pages | concat: group.items -%}
+    {%- assign nav_number_pages = nav_number_pages | concat: group.items -%}
   {%- endif -%}
-  {%- endfor -%}
+{%- endfor -%}
 
-  {%- assign sorted_number_ordered_pages = number_ordered_pages | sort:"nav_order" -%}
+{%- unless nav_number_pages == empty -%}
+  {%- assign nav_number_pages = nav_number_pages | sort: "nav_order" -%}
+{%- endunless -%}
 
-  {%- comment -%}
+{%- unless nav_string_pages == empty -%}
-    The string_ordered_pages have to be sorted by nav_order, and otherwise title
-    (where appending the empty string to a numeric title converts it to a string).
-    After grouping them by those values, the groups are sorted, then the items
-    of each group are concatenated.
-  {%- endcomment -%}
-  {%- assign string_ordered_groups = string_ordered_pages
-        | group_by_exp:"item", "item.nav_order | default: item.title | append:''" -%}
   {%- if site.nav_sort == 'case_insensitive' -%}
-    {%- assign sorted_string_ordered_groups = string_ordered_groups | sort_natural:"name" -%}
+    {%- assign nav_string_pages = nav_string_pages | sort_natural: "nav_order" -%}
   {%- else -%}
-    {%- assign sorted_string_ordered_groups = string_ordered_groups | sort:"name" -%}
+    {%- assign nav_string_pages = nav_string_pages | sort: "nav_order" -%}
   {%- endif -%}
-  {%- assign sorted_string_ordered_pages = "" | split:"X" -%}
+{%- endunless -%}
-  {%- for group in sorted_string_ordered_groups -%}
-    {%- assign sorted_string_ordered_pages = sorted_string_ordered_pages | concat: group.items -%}
-  {%- endfor -%}
 
-  {%- assign pages_list = sorted_number_ordered_pages | concat: sorted_string_ordered_pages -%}
+{%- assign title_number_pages = "" | split: "" -%}
+{%- assign title_string_pages = "" | split: "" -%}
+{%- assign title_order_groups = title_order_pages
+      | group_by_exp: "item", "item.title | jsonify | slice: 0" -%}
+{%- for group in title_order_groups -%}
+  {%- if group.name == '"' -%}
+    {%- assign title_string_pages = group.items -%}
+  {%- else -%}
+    {%- assign title_number_pages = title_number_pages | concat: group.items -%}
+  {%- endif -%}
+{%- endfor -%}
 
-  {%- for node in pages_list -%}
+{%- unless title_number_pages == empty -%}
-    {%- if node.parent == nil -%}
+  {%- assign title_number_pages = title_number_pages | sort: "title" -%}
+{%- endunless -%}
+
+{%- unless title_string_pages == empty -%}
+  {%- if site.nav_sort == 'case_insensitive' -%}
+    {%- assign title_string_pages = title_string_pages | sort_natural: "title" -%}
+  {%- else -%}
+    {%- assign title_string_pages = title_string_pages | sort: "title" -%}
+  {%- endif -%}
+{%- endunless -%}
+
+{%- assign pages_list = nav_number_pages | concat: nav_string_pages
+      | concat: title_number_pages | concat: title_string_pages -%}
+
+{%- assign first_level_pages = pages_list
+      | where_exp: "item", "item.parent == nil" -%}
+{%- assign second_level_pages = pages_list
+      | where_exp: "item", "item.parent != nil"
+      | where_exp: "item", "item.grand_parent == nil" -%}
+{%- assign third_level_pages = pages_list
+      | where_exp: "item", "item.grand_parent != nil" -%}
+
+{%- comment -%}
+  The order of sibling pages in `pages_list` determines the order of display of
+  links to them in lists of navigation links and in auto-generated TOCs.
+{%- endcomment -%}
+
+<ul class="nav-list">
+{%- for node in first_level_pages -%}
     {%- unless node.nav_exclude -%}
       <li class="nav-list-item{% if page.collection == include.key and page.url == node.url or page.parent == node.title or page.grand_parent == node.title %} active{% endif %}">
         {%- if node.has_children -%}
-          <a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a>
+          <a href="#" class="nav-list-expander" aria-label="toggle links in {{ node.title }} category">
+            <svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg>
+          </a>
         {%- endif -%}
         <a href="{{ node.url | relative_url }}" class="nav-list-link{% if page.url == node.url %} active{% endif %}">{{ node.title }}</a>
         {%- if node.has_children -%}
+          {%- assign children_list = second_level_pages
+                | where: "parent", node.title -%}
           {%- if node.child_nav_order == 'desc' -%}
-            {%- assign children_list = pages_list | where: "parent", node.title | where_exp:"item", "item.grand_parent == nil" | reverse -%}
+            {%- assign children_list = children_list | reverse -%}
-          {%- else -%}
-            {%- assign children_list = pages_list | where: "parent", node.title | where_exp:"item", "item.grand_parent == nil" -%}
           {%- endif -%}
           <ul class="nav-list ">
           {%- for child in children_list -%}
             {%- unless child.nav_exclude -%}
             <li class="nav-list-item {% if page.url == child.url or page.parent == child.title %} active{% endif %}">
               {%- if child.has_children -%}
-                <a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a>
+                <a href="#" class="nav-list-expander" aria-label="toggle links in {{ child.title }} category">
+                  <svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg>
+                </a>
               {%- endif -%}
               <a href="{{ child.url | relative_url }}" class="nav-list-link{% if page.url == child.url %} active{% endif %}">{{ child.title }}</a>
               {%- if child.has_children -%}
-                {%- if node.child_nav_order == 'desc' -%}
+                {%- assign grand_children_list = third_level_pages
-                {%- assign grand_children_list = pages_list | where: "parent", child.title | where: "grand_parent", node.title | reverse -%}
+                      | where: "parent", child.title
-                {%- else -%}
+                      | where: "grand_parent", node.title -%}
-                {%- assign grand_children_list = pages_list | where: "parent", child.title | where: "grand_parent", node.title -%}
+                {%- if child.child_nav_order == 'desc' -%}
+                  {%- assign grand_children_list = grand_children_list | reverse -%}
                 {%- endif -%}
                 <ul class="nav-list">
                 {%- for grand_child in grand_children_list -%}
@@ -102,28 +182,37 @@
         {%- endif -%}
       </li>
     {%- endunless -%}
-    {%- endif -%}
+{%- endfor -%}
-  {%- endfor -%}
+{%- assign nav_external_links = site.nav_external_links -%}
-  {%- assign nav_external_links = site.nav_external_links -%}
+{%- for node in nav_external_links -%}
-  {%- for node in nav_external_links -%}
       <li class="nav-list-item external">
         <a href="{{ node.url | absolute_url }}" class="nav-list-link external">
           {{ node.title }}
           {% unless node.hide_icon %}<svg viewBox="0 0 24 24" aria-labelledby="svg-external-link-title"><use xlink:href="#svg-external-link"></use></svg>{% endunless %}
         </a>
       </li>
-  {%- endfor -%}
+{%- endfor -%}
 </ul>
 
-{%- if page.collection == include.key -%}
+{%- comment -%}
+  `page.collection` is the name of the Jekyll collection that contains the page,
+  if any, and otherwise nil. Similarly for `include.key`.
   
-  {%- for node in pages_list -%}
+  If the current page is in the collection (if any) whose navigation is currently
-    {%- if node.parent == nil -%}
+  being generated, the following code sets `first_level_url` to the URL used in
+  the page's top-level breadcrumb (if any), and `second_level_url` to that used
+  in the page's second-level breadcrumb (if any).
+  
+  For pages with children, the code also sets `toc_list` to the list of child pages.
+{%- endcomment -%}
+
+{%- if page.collection == include.key -%}
+  {%- for node in first_level_pages -%}
       {%- if page.grand_parent == node.title or page.parent == node.title and page.grand_parent == nil -%}
         {%- assign first_level_url = node.url | relative_url -%}
       {%- endif -%}
       {%- if node.has_children -%}
-        {%- assign children_list = pages_list | where: "parent", node.title -%}
+        {%- assign children_list = second_level_pages | where: "parent", node.title -%}
         {%- for child in children_list -%}
           {%- if child.has_children -%}
             {%- if page.url == child.url or page.parent == child.title and page.grand_parent == child.parent -%}
@@ -132,11 +221,13 @@
           {%- endif -%}
         {%- endfor -%}
       {%- endif -%}
-    {%- endif -%}
   {%- endfor -%}
-
+  {%- if page.has_children == true and page.has_toc != false -%}
-  {% if page.has_children == true and page.has_toc != false %}
+    {%- assign toc_list = pages_list
-    {%- assign toc_list = pages_list | where: "parent", page.title | where: "grand_parent", page.parent -%}
+          | where: "parent", page.title
+          | where: "grand_parent", page.parent -%}
+    {%- if page.child_nav_order == "desc" -%}
+      {%- assign toc_list = toc_list | reverse -%}
+    {%- endif -%}
   {%- endif -%}
-
 {%- endif -%}

_includes/toc_heading_custom.html

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

_layouts/default.html

@@ -7,6 +7,7 @@ layout: table_wrappers
 <html lang="{{ site.lang | default: 'en-US' }}">
 {% include head.html %}
 <body>
+  <a class="skip-to-main" href="#main-content">Skip to main content</a>
   <svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
     <symbol id="svg-link" viewBox="0 0 24 24">
       <title>Link</title>
@@ -48,7 +49,7 @@ layout: table_wrappers
         <svg viewBox="0 0 24 24" class="icon"><use xlink:href="#svg-menu"></use></svg>
       </a>
     </div>
-    <nav role="navigation" aria-label="Main" id="site-nav" class="site-nav">
+    <nav aria-label="Main" id="site-nav" class="site-nav">
       {% assign pages_top_size = site.html_pages
           | where_exp:"item", "item.title != nil"
           | where_exp:"item", "item.parent == nil"
@@ -111,6 +112,8 @@ layout: table_wrappers
           </div>
           <div id="search-results" class="search-results"></div>
         </div>
+      {% else %}
+        <div></div>
       {% endif %}
       {% include header_custom.html %}
       {% if site.aux_links %}
@@ -156,7 +159,7 @@ layout: table_wrappers
 
         {% if page.has_children == true and page.has_toc != false %}
           <hr>
-          <h2 class="text-delta">Table of contents</h2>
+          {% include toc_heading_custom.html %}
           <ul>
             {% for child in toc_list %}
               <li>
@@ -214,12 +217,13 @@ layout: table_wrappers
       <div class="search-overlay"></div>
     {% endif %}
   </div>
-</body>
+
-{% if site.mermaid %}
+  {% if site.mermaid %}
   <script>
     var config = {% include mermaid_config.js %};
     mermaid.initialize(config);
     window.mermaid.init(undefined, document.querySelectorAll('.language-mermaid'));
   </script>
-{% endif %}
+  {% endif %}
+</body>
 </html>

_sass/base.scss

@@ -65,18 +65,12 @@ a {
 }
 
 a:not([class]) {
-  text-decoration: none;
+  text-decoration: underline;
-  background-image: linear-gradient($border-color 0%, $border-color 100%);
+  text-decoration-color: $border-color;
-  background-repeat: repeat-x;
+  text-underline-offset: 2px;
-  background-position: 0 100%;
-  background-size: 1px 1px;
 
   &:hover {
-    background-image: linear-gradient(
+    text-decoration-color: rgba($link-color, 0.45);
-      rgba($link-color, 0.45) 0%,
-      rgba($link-color, 0.45) 100%
-    );
-    background-size: 1px 1px;
   }
 }
 
@@ -107,3 +101,14 @@ hr {
   background-color: $border-color;
   border: 0;
 }
+
+// adds a GitHub-style sidebar to blockquotes
+blockquote {
+  margin: 10px 0;
+
+  // resets user-agent stylesheets for blockquotes
+  margin-block-start: 0;
+  margin-inline-start: 0;
+  padding-left: 15px;
+  border-left: 3px solid $border-color;
+}

_sass/code.scss

@@ -48,7 +48,7 @@ a:visited code {
 
 // ```[LANG]...```
 div.highlighter-rouge,
-div.listingblock {
+div.listingblock > div.content {
   padding: $sp-3;
   margin-top: 0;
   margin-bottom: $sp-3;
@@ -106,6 +106,7 @@ figure.highlight {
   }
 
   td.gl {
+    width: 1em;
     padding-right: $sp-3;
   }
 
@@ -119,7 +120,8 @@ figure.highlight {
 // Code examples (rendered)
 //
 
-.code-example {
+.code-example,
+.listingblock > .title {
   padding: $sp-3;
   margin-bottom: $sp-3;
   overflow: auto;
@@ -128,6 +130,7 @@ figure.highlight {
 
   + .highlighter-rouge,
   + .sectionbody .listingblock,
+  + .content,
   + figure.highlight {
     position: relative;
     margin-top: -$sp-4;

_sass/modules.scss

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

_sass/skiptomain.scss

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

docs/customization.md

@@ -58,6 +58,17 @@ You can add custom schemes.
 If you want to add a scheme named `foo` (can be any name) just add a file `_sass/color_schemes/foo.scss` (replace `foo` by your scheme name)
 where you override theme variables to change colors, fonts, spacing, etc.
 
+{: .note }
+Since the default color scheme is `light`, your custom scheme is implicitly based on the variable settings used by the `light` scheme.
+
+If you want your custom scheme to be based on the `dark` scheme, you need to start your file with the following line:
+
+```scss
+@import "./color_schemes/dark";
+```
+
+You can define custom schemes based on other custom schemes in the same way.
+
 Available variables are listed in the [\_variables.scss](https://github.com/just-the-docs/just-the-docs/tree/main/_sass/support/_variables.scss) file.
 
 For example, to change the link color from the purple default to blue, include the following inside your scheme file:
@@ -129,17 +140,33 @@ For example, if you'd like to add your own styles for printing a page, you could
 
 ## Override includes
 
-The site can be modified by overriding any of the custom [Jekyll includes](https://jekyllrb.com/docs/includes/) provided by default in the theme.
+You can customize the theme by overriding any of the custom [Jekyll includes](https://jekyllrb.com/docs/includes/) files that it provides.
 
-To do this, create an `_includes` directory and make a copy of the specific file you wish to modify. Any content added to this file will override the theme defaults. You can learn more about this process in the Jekyll docs for [Overriding theme defaults](https://jekyllrb.com/docs/themes/#overriding-theme-defaults).
+To do this, create an `_includes` directory and make a copy of the specific file you wish to modify. The content in this file will override the theme defaults. You can learn more about this process in the Jekyll docs for [Overriding theme defaults](https://jekyllrb.com/docs/themes/#overriding-theme-defaults).
 
-The following includes were made available to you:
+Just the Docs provides the following custom includes files:
+
+### Custom TOC Heading
+
+`_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.
+
+#### Example
+{: .no_toc }
+
+To change the default TOC heading to "Contents", create `_includes/toc_heading_custom.html` and add:
+```html
+<h2 class="text-delta">Contents</h2>
+```
+
+The (optional) `text-delta` class makes the heading appear as **Contents**{:.text-delta} .
 
 ### Custom Footer
 
 `_includes/footer_custom.html`
 
-This content appears at the bottom of every page's main content. More info for this include can be found in the [Configuration - Footer content]({% link docs/configuration.md %}#footer-content).
+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).
 
 ### Custom Head
 
@@ -148,6 +175,7 @@ This content appears at the bottom of every page's main content. More info for t
 Any HTML added to this file will be inserted before the closing `<head>` tag. This might include additional `<meta>`, `<link>`, or `<script>` tags.
 
 #### Example
+{: .no_toc }
 
 To add a custom favicon, create `_includes/head_custom.html` and add:
 ```html
@@ -165,3 +193,29 @@ Content added to this file appears at the top of every page's main content betwe
 `_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
+
+`_includes/search_placeholder_custom.html`
+
+Content added to this file will replace the default placeholder text in the search bar (and its `aria-label`), after stripping HTML and leading/trailing whitespace. By default, the content of the include is:
+
+{% raw %}
+
+```liquid
+Search {{site.title}}
+```
+
+{% endraw %}
+
+Override this file to render a custom placeholder. One common use-case is internationalization; for example,
+
+{% raw %}
+
+```liquid
+Chercher notre site
+```
+
+{% endraw %}
+
+would make the placeholder text "Chercher notre site". [Liquid code](https://jekyllrb.com/docs/liquid/) (including [Jekyll variables](https://jekyllrb.com/docs/variables/)) is also supported.

docs/navigation-structure.md

@@ -44,11 +44,10 @@ nav_order: 4
 
 The parameter values determine the order of the top-level pages, and of child pages with the same parent. You can reuse the same parameter values (e.g., integers starting from 1) for the child pages of different parents.
 
-The parameter values can be numbers (integers, floats) and/or strings. When you omit `nav_order` parameters, they default to the titles of the pages, which are ordered alphabetically. Pages with numerical `nav_order` parameters always come before those with strings or default `nav_order` parameters. If you want to make the page order independent of the page titles, you can set explicit `nav_order` parameters on all pages.
+The parameter values can be numbers (integers, floats) and/or strings. Pages with numerical `nav_order` parameters always come before those with string `nav_order` parameters. When you omit `nav_order` parameters, they default to the titles of the pages. If you want to make the page order independent of the page titles, you can set explicit `nav_order` parameters on all pages. All pages with explicit `nav_order` parameters
+come before all pages ordered by their `title` values.
 
-By default, all Capital letters come before all lowercase letters; you can add `nav_sort: case_insensitive` in the configuration file to ignore the case. Enclosing strings in quotation marks is optional.
+By default, all Capital letters come before all lowercase letters; you can add `nav_sort: case_insensitive` in the configuration file to ignore the case. Enclosing strings in (single or double) quotation marks is optional. Numeric values are not enclosed in quotation marks, e.g., `42`, `-1.0`; numbers in quotation marks are lexicographically ordered, so `"10"` comes before `"2"`, for example.
-
-> _Note for users of previous versions:_ `nav_sort: case_insensitive` previously affected the ordering of numerical `nav_order` parameters: e.g., `10` came before `2`. Also, all pages with explicit `nav_order` parameters previously came before all pages with default parameters. Both were potentially confusing, and they have now been eliminated.
 
 ---
 
@@ -70,7 +69,7 @@ nav_exclude: true
 
 The `nav_exclude` parameter does not affect the [auto-generating list of child pages](#auto-generating-table-of-contents), which you can use to access pages excluded from the main navigation.
 
-Pages with no `title` are automatically excluded from the navigation.
+Pages with no `title` are automatically excluded from the main navigation.
 
 ---
 
@@ -229,6 +228,9 @@ This would create the following navigation structure:
 +-- ..
 ```
 
+{: .note }
+Currently, the navigation structure is limited to 3 levels: grandchild pages cannot themselves have child pages.
+
 ---
 
 ## Auxiliary Links

docs/search.md

@@ -5,15 +5,13 @@ nav_order: 7
 ---
 
 # Search
-
 {: .no_toc }
 
 ## Table of contents
-
 {: .no_toc .text-delta }
 
 1. TOC
-   {:toc}
+{:toc}
 
 ---
 

docs/ui-components/callouts.md

@@ -9,7 +9,10 @@ nav_order: 7
 
 Markdown does not include support for callouts. However, you can style text as a callout using a Markdown extension supported by kramdown: [*block IALs*](https://kramdown.gettalong.org/quickref.html#block-attributes). 
 
-Common kinds of callouts include `admonition`, `attention`, `caution`, `danger`, `error`, `hint`, `important`, `note`, `tip`, and `warning`.
+Common kinds of callouts include `highlight`, `important`, `new`, `note`, and `warning`.
+
+{: .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]
 
@@ -24,6 +27,10 @@ When you have [configured]({{ site.baseurl }}{% link docs/configuration.md %}#ca
 A paragraph
 ```
 
+{: .highlight }
+A paragraph
+
+
 #### A single paragraph callout
 {: .no_toc }
 
@@ -32,6 +39,9 @@ A paragraph
 A paragraph
 ```
 
+{: .note }
+A paragraph
+
 ```markdown
 {: .note-title }
 > My note title
@@ -39,6 +49,11 @@ A paragraph
 > A paragraph with a custom title callout
 ```
 
+{: .note-title }
+> My note title
+>
+> A paragraph with a custom title callout
+
 #### A multi-paragraph callout
 {: .no_toc }
 
@@ -51,6 +66,13 @@ A paragraph
 > The last paragraph
 ```
 
+{: .important }
+> A paragraph
+>
+> Another paragraph
+>
+> The last paragraph
+
 ```markdown
 {: .important-title }
 > My important title
@@ -62,19 +84,31 @@ A paragraph
 > The last paragraph
 ```
 
+{: .important-title }
+> My important title
+>
+> A paragraph
+>
+> Another paragraph
+>
+> The last paragraph
+
 #### An indented callout
 {: .no_toc }
 
 ```markdown
-> {: .hint }
+> {: .highlight }
   A paragraph
 ```
 
+> {: .highlight }
+  A paragraph
+
 #### Indented multi-paragraph callouts
 {: .no_toc }
 
 ```markdown
-> {: .attention }
+> {: .new }
 > > A paragraph
 > >
 > > Another paragraph
@@ -82,6 +116,14 @@ A paragraph
 > > The last paragraph
 ```
 
+> {: .new }
+> > A paragraph
+> >
+> > Another paragraph
+> >
+> > The last paragraph
+
+
 #### Nested callouts
 {: .no_toc }
 
@@ -91,6 +133,10 @@ A paragraph
 > A paragraph
 ```
 
+{: .important }
+> {: .warning }
+> A paragraph
+
 #### Opaque background
 {: .no_toc }
 
@@ -102,3 +148,10 @@ A paragraph
 > A paragraph
 > </div>
 ```
+
+{: .important }
+> {: .opaque }
+> <div markdown="block">
+> {: .warning }
+> A paragraph
+> </div>

docs/ui-components/code.md

@@ -91,7 +91,7 @@ To demonstrate front end code, sometimes it's useful to show a rendered example
 
 ## Mermaid diagram code blocks
 
-[Mermaid](https://mermaid-js.github.io/mermaid/) allows you to add diagrams and visualizations using Markdown code blocks. You can turn on support for mermaid by adding a `mermaid` key to your `_config.yml`.
+[Mermaid](https://mermaid-js.github.io/mermaid/) allows you to add diagrams and visualizations using Markdown code blocks. **It is disabled by default**. However, you can turn on support for mermaid by adding a `mermaid` key to your `_config.yml`.
 
 The minimum configuration requires a `version` key (matching a version in [jsDelivr](https://cdn.jsdelivr.net/npm/mermaid/)):
 
@@ -131,3 +131,15 @@ graph TD;
     C-->D;
 ```
 {% endhighlight %}
+
+which renders:
+
+```mermaid
+graph TD;
+    A-->B;
+    A-->C;
+    B-->D;
+    C-->D;
+```
+
+*Note: for demonstration purposes, we've enabled mermaid on this site. It is still disabled by default, and users need to opt-in to use it.*

docs/ui-components/line-nos.md

@@ -103,13 +103,24 @@ end
 {% include fix_linenos.html code=code %}
 {% assign code = nil %}
 
-❌ With the default configuration options, the following example illustrates
+Narrow code stays close to the line numbers:
+
+{% capture code %}
+{% highlight ruby linenos %}
+def foo
+  puts 'foo'
+end
+{% endhighlight %}
+{% endcapture %}
+{% include fix_linenos.html code=code %}
+{% assign code = nil %}
+
+❌ With the compression options used for the theme docs, the following example illustrates
 the **incorrect** formatting arising from the incompatibility of HTML compression
 and the non-conforming HTML produced by Jekyll for line numbers:
 
 {% highlight ruby linenos %}
-# Ruby code with syntax highlighting and unfixed line numbers using Liquid
+def foo
-GitHubPages::Dependencies.gems.each do |gem, version|
+  puts 'foo'
-  s.add_dependency(gem, "= #{version}")
 end
 {% endhighlight %}

index.md

@@ -16,7 +16,20 @@ Just the Docs gives your documentation a jumpstart with a responsive Jekyll them
 
 ---
 
-**New: version `0.4.0.rc1` has just been released! See [the changelog](https://github.com/just-the-docs/just-the-docs/blob/main/CHANGELOG.md) for a detailed breakdown!**
+{: .new }
+> **Pre-release version `0.4.0.rc3` is available!**
+> See [the CHANGELOG]({{ site.baseurl }}{% link CHANGELOG.md %}) for a detailed breakdown.
+
+{: .warning }
+> Specifying `gem "just-the-docs"` in your `Gemfile` uses the latest ***release*** (`v0.3.3`), ignoring all pre-releases!
+> To use this pre-release, pin it:
+> ```ruby
+> gem "just-the-docs", "0.4.0.rc3"
+> ```
+> and/or
+> ```yaml
+> remote_theme: just-the-docs/just-the-docs@v0.4.0.rc3
+> ```
 
 ## Getting started
 

just-the-docs.gemspec

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

package-lock.json

@@ -10,9 +10,9 @@
       "license": "MIT",
       "devDependencies": {
         "prettier": "^2.7.1",
-        "stylelint": "^14.9.1",
+        "stylelint": "^14.13.0",
         "stylelint-config-prettier-scss": "0.0.1",
-        "stylelint-config-standard-scss": "^3.0.0",
+        "stylelint-config-standard-scss": "^5.0.0",
         "stylelint-prettier": "^2.0.0"
       }
     },
@@ -268,18 +268,6 @@
         "node": ">=4"
       }
     },
-    "node_modules/clone-regexp": {
-      "version": "2.2.0",
-      "resolved": "https://registry.npmjs.org/clone-regexp/-/clone-regexp-2.2.0.tgz",
-      "integrity": "sha512-beMpP7BOtTipFuW8hrJvREQ2DrRu3BE7by0ZpibtfBA+qfHYvMGTc2Yb1JMYPKg/JUw0CHYvpg796aNTSW9z7Q==",
-      "dev": true,
-      "dependencies": {
-        "is-regexp": "^2.0.0"
-      },
-      "engines": {
-        "node": ">=6"
-      }
-    },
     "node_modules/color-convert": {
       "version": "1.9.3",
       "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-1.9.3.tgz",
@@ -296,9 +284,9 @@
       "dev": true
     },
     "node_modules/colord": {
-      "version": "2.9.2",
+      "version": "2.9.3",
-      "resolved": "https://registry.npmjs.org/colord/-/colord-2.9.2.tgz",
+      "resolved": "https://registry.npmjs.org/colord/-/colord-2.9.3.tgz",
-      "integrity": "sha512-Uqbg+J445nc1TKn4FoDPS6ZZqAvEDnwrH42yo8B40JSOgSLxMZ/gt3h4nmCtPLQeXhjJJkqBx7SCY35WnIixaQ==",
+      "integrity": "sha512-jeC1axXpnb0/2nn/Y1LPuLdgXBLH7aDcHu4KEKfqw3CUhX7ZpfBSlPKyqXE6btIgEzfWtrX3/tyBCaCvXvMkOw==",
       "dev": true
     },
     "node_modules/concat-map": {
@@ -428,18 +416,6 @@
         "node": ">=0.8.0"
       }
     },
-    "node_modules/execall": {
-      "version": "2.0.0",
-      "resolved": "https://registry.npmjs.org/execall/-/execall-2.0.0.tgz",
-      "integrity": "sha512-0FU2hZ5Hh6iQnarpRtQurM/aAvp3RIbfvgLHrcqJYzhXyV2KFruhuChf9NC6waAhiUR7FFtlugkI4p7f2Fqlow==",
-      "dev": true,
-      "dependencies": {
-        "clone-regexp": "^2.1.0"
-      },
-      "engines": {
-        "node": ">=8"
-      }
-    },
     "node_modules/fast-deep-equal": {
       "version": "3.1.3",
       "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
@@ -453,9 +429,9 @@
       "dev": true
     },
     "node_modules/fast-glob": {
-      "version": "3.2.11",
+      "version": "3.2.12",
-      "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.2.11.tgz",
+      "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.2.12.tgz",
-      "integrity": "sha512-xrO3+1bxSo3ZVHAnqzyuewYT6aMFHRAd4Kcs92MAonjwQZLsK9d0SF1IyQ3k5PoirxTW0Oe/RqFgMQ6TcNE5Ew==",
+      "integrity": "sha512-DVj4CQIYYow0BlaelwK1pHl5n5cRSJfM60UA0zK891sVInoPri2Ekj7+e1CT3/3qxXenpI+nBBmQAcJPJgaj4w==",
       "dev": true,
       "dependencies": {
         "@nodelib/fs.stat": "^2.0.2",
@@ -469,10 +445,13 @@
       }
     },
     "node_modules/fastest-levenshtein": {
-      "version": "1.0.12",
+      "version": "1.0.16",
-      "resolved": "https://registry.npmjs.org/fastest-levenshtein/-/fastest-levenshtein-1.0.12.tgz",
+      "resolved": "https://registry.npmjs.org/fastest-levenshtein/-/fastest-levenshtein-1.0.16.tgz",
-      "integrity": "sha512-On2N+BpYJ15xIC974QNVuYGMOlEVt4s0EOI3wwMqOmK1fdDY+FN/zltPV8vosq4ad4c/gJ1KHScUn/6AWIgiow==",
+      "integrity": "sha512-eRnCtTTtGZFpQCwhJiUOuxPQWRXVKYDn0b2PeHfXL6/Zi53SLAzAHfVhVWK2AryC/WH05kGfxhFIPvTF0SXQzg==",
-      "dev": true
+      "dev": true,
+      "engines": {
+        "node": ">= 4.9.1"
+      }
     },
     "node_modules/fastq": {
       "version": "1.13.0",
@@ -551,18 +530,6 @@
       "integrity": "sha512-yIovAzMX49sF8Yl58fSCWJ5svSLuaibPxXQJFLmBObTuCr0Mf1KiPopGM9NiFjiYBCbfaa2Fh6breQ6ANVTI0A==",
       "dev": true
     },
-    "node_modules/get-stdin": {
-      "version": "8.0.0",
-      "resolved": "https://registry.npmjs.org/get-stdin/-/get-stdin-8.0.0.tgz",
-      "integrity": "sha512-sY22aA6xchAzprjyqmSEQv4UbAAzRN0L2dQB0NlN5acTTK9Don6nhoc3eAbUnpZiCANAMfd/+40kVdKfFygohg==",
-      "dev": true,
-      "engines": {
-        "node": ">=10"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
-      }
-    },
     "node_modules/glob": {
       "version": "7.2.0",
       "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.0.tgz",
@@ -747,7 +714,7 @@
     "node_modules/imurmurhash": {
       "version": "0.1.4",
       "resolved": "https://registry.npmjs.org/imurmurhash/-/imurmurhash-0.1.4.tgz",
-      "integrity": "sha1-khi5srkoojixPcT7a21XbyMUU+o=",
+      "integrity": "sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==",
       "dev": true,
       "engines": {
         "node": ">=0.8.19"
@@ -859,15 +826,6 @@
         "node": ">=0.10.0"
       }
     },
-    "node_modules/is-regexp": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/is-regexp/-/is-regexp-2.1.0.tgz",
-      "integrity": "sha512-OZ4IlER3zmRIoB9AqNhEggVxqIH4ofDns5nRrPS6yQxXE1TPCUpFznBfRQmQa8uC+pXqjMnukiJBxCisIxiLGA==",
-      "dev": true,
-      "engines": {
-        "node": ">=6"
-      }
-    },
     "node_modules/isexe": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
@@ -1223,9 +1181,9 @@
       }
     },
     "node_modules/postcss": {
-      "version": "8.4.14",
+      "version": "8.4.16",
-      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.4.14.tgz",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.4.16.tgz",
-      "integrity": "sha512-E398TUmfAYFPBSdzgeieK2Y1+1cpdxJx8yXbK/m57nRhKSmk1GB2tO4lbLBtlkfPQTDKfe4Xqv1ASWPpayPEig==",
+      "integrity": "sha512-ipHE1XBvKzm5xI7hiHCZJCSugxvsdq2mPnsq5+UF+VHCjiBvtDrlxJfMBToWaP9D5XlgNmcFGqoHmUn0EYEaRQ==",
       "dev": true,
       "funding": [
         {
@@ -1275,9 +1233,9 @@
       }
     },
     "node_modules/postcss-scss": {
-      "version": "4.0.3",
+      "version": "4.0.4",
-      "resolved": "https://registry.npmjs.org/postcss-scss/-/postcss-scss-4.0.3.tgz",
+      "resolved": "https://registry.npmjs.org/postcss-scss/-/postcss-scss-4.0.4.tgz",
-      "integrity": "sha512-j4KxzWovfdHsyxwl1BxkUal/O4uirvHgdzMKS1aWJBAV0qh2qj5qAZqpeBfVUYGWv+4iK9Az7SPyZ4fyNju1uA==",
+      "integrity": "sha512-aBBbVyzA8b3hUL0MGrpydxxXKXFZc5Eqva0Q3V9qsBOLEMsjb6w49WfpsoWzpEgcqJGW4t7Rio8WXVU9Gd8vWg==",
       "dev": true,
       "engines": {
         "node": ">=12.0"
@@ -1713,22 +1671,20 @@
       "dev": true
     },
     "node_modules/stylelint": {
-      "version": "14.9.1",
+      "version": "14.13.0",
-      "resolved": "https://registry.npmjs.org/stylelint/-/stylelint-14.9.1.tgz",
+      "resolved": "https://registry.npmjs.org/stylelint/-/stylelint-14.13.0.tgz",
-      "integrity": "sha512-RdAkJdPiLqHawCSnu21nE27MjNXaVd4WcOHA4vK5GtIGjScfhNnaOuWR2wWdfKFAvcWQPOYe311iveiVKSmwsA==",
+      "integrity": "sha512-NJSAdloiAB/jgVJKxMR90mWlctvmeBFGFVUvyKngi9+j/qPSJ5ZB+u8jOmGbLTnS7OHrII9NFGehPRyar8U5vg==",
       "dev": true,
       "dependencies": {
-        "@csstools/selector-specificity": "^2.0.1",
+        "@csstools/selector-specificity": "^2.0.2",
         "balanced-match": "^2.0.0",
-        "colord": "^2.9.2",
+        "colord": "^2.9.3",
         "cosmiconfig": "^7.0.1",
         "css-functions-list": "^3.1.0",
         "debug": "^4.3.4",
-        "execall": "^2.0.0",
+        "fast-glob": "^3.2.12",
-        "fast-glob": "^3.2.11",
+        "fastest-levenshtein": "^1.0.16",
-        "fastest-levenshtein": "^1.0.12",
         "file-entry-cache": "^6.0.1",
-        "get-stdin": "^8.0.0",
         "global-modules": "^2.0.0",
         "globby": "^11.1.0",
         "globjoin": "^0.1.4",
@@ -1743,7 +1699,7 @@
         "micromatch": "^4.0.5",
         "normalize-path": "^3.0.0",
         "picocolors": "^1.0.0",
-        "postcss": "^8.4.14",
+        "postcss": "^8.4.16",
         "postcss-media-query-parser": "^0.2.3",
         "postcss-resolve-nested-selector": "^0.1.1",
         "postcss-safe-parser": "^6.0.0",
@@ -1753,11 +1709,11 @@
         "string-width": "^4.2.3",
         "strip-ansi": "^6.0.1",
         "style-search": "^0.1.0",
-        "supports-hyperlinks": "^2.2.0",
+        "supports-hyperlinks": "^2.3.0",
         "svg-tags": "^1.0.0",
         "table": "^6.8.0",
         "v8-compile-cache": "^2.3.0",
-        "write-file-atomic": "^4.0.1"
+        "write-file-atomic": "^4.0.2"
       },
       "bin": {
         "stylelint": "bin/stylelint.js"
@@ -1806,51 +1762,51 @@
       }
     },
     "node_modules/stylelint-config-recommended": {
-      "version": "6.0.0",
+      "version": "8.0.0",
-      "resolved": "https://registry.npmjs.org/stylelint-config-recommended/-/stylelint-config-recommended-6.0.0.tgz",
+      "resolved": "https://registry.npmjs.org/stylelint-config-recommended/-/stylelint-config-recommended-8.0.0.tgz",
-      "integrity": "sha512-ZorSSdyMcxWpROYUvLEMm0vSZud2uB7tX1hzBZwvVY9SV/uly4AvvJPPhCcymZL3fcQhEQG5AELmrxWqtmzacw==",
+      "integrity": "sha512-IK6dWvE000+xBv9jbnHOnBq01gt6HGVB2ZTsot+QsMpe82doDQ9hvplxfv4YnpEuUwVGGd9y6nbaAnhrjcxhZQ==",
       "dev": true,
       "peerDependencies": {
-        "stylelint": "^14.0.0"
+        "stylelint": "^14.8.0"
       }
     },
     "node_modules/stylelint-config-recommended-scss": {
-      "version": "5.0.2",
+      "version": "7.0.0",
-      "resolved": "https://registry.npmjs.org/stylelint-config-recommended-scss/-/stylelint-config-recommended-scss-5.0.2.tgz",
+      "resolved": "https://registry.npmjs.org/stylelint-config-recommended-scss/-/stylelint-config-recommended-scss-7.0.0.tgz",
-      "integrity": "sha512-b14BSZjcwW0hqbzm9b0S/ScN2+3CO3O4vcMNOw2KGf8lfVSwJ4p5TbNEXKwKl1+0FMtgRXZj6DqVUe/7nGnuBg==",
+      "integrity": "sha512-rGz1J4rMAyJkvoJW4hZasuQBB7y9KIrShb20l9DVEKKZSEi1HAy0vuNlR8HyCKy/jveb/BdaQFcoiYnmx4HoiA==",
       "dev": true,
       "dependencies": {
         "postcss-scss": "^4.0.2",
-        "stylelint-config-recommended": "^6.0.0",
+        "stylelint-config-recommended": "^8.0.0",
         "stylelint-scss": "^4.0.0"
       },
       "peerDependencies": {
-        "stylelint": "^14.0.0"
+        "stylelint": "^14.4.0"
       }
     },
     "node_modules/stylelint-config-standard": {
-      "version": "24.0.0",
+      "version": "26.0.0",
-      "resolved": "https://registry.npmjs.org/stylelint-config-standard/-/stylelint-config-standard-24.0.0.tgz",
+      "resolved": "https://registry.npmjs.org/stylelint-config-standard/-/stylelint-config-standard-26.0.0.tgz",
-      "integrity": "sha512-+RtU7fbNT+VlNbdXJvnjc3USNPZRiRVp/d2DxOF/vBDDTi0kH5RX2Ny6errdtZJH3boO+bmqIYEllEmok4jiuw==",
+      "integrity": "sha512-hUuB7LaaqM8abvkOO84wh5oYSkpXgTzHu2Zza6e7mY+aOmpNTjoFBRxSLlzY0uAOMWEFx0OMKzr+reG1BUtcqQ==",
       "dev": true,
       "dependencies": {
-        "stylelint-config-recommended": "^6.0.0"
+        "stylelint-config-recommended": "^8.0.0"
       },
       "peerDependencies": {
-        "stylelint": "^14.0.0"
+        "stylelint": "^14.9.0"
       }
     },
     "node_modules/stylelint-config-standard-scss": {
-      "version": "3.0.0",
+      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/stylelint-config-standard-scss/-/stylelint-config-standard-scss-3.0.0.tgz",
+      "resolved": "https://registry.npmjs.org/stylelint-config-standard-scss/-/stylelint-config-standard-scss-5.0.0.tgz",
-      "integrity": "sha512-zt3ZbzIbllN1iCmc94e4pDxqpkzeR6CJo5DDXzltshuXr+82B8ylHyMMARNnUYrZH80B7wgY7UkKTYCFM0UUyw==",
+      "integrity": "sha512-zoXLibojHZYPFjtkc4STZtAJ2yGTq3Bb4MYO0oiyO6f/vNxDKRcSDZYoqN260Gv2eD5niQIr1/kr5SXlFj9kcQ==",
       "dev": true,
       "dependencies": {
-        "stylelint-config-recommended-scss": "^5.0.2",
+        "stylelint-config-recommended-scss": "^7.0.0",
-        "stylelint-config-standard": "^24.0.0"
+        "stylelint-config-standard": "^26.0.0"
       },
       "peerDependencies": {
-        "stylelint": "^14.0.0"
+        "stylelint": "^14.9.0"
       }
     },
     "node_modules/stylelint-prettier": {
@@ -1870,9 +1826,9 @@
       }
     },
     "node_modules/stylelint-scss": {
-      "version": "4.2.0",
+      "version": "4.3.0",
-      "resolved": "https://registry.npmjs.org/stylelint-scss/-/stylelint-scss-4.2.0.tgz",
+      "resolved": "https://registry.npmjs.org/stylelint-scss/-/stylelint-scss-4.3.0.tgz",
-      "integrity": "sha512-HHHMVKJJ5RM9pPIbgJ/XA67h9H0407G68Rm69H4fzFbFkyDMcTV1Byep3qdze5+fJ3c0U7mJrbj6S0Fg072uZA==",
+      "integrity": "sha512-GvSaKCA3tipzZHoz+nNO7S02ZqOsdBzMiCx9poSmLlb3tdJlGddEX/8QzCOD8O7GQan9bjsvLMsO5xiw6IhhIQ==",
       "dev": true,
       "dependencies": {
         "lodash": "^4.17.21",
@@ -1898,9 +1854,9 @@
       }
     },
     "node_modules/supports-hyperlinks": {
-      "version": "2.2.0",
+      "version": "2.3.0",
-      "resolved": "https://registry.npmjs.org/supports-hyperlinks/-/supports-hyperlinks-2.2.0.tgz",
+      "resolved": "https://registry.npmjs.org/supports-hyperlinks/-/supports-hyperlinks-2.3.0.tgz",
-      "integrity": "sha512-6sXEzV5+I5j8Bmq9/vUphGRM/RJNT9SCURJLjwfOg51heRtguGWDzcaBlgAzKhQa0EVNpPEKzQuBwZ8S8WaCeQ==",
+      "integrity": "sha512-RpsAZlpWcDwOPQA22aCH4J0t7L8JmAvsCxfOSEwm7cQs3LshN36QaTkwd70DnBOXDWGssw2eUoc8CaRWT0XunA==",
       "dev": true,
       "dependencies": {
         "has-flag": "^4.0.0",
@@ -2048,16 +2004,16 @@
       "dev": true
     },
     "node_modules/write-file-atomic": {
-      "version": "4.0.1",
+      "version": "4.0.2",
-      "resolved": "https://registry.npmjs.org/write-file-atomic/-/write-file-atomic-4.0.1.tgz",
+      "resolved": "https://registry.npmjs.org/write-file-atomic/-/write-file-atomic-4.0.2.tgz",
-      "integrity": "sha512-nSKUxgAbyioruk6hU87QzVbY279oYT6uiwgDoujth2ju4mJ+TZau7SQBhtbTmUyuNYTuXnSyRn66FV0+eCgcrQ==",
+      "integrity": "sha512-7KxauUdBmSdWnmpaGFg+ppNjKF8uNLry8LyzjauQDOVONfFLNKrKvQOxZ/VuTIcS/gge/YNahf5RIIQWTSarlg==",
       "dev": true,
       "dependencies": {
         "imurmurhash": "^0.1.4",
         "signal-exit": "^3.0.7"
       },
       "engines": {
-        "node": "^12.13.0 || ^14.15.0 || >=16"
+        "node": "^12.13.0 || ^14.15.0 || >=16.0.0"
       }
     },
     "node_modules/yallist": {
@@ -2275,15 +2231,6 @@
         "supports-color": "^5.3.0"
       }
     },
-    "clone-regexp": {
-      "version": "2.2.0",
-      "resolved": "https://registry.npmjs.org/clone-regexp/-/clone-regexp-2.2.0.tgz",
-      "integrity": "sha512-beMpP7BOtTipFuW8hrJvREQ2DrRu3BE7by0ZpibtfBA+qfHYvMGTc2Yb1JMYPKg/JUw0CHYvpg796aNTSW9z7Q==",
-      "dev": true,
-      "requires": {
-        "is-regexp": "^2.0.0"
-      }
-    },
     "color-convert": {
       "version": "1.9.3",
       "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-1.9.3.tgz",
@@ -2300,9 +2247,9 @@
       "dev": true
     },
     "colord": {
-      "version": "2.9.2",
+      "version": "2.9.3",
-      "resolved": "https://registry.npmjs.org/colord/-/colord-2.9.2.tgz",
+      "resolved": "https://registry.npmjs.org/colord/-/colord-2.9.3.tgz",
-      "integrity": "sha512-Uqbg+J445nc1TKn4FoDPS6ZZqAvEDnwrH42yo8B40JSOgSLxMZ/gt3h4nmCtPLQeXhjJJkqBx7SCY35WnIixaQ==",
+      "integrity": "sha512-jeC1axXpnb0/2nn/Y1LPuLdgXBLH7aDcHu4KEKfqw3CUhX7ZpfBSlPKyqXE6btIgEzfWtrX3/tyBCaCvXvMkOw==",
       "dev": true
     },
     "concat-map": {
@@ -2399,15 +2346,6 @@
       "integrity": "sha1-G2HAViGQqN/2rjuyzwIAyhMLhtQ=",
       "dev": true
     },
-    "execall": {
-      "version": "2.0.0",
-      "resolved": "https://registry.npmjs.org/execall/-/execall-2.0.0.tgz",
-      "integrity": "sha512-0FU2hZ5Hh6iQnarpRtQurM/aAvp3RIbfvgLHrcqJYzhXyV2KFruhuChf9NC6waAhiUR7FFtlugkI4p7f2Fqlow==",
-      "dev": true,
-      "requires": {
-        "clone-regexp": "^2.1.0"
-      }
-    },
     "fast-deep-equal": {
       "version": "3.1.3",
       "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
@@ -2421,9 +2359,9 @@
       "dev": true
     },
     "fast-glob": {
-      "version": "3.2.11",
+      "version": "3.2.12",
-      "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.2.11.tgz",
+      "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.2.12.tgz",
-      "integrity": "sha512-xrO3+1bxSo3ZVHAnqzyuewYT6aMFHRAd4Kcs92MAonjwQZLsK9d0SF1IyQ3k5PoirxTW0Oe/RqFgMQ6TcNE5Ew==",
+      "integrity": "sha512-DVj4CQIYYow0BlaelwK1pHl5n5cRSJfM60UA0zK891sVInoPri2Ekj7+e1CT3/3qxXenpI+nBBmQAcJPJgaj4w==",
       "dev": true,
       "requires": {
         "@nodelib/fs.stat": "^2.0.2",
@@ -2434,9 +2372,9 @@
       }
     },
     "fastest-levenshtein": {
-      "version": "1.0.12",
+      "version": "1.0.16",
-      "resolved": "https://registry.npmjs.org/fastest-levenshtein/-/fastest-levenshtein-1.0.12.tgz",
+      "resolved": "https://registry.npmjs.org/fastest-levenshtein/-/fastest-levenshtein-1.0.16.tgz",
-      "integrity": "sha512-On2N+BpYJ15xIC974QNVuYGMOlEVt4s0EOI3wwMqOmK1fdDY+FN/zltPV8vosq4ad4c/gJ1KHScUn/6AWIgiow==",
+      "integrity": "sha512-eRnCtTTtGZFpQCwhJiUOuxPQWRXVKYDn0b2PeHfXL6/Zi53SLAzAHfVhVWK2AryC/WH05kGfxhFIPvTF0SXQzg==",
       "dev": true
     },
     "fastq": {
@@ -2504,12 +2442,6 @@
       "integrity": "sha512-yIovAzMX49sF8Yl58fSCWJ5svSLuaibPxXQJFLmBObTuCr0Mf1KiPopGM9NiFjiYBCbfaa2Fh6breQ6ANVTI0A==",
       "dev": true
     },
-    "get-stdin": {
-      "version": "8.0.0",
-      "resolved": "https://registry.npmjs.org/get-stdin/-/get-stdin-8.0.0.tgz",
-      "integrity": "sha512-sY22aA6xchAzprjyqmSEQv4UbAAzRN0L2dQB0NlN5acTTK9Don6nhoc3eAbUnpZiCANAMfd/+40kVdKfFygohg==",
-      "dev": true
-    },
     "glob": {
       "version": "7.2.0",
       "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.0.tgz",
@@ -2642,7 +2574,7 @@
     "imurmurhash": {
       "version": "0.1.4",
       "resolved": "https://registry.npmjs.org/imurmurhash/-/imurmurhash-0.1.4.tgz",
-      "integrity": "sha1-khi5srkoojixPcT7a21XbyMUU+o=",
+      "integrity": "sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==",
       "dev": true
     },
     "indent-string": {
@@ -2727,12 +2659,6 @@
       "integrity": "sha512-VRSzKkbMm5jMDoKLbltAkFQ5Qr7VDiTFGXxYFXXowVj387GeGNOCsOH6Msy00SGZ3Fp84b1Naa1psqgcCIEP5Q==",
       "dev": true
     },
-    "is-regexp": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/is-regexp/-/is-regexp-2.1.0.tgz",
-      "integrity": "sha512-OZ4IlER3zmRIoB9AqNhEggVxqIH4ofDns5nRrPS6yQxXE1TPCUpFznBfRQmQa8uC+pXqjMnukiJBxCisIxiLGA==",
-      "dev": true
-    },
     "isexe": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
@@ -3000,9 +2926,9 @@
       "dev": true
     },
     "postcss": {
-      "version": "8.4.14",
+      "version": "8.4.16",
-      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.4.14.tgz",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.4.16.tgz",
-      "integrity": "sha512-E398TUmfAYFPBSdzgeieK2Y1+1cpdxJx8yXbK/m57nRhKSmk1GB2tO4lbLBtlkfPQTDKfe4Xqv1ASWPpayPEig==",
+      "integrity": "sha512-ipHE1XBvKzm5xI7hiHCZJCSugxvsdq2mPnsq5+UF+VHCjiBvtDrlxJfMBToWaP9D5XlgNmcFGqoHmUn0EYEaRQ==",
       "dev": true,
       "requires": {
         "nanoid": "^3.3.4",
@@ -3030,9 +2956,9 @@
       "requires": {}
     },
     "postcss-scss": {
-      "version": "4.0.3",
+      "version": "4.0.4",
-      "resolved": "https://registry.npmjs.org/postcss-scss/-/postcss-scss-4.0.3.tgz",
+      "resolved": "https://registry.npmjs.org/postcss-scss/-/postcss-scss-4.0.4.tgz",
-      "integrity": "sha512-j4KxzWovfdHsyxwl1BxkUal/O4uirvHgdzMKS1aWJBAV0qh2qj5qAZqpeBfVUYGWv+4iK9Az7SPyZ4fyNju1uA==",
+      "integrity": "sha512-aBBbVyzA8b3hUL0MGrpydxxXKXFZc5Eqva0Q3V9qsBOLEMsjb6w49WfpsoWzpEgcqJGW4t7Rio8WXVU9Gd8vWg==",
       "dev": true,
       "requires": {}
     },
@@ -3337,22 +3263,20 @@
       "dev": true
     },
     "stylelint": {
-      "version": "14.9.1",
+      "version": "14.13.0",
-      "resolved": "https://registry.npmjs.org/stylelint/-/stylelint-14.9.1.tgz",
+      "resolved": "https://registry.npmjs.org/stylelint/-/stylelint-14.13.0.tgz",
-      "integrity": "sha512-RdAkJdPiLqHawCSnu21nE27MjNXaVd4WcOHA4vK5GtIGjScfhNnaOuWR2wWdfKFAvcWQPOYe311iveiVKSmwsA==",
+      "integrity": "sha512-NJSAdloiAB/jgVJKxMR90mWlctvmeBFGFVUvyKngi9+j/qPSJ5ZB+u8jOmGbLTnS7OHrII9NFGehPRyar8U5vg==",
       "dev": true,
       "requires": {
-        "@csstools/selector-specificity": "^2.0.1",
+        "@csstools/selector-specificity": "^2.0.2",
         "balanced-match": "^2.0.0",
-        "colord": "^2.9.2",
+        "colord": "^2.9.3",
         "cosmiconfig": "^7.0.1",
         "css-functions-list": "^3.1.0",
         "debug": "^4.3.4",
-        "execall": "^2.0.0",
+        "fast-glob": "^3.2.12",
-        "fast-glob": "^3.2.11",
+        "fastest-levenshtein": "^1.0.16",
-        "fastest-levenshtein": "^1.0.12",
         "file-entry-cache": "^6.0.1",
-        "get-stdin": "^8.0.0",
         "global-modules": "^2.0.0",
         "globby": "^11.1.0",
         "globjoin": "^0.1.4",
@@ -3367,7 +3291,7 @@
         "micromatch": "^4.0.5",
         "normalize-path": "^3.0.0",
         "picocolors": "^1.0.0",
-        "postcss": "^8.4.14",
+        "postcss": "^8.4.16",
         "postcss-media-query-parser": "^0.2.3",
         "postcss-resolve-nested-selector": "^0.1.1",
         "postcss-safe-parser": "^6.0.0",
@@ -3377,11 +3301,11 @@
         "string-width": "^4.2.3",
         "strip-ansi": "^6.0.1",
         "style-search": "^0.1.0",
-        "supports-hyperlinks": "^2.2.0",
+        "supports-hyperlinks": "^2.3.0",
         "svg-tags": "^1.0.0",
         "table": "^6.8.0",
         "v8-compile-cache": "^2.3.0",
-        "write-file-atomic": "^4.0.1"
+        "write-file-atomic": "^4.0.2"
       }
     },
     "stylelint-config-prettier": {
@@ -3401,40 +3325,40 @@
       }
     },
     "stylelint-config-recommended": {
-      "version": "6.0.0",
+      "version": "8.0.0",
-      "resolved": "https://registry.npmjs.org/stylelint-config-recommended/-/stylelint-config-recommended-6.0.0.tgz",
+      "resolved": "https://registry.npmjs.org/stylelint-config-recommended/-/stylelint-config-recommended-8.0.0.tgz",
-      "integrity": "sha512-ZorSSdyMcxWpROYUvLEMm0vSZud2uB7tX1hzBZwvVY9SV/uly4AvvJPPhCcymZL3fcQhEQG5AELmrxWqtmzacw==",
+      "integrity": "sha512-IK6dWvE000+xBv9jbnHOnBq01gt6HGVB2ZTsot+QsMpe82doDQ9hvplxfv4YnpEuUwVGGd9y6nbaAnhrjcxhZQ==",
       "dev": true,
       "requires": {}
     },
     "stylelint-config-recommended-scss": {
-      "version": "5.0.2",
+      "version": "7.0.0",
-      "resolved": "https://registry.npmjs.org/stylelint-config-recommended-scss/-/stylelint-config-recommended-scss-5.0.2.tgz",
+      "resolved": "https://registry.npmjs.org/stylelint-config-recommended-scss/-/stylelint-config-recommended-scss-7.0.0.tgz",
-      "integrity": "sha512-b14BSZjcwW0hqbzm9b0S/ScN2+3CO3O4vcMNOw2KGf8lfVSwJ4p5TbNEXKwKl1+0FMtgRXZj6DqVUe/7nGnuBg==",
+      "integrity": "sha512-rGz1J4rMAyJkvoJW4hZasuQBB7y9KIrShb20l9DVEKKZSEi1HAy0vuNlR8HyCKy/jveb/BdaQFcoiYnmx4HoiA==",
       "dev": true,
       "requires": {
         "postcss-scss": "^4.0.2",
-        "stylelint-config-recommended": "^6.0.0",
+        "stylelint-config-recommended": "^8.0.0",
         "stylelint-scss": "^4.0.0"
       }
     },
     "stylelint-config-standard": {
-      "version": "24.0.0",
+      "version": "26.0.0",
-      "resolved": "https://registry.npmjs.org/stylelint-config-standard/-/stylelint-config-standard-24.0.0.tgz",
+      "resolved": "https://registry.npmjs.org/stylelint-config-standard/-/stylelint-config-standard-26.0.0.tgz",
-      "integrity": "sha512-+RtU7fbNT+VlNbdXJvnjc3USNPZRiRVp/d2DxOF/vBDDTi0kH5RX2Ny6errdtZJH3boO+bmqIYEllEmok4jiuw==",
+      "integrity": "sha512-hUuB7LaaqM8abvkOO84wh5oYSkpXgTzHu2Zza6e7mY+aOmpNTjoFBRxSLlzY0uAOMWEFx0OMKzr+reG1BUtcqQ==",
       "dev": true,
       "requires": {
-        "stylelint-config-recommended": "^6.0.0"
+        "stylelint-config-recommended": "^8.0.0"
       }
     },
     "stylelint-config-standard-scss": {
-      "version": "3.0.0",
+      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/stylelint-config-standard-scss/-/stylelint-config-standard-scss-3.0.0.tgz",
+      "resolved": "https://registry.npmjs.org/stylelint-config-standard-scss/-/stylelint-config-standard-scss-5.0.0.tgz",
-      "integrity": "sha512-zt3ZbzIbllN1iCmc94e4pDxqpkzeR6CJo5DDXzltshuXr+82B8ylHyMMARNnUYrZH80B7wgY7UkKTYCFM0UUyw==",
+      "integrity": "sha512-zoXLibojHZYPFjtkc4STZtAJ2yGTq3Bb4MYO0oiyO6f/vNxDKRcSDZYoqN260Gv2eD5niQIr1/kr5SXlFj9kcQ==",
       "dev": true,
       "requires": {
-        "stylelint-config-recommended-scss": "^5.0.2",
+        "stylelint-config-recommended-scss": "^7.0.0",
-        "stylelint-config-standard": "^24.0.0"
+        "stylelint-config-standard": "^26.0.0"
       }
     },
     "stylelint-prettier": {
@@ -3447,9 +3371,9 @@
       }
     },
     "stylelint-scss": {
-      "version": "4.2.0",
+      "version": "4.3.0",
-      "resolved": "https://registry.npmjs.org/stylelint-scss/-/stylelint-scss-4.2.0.tgz",
+      "resolved": "https://registry.npmjs.org/stylelint-scss/-/stylelint-scss-4.3.0.tgz",
-      "integrity": "sha512-HHHMVKJJ5RM9pPIbgJ/XA67h9H0407G68Rm69H4fzFbFkyDMcTV1Byep3qdze5+fJ3c0U7mJrbj6S0Fg072uZA==",
+      "integrity": "sha512-GvSaKCA3tipzZHoz+nNO7S02ZqOsdBzMiCx9poSmLlb3tdJlGddEX/8QzCOD8O7GQan9bjsvLMsO5xiw6IhhIQ==",
       "dev": true,
       "requires": {
         "lodash": "^4.17.21",
@@ -3469,9 +3393,9 @@
       }
     },
     "supports-hyperlinks": {
-      "version": "2.2.0",
+      "version": "2.3.0",
-      "resolved": "https://registry.npmjs.org/supports-hyperlinks/-/supports-hyperlinks-2.2.0.tgz",
+      "resolved": "https://registry.npmjs.org/supports-hyperlinks/-/supports-hyperlinks-2.3.0.tgz",
-      "integrity": "sha512-6sXEzV5+I5j8Bmq9/vUphGRM/RJNT9SCURJLjwfOg51heRtguGWDzcaBlgAzKhQa0EVNpPEKzQuBwZ8S8WaCeQ==",
+      "integrity": "sha512-RpsAZlpWcDwOPQA22aCH4J0t7L8JmAvsCxfOSEwm7cQs3LshN36QaTkwd70DnBOXDWGssw2eUoc8CaRWT0XunA==",
       "dev": true,
       "requires": {
         "has-flag": "^4.0.0",
@@ -3588,9 +3512,9 @@
       "dev": true
     },
     "write-file-atomic": {
-      "version": "4.0.1",
+      "version": "4.0.2",
-      "resolved": "https://registry.npmjs.org/write-file-atomic/-/write-file-atomic-4.0.1.tgz",
+      "resolved": "https://registry.npmjs.org/write-file-atomic/-/write-file-atomic-4.0.2.tgz",
-      "integrity": "sha512-nSKUxgAbyioruk6hU87QzVbY279oYT6uiwgDoujth2ju4mJ+TZau7SQBhtbTmUyuNYTuXnSyRn66FV0+eCgcrQ==",
+      "integrity": "sha512-7KxauUdBmSdWnmpaGFg+ppNjKF8uNLry8LyzjauQDOVONfFLNKrKvQOxZ/VuTIcS/gge/YNahf5RIIQWTSarlg==",
       "dev": true,
       "requires": {
         "imurmurhash": "^0.1.4",

package.json

@@ -7,9 +7,9 @@
   "bugs": "https://github.com/just-the-docs/just-the-docs/issues",
   "devDependencies": {
     "prettier": "^2.7.1",
-    "stylelint": "^14.9.1",
+    "stylelint": "^14.13.0",
     "stylelint-config-prettier-scss": "0.0.1",
-    "stylelint-config-standard-scss": "^3.0.0",
+    "stylelint-config-standard-scss": "^5.0.0",
     "stylelint-prettier": "^2.0.0"
   },
   "scripts": {

script/build

@@ -1,8 +0,0 @@
-#!/bin/sh
-
-echo "Packaging gem... \n"
-gem build just-the-docs.gemspec
-
-echo "Cleaning up... \n"
-git add *.gem
-git commit -m 'Bump just-the-docs gem package'