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,27 +1,116 @@
+---
+title: CHANGELOG
+layout: default
+---
+
 # CHANGELOG
 
 All notable changes to this project are documented in this file.
 
-*Note:* The project underwent a major maintenance shift in March 2022.
+{: .highlight }
+The project underwent a major maintenance shift in March 2022.
 
 ## HEAD
 
-*Note:* This website is built from the `HEAD` of the `main` branch of the theme repository. It includes docs for the following changes, which are *not* in the latest pre-release!
+{: .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
+- 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
+- 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 prereleases - please let us know!
+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` - if your version of Just the Docs is not pinned, you'll see the changes the next time you run `bundle install` (if you don't have a `Gemfile.lock`) or `bundle update just-the-docs` (if you do).
+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:
 
@@ -48,27 +137,47 @@ remote_theme: just-the-docs/just-the-docs@v0.3.3
 
 ### Features
 
-- Added: accessible titles to nested page nav toggle by @JPrevost in https://github.com/just-the-docs/just-the-docs/pull/950
-- Added: better title styling for AsciiDoc examples by @alyssais in https://github.com/just-the-docs/just-the-docs/pull/944
-- Added: docs for custom search placeholder by @mattxwang in https://github.com/just-the-docs/just-the-docs/pull/939
-- Added: provide ability to skip to main content by @JPrevost in https://github.com/just-the-docs/just-the-docs/pull/949
-- Fixed: exclude `vendor/` in Jekyll config by @manuelhenke in https://github.com/just-the-docs/just-the-docs/pull/941
-- Fixed: improve build time of navigation panel by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/956
+- 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 https://github.com/just-the-docs/just-the-docs/pull/935
-- Fixed: table of contents on search docs by @robinpokorny in https://github.com/just-the-docs/just-the-docs/pull/940
-- Fixed: broken docs link (custom footer) by @olgarithms in https://github.com/just-the-docs/just-the-docs/pull/951
-- Fixed: clarify version docs by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/955
-- Deleted: unused script directory by @mattxwang in https://github.com/just-the-docs/just-the-docs/pull/937
+- 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 https://github.com/just-the-docs/just-the-docs/pull/940
-* @olgarithms made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/951
-* @manuelhenke made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/941
-* @JPrevost made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/950
+* [@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
 
@@ -89,7 +198,7 @@ We want your feedback! Are these changes helpful? Are our docs easy to understan
 
 ### Trying out pre-release `v0.4.0.rc1`
 
-Due to the massive scope of these changes, we're making `v0.4.0.rc1` avaialble as a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc1` - if your version of Just the Docs is not pinned, you'll see the changes the next time you run `bundle install` (if you don't have 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:
 
@@ -118,13 +227,20 @@ 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
 
@@ -133,114 +249,216 @@ In the short-term, we're committed to tidying up everything for a `v0.4.0` relea
 We're also scoping out medium and long-term projects, and want to keep you in the loop. These include:
 
 - upgrading to Jekyll 4, and stopping support for Jekyll 3
-- versioned docs - issue [#728](https://github.com/just-the-docs/just-the-docs/issues/728)
-- 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)
-- internationalization (i18n) - issue [#59](https://github.com/just-the-docs/just-the-docs/issues/59)
-- recursive/multi-level navigation - PR [#462](https://github.com/just-the-docs/just-the-docs/pull/462)
-- toggleable dark mode - issue [#234](https://github.com/just-the-docs/just-the-docs/issues/234)
+- versioned docs - issue [#728]
+- improved accessibility - issues [#566], [#870]
+- internationalization (i18n) - issue [#59]
+- recursive/multi-level navigation - PR [#462]
+- toggleable dark mode - issue [#234]
 
 as well as DX improvements like better regression tests, CI, and tooling. If you're interested in any of these, please join us [on GitHub](https://github.com/just-the-docs/just-the-docs) - any contribution (raising an issue, writing docs, or submitting a PR) is welcome!
 
+[#728]: https://github.com/just-the-docs/just-the-docs/issues/728
+[#566]: https://github.com/just-the-docs/just-the-docs/issues/566
+[#870]: https://github.com/just-the-docs/just-the-docs/issues/870
+[#59]: https://github.com/just-the-docs/just-the-docs/issues/59
+[#462]: https://github.com/just-the-docs/just-the-docs/pull/462
+[#234]: https://github.com/just-the-docs/just-the-docs/issues/234
+
 ### Features
 
-* Added: Combination by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/578
-  - Added: dark highlighting in https://github.com/just-the-docs/just-the-docs/pull/463
-  - Added: pages and collections in https://github.com/just-the-docs/just-the-docs/pull/448
-  - Added: callouts in https://github.com/just-the-docs/just-the-docs/pull/466
-  - Fixed: breadcrumb behaviour … by @AdityaTiwari2102 in https://github.com/just-the-docs/just-the-docs/pull/477
-  - Fixed: prevent rake command corrupting search data in https://github.com/just-the-docs/just-the-docs/pull/495 (also listed below)
-  - Fixed: nested lists in https://github.com/just-the-docs/just-the-docs/pull/496
-  - Fixed: set color for search input in https://github.com/just-the-docs/just-the-docs/pull/498 (also listed below)
+* Added: Combination by [@pdmosses] in [#578]
+  - Added: dark highlighting in [#463]
+  - Added: pages and collections in [#448]
+  - Added: callouts in [#466]
+  - Fixed: breadcrumb behaviour … by [@AdityaTiwari2102] in [#477]
+  - Fixed: prevent rake command corrupting search data in [#495] (also listed below)
+  - Fixed: nested lists in [#496]
+  - Fixed: set color for search input in [#498] (also listed below)
   - Fixed: sites with no child pages (no PR)
-  - Fixed: TOC/breadcrumbs for multiple collections in 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: Replace all uses of `absolute_url` by `relative_url`, by @svrooij in https://github.com/just-the-docs/just-the-docs/pull/544
-* Added: custom favicon `_includes` by @burner1024 in https://github.com/just-the-docs/just-the-docs/pull/364
-* Added: set color for search input by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/498
-* Added: search placeholder configuration by @mattxwang in https://github.com/just-the-docs/just-the-docs/pull/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: `nav_footer_custom` include by @nathanjessen in https://github.com/just-the-docs/just-the-docs/pull/474
-* Added: style fixes for jekyll-asciidoc by @alyssais in https://github.com/just-the-docs/just-the-docs/pull/829
-* Added: mermaid.js support by @nascosto in https://github.com/just-the-docs/just-the-docs/pull/857
-* Added: support for external navigation links by @SPGoding in https://github.com/just-the-docs/just-the-docs/pull/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
-* Fixed: prepend `site.collections_dir` if exists by @alexsegura in https://github.com/just-the-docs/just-the-docs/pull/519
-* Fixed: nested task lists (#517) by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/855
-* Fixed: suppress Liquid processing in CSS comments by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/686
-* Fixed: prevent rake command from corrupting search data by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/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: add `overflow-x: auto` to `figure.highlight` by @iridazzle in https://github.com/just-the-docs/just-the-docs/pull/727
-* Fixed: add `overflow-wrap: word-break` to `body` by @iridazzle in https://github.com/just-the-docs/just-the-docs/pull/889
-* Fixed: vertical alignment for consecutive labels by @Eisverygoodletter in https://github.com/just-the-docs/just-the-docs/pull/893
-* Fixed: allow links to wrap by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/905
-* Fixed: nav scroll feature and absolute/relative URLs by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/898
+  - Fixed: scroll navigation to show the link to the current page in [#639]
+  - Fixed: Replace all uses of `absolute_url` by `relative_url`, by [@svrooij] in [#544]
+* Added: custom favicon `_includes` by [@burner1024] in [#364]
+* Added: set color for search input by [@pdmosses] in [#498]
+* Added: search placeholder configuration by [@mattxwang] in [#613]
+* Added: 'child_nav_order' front matter to be able to sort navigation pages in reverse by [@jmertic] in [#726]
+* Added: `nav_footer_custom` include by [@nathanjessen] in [#474]
+* Added: style fixes for jekyll-asciidoc by [@alyssais] in [#829]
+* Added: mermaid.js support by [@nascosto] in [#857]
+* Added: support for external navigation links by [@SPGoding] in [#876]
+* Added: refactor `mermaid` config to use `mermaid_config.js` include, only require `mermaid.version` in `_config.yml` by [@mattxwang] in [#909]
+* Fixed: prepend `site.collections_dir` if exists by [@alexsegura] in [#519]
+* Fixed: nested task lists (#517) by [@pdmosses] in [#855]
+* Fixed: suppress Liquid processing in CSS comments by [@pdmosses] in [#686]
+* Fixed: prevent rake command from corrupting search data by [@pdmosses] in [#495]
+* Fixed: anchor heading links should be visible on focus by [@jacobhq] in [#846]
+* Fixed: add `overflow-x: auto` to `figure.highlight` by [@iridazzle] in [#727]
+* Fixed: add `overflow-wrap: word-break` to `body` by [@iridazzle] in [#889]
+* Fixed: vertical alignment for consecutive labels by [@Eisverygoodletter] in [#893]
+* Fixed: allow links to wrap by [@pdmosses] in [#905]
+* Fixed: nav scroll feature and absolute/relative URLs by [@pdmosses] in [#898]
+
+[#578]: https://github.com/just-the-docs/just-the-docs/pull/578
+[#463]: https://github.com/just-the-docs/just-the-docs/pull/463
+[#448]: https://github.com/just-the-docs/just-the-docs/pull/448
+[#466]: https://github.com/just-the-docs/just-the-docs/pull/466
+[#477]: https://github.com/just-the-docs/just-the-docs/pull/477
+[#495]: https://github.com/just-the-docs/just-the-docs/pull/495
+[#496]: https://github.com/just-the-docs/just-the-docs/pull/496
+[#498]: https://github.com/just-the-docs/just-the-docs/pull/498
+[#494]: https://github.com/just-the-docs/just-the-docs/pull/494
+[#639]: https://github.com/just-the-docs/just-the-docs/pull/639
+[#544]: https://github.com/just-the-docs/just-the-docs/pull/544
+[#364]: https://github.com/just-the-docs/just-the-docs/pull/364
+[#498]: https://github.com/just-the-docs/just-the-docs/pull/498
+[#613]: https://github.com/just-the-docs/just-the-docs/pull/613
+[#726]: https://github.com/just-the-docs/just-the-docs/pull/726
+[#474]: https://github.com/just-the-docs/just-the-docs/pull/474
+[#829]: https://github.com/just-the-docs/just-the-docs/pull/829
+[#857]: https://github.com/just-the-docs/just-the-docs/pull/857
+[#876]: https://github.com/just-the-docs/just-the-docs/pull/876
+[#909]: https://github.com/just-the-docs/just-the-docs/pull/909
+[#519]: https://github.com/just-the-docs/just-the-docs/pull/519
+[#855]: https://github.com/just-the-docs/just-the-docs/pull/855
+[#686]: https://github.com/just-the-docs/just-the-docs/pull/686
+[#495]: https://github.com/just-the-docs/just-the-docs/pull/495
+[#846]: https://github.com/just-the-docs/just-the-docs/pull/846
+[#727]: https://github.com/just-the-docs/just-the-docs/pull/727
+[#889]: https://github.com/just-the-docs/just-the-docs/pull/889
+[#893]: https://github.com/just-the-docs/just-the-docs/pull/893
+[#905]: https://github.com/just-the-docs/just-the-docs/pull/905
+[#898]: https://github.com/just-the-docs/just-the-docs/pull/898
 
 ### Documentation
 
-* Added: docs on how to break an `ol` by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/856
-* Added: docs for custom includes by @nathanjessen in https://github.com/just-the-docs/just-the-docs/pull/806
-* Added: document caveat about variable dependencies by @waldyrious in https://github.com/just-the-docs/just-the-docs/pull/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
-* Fixed: `ol` on `index.md` by @pmarsceill in https://github.com/just-the-docs/just-the-docs/pull/778
-* Fixed: image link in Markdown kitchen sink by @JeffGuKang in https://github.com/just-the-docs/just-the-docs/pull/221
-* Fixed: images in Markdown kitchen sink by @dougaitken in https://github.com/just-the-docs/just-the-docs/pull/782
-* Fixed: clearer label of link to Jekyll quickstart by @waldyrious in https://github.com/just-the-docs/just-the-docs/pull/549
-* Fixed: remove extra spaces in component docs by @MichelleBlanchette in https://github.com/just-the-docs/just-the-docs/pull/554
-* Fixed: double "your" typo in `index.md` by @sehilyi in https://github.com/just-the-docs/just-the-docs/pull/499
-* Fixed: "you" -> "your" typo in `index.md` by @nathanjessen in https://github.com/just-the-docs/just-the-docs/pull/473
-* Fixed: spacing in toc example by @henryiii in https://github.com/just-the-docs/just-the-docs/pull/835
-* Fixed: typo in `README` on `_config.yml` by @ivanskodje in https://github.com/just-the-docs/just-the-docs/pull/891
-* Fixed: missing code fence in navigation structure docs by @mattxwang in https://github.com/just-the-docs/just-the-docs/pull/906
+* Added: docs on how to break an `ol` by [@pdmosses] in [#856]
+* Added: docs for custom includes by [@nathanjessen] in [#806]
+* Added: document caveat about variable dependencies by [@waldyrious] in [#555]
+* Added: docs on how to use `custom_head` to add a custom favicon by [@UnclassedPenguin] in [#814]
+* Fixed: `ol` on `index.md` by [@pmarsceill] in [#778]
+* Fixed: image link in Markdown kitchen sink by [@JeffGuKang] in [#221]
+* Fixed: images in Markdown kitchen sink by [@dougaitken] in [#782]
+* Fixed: clearer label of link to Jekyll quickstart by [@waldyrious] in [#549]
+* Fixed: remove extra spaces in component docs by [@MichelleBlanchette] in [#554]
+* Fixed: double "your" typo in `index.md` by [@sehilyi] in [#499]
+* Fixed: "you" -> "your" typo in `index.md` by [@nathanjessen] in [#473]
+* Fixed: spacing in toc example by [@henryiii] in [#835]
+* Fixed: typo in `README` on `_config.yml` by [@ivanskodje] in [#891]
+* Fixed: missing code fence in navigation structure docs by [@mattxwang] in [#906]
+
+[#856]: https://github.com/just-the-docs/just-the-docs/pull/856
+[#806]: https://github.com/just-the-docs/just-the-docs/pull/806
+[#555]: https://github.com/just-the-docs/just-the-docs/pull/555
+[#814]: https://github.com/just-the-docs/just-the-docs/pull/814
+[#778]: https://github.com/just-the-docs/just-the-docs/pull/778
+[#221]: https://github.com/just-the-docs/just-the-docs/pull/221
+[#782]: https://github.com/just-the-docs/just-the-docs/pull/782
+[#549]: https://github.com/just-the-docs/just-the-docs/pull/549
+[#554]: https://github.com/just-the-docs/just-the-docs/pull/554
+[#499]: https://github.com/just-the-docs/just-the-docs/pull/499
+[#473]: https://github.com/just-the-docs/just-the-docs/pull/473
+[#835]: https://github.com/just-the-docs/just-the-docs/pull/835
+[#891]: https://github.com/just-the-docs/just-the-docs/pull/891
+[#906]: https://github.com/just-the-docs/just-the-docs/pull/906
 
 ### Maintenance
 
-* Added: VScode devcontainer by @max06 in https://github.com/just-the-docs/just-the-docs/pull/783
-* Added: `webrick` to `Gemfile` by @mattxwang in https://github.com/just-the-docs/just-the-docs/pull/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
-* Updated: new repo path by @pmarsceill in https://github.com/just-the-docs/just-the-docs/pull/775
-* Updated: rename `master` -> `main` by @pmarsceill in https://github.com/just-the-docs/just-the-docs/pull/776
-* Updated: README by @pmarsceill in https://github.com/just-the-docs/just-the-docs/pull/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: CI files, Ruby & Node Versions by @mattxwang in https://github.com/just-the-docs/just-the-docs/pull/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
+* Added: VScode devcontainer by [@max06] in [#783]
+* Added: `webrick` to `Gemfile` by [@mattxwang] in [#799]
+* Added: 'This site is powered by Netlify.' to the footer by [@mattxwang] in [#797]
+* Updated: new repo path by [@pmarsceill] in [#775]
+* Updated: rename `master` -> `main` by [@pmarsceill] in [#776]
+* Updated: README by [@pmarsceill] in [#777]
+* Updated: Code of Conduct to Contributor Covenant v2.1 by [@mattxwang] in [#790]
+* Updated: CI files, Ruby & Node Versions by [@mattxwang] in [#820]
+* Updated: Stylelint to v14, extend SCSS plugins, remove primer-* configs, resolve issues by [@mattxwang] in [#821]
+
+[#783]: https://github.com/just-the-docs/just-the-docs/pull/783
+[#799]: https://github.com/just-the-docs/just-the-docs/pull/799
+[#797]: https://github.com/just-the-docs/just-the-docs/pull/797
+[#775]: https://github.com/just-the-docs/just-the-docs/pull/775
+[#776]: https://github.com/just-the-docs/just-the-docs/pull/776
+[#777]: https://github.com/just-the-docs/just-the-docs/pull/777
+[#790]: https://github.com/just-the-docs/just-the-docs/pull/790
+[#820]: https://github.com/just-the-docs/just-the-docs/pull/820
+[#821]: https://github.com/just-the-docs/just-the-docs/pull/821
 
 ### Dependencies
-* Upgrade to GitHub-native Dependabot by @dependabot-preview in 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
-* [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 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 ini from 1.3.5 to 1.3.8 by @dependabot-preview in https://github.com/just-the-docs/just-the-docs/pull/511
-* 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
-* 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 prettier from 2.1.2 to 2.5.1 by @dependabot in https://github.com/just-the-docs/just-the-docs/pull/787
-* 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.6.2 to 2.7.1 by @dependabot in https://github.com/just-the-docs/just-the-docs/pull/864
+
+* Upgrade to GitHub-native Dependabot by @dependabot-preview in [#627]
+* [Security] Bump y18n from 3.2.1 to 3.2.2 by @dependabot-preview in [#606]
+* [Security] Bump hosted-git-info from 2.7.1 to 2.8.9 by @dependabot-preview in [#641]
+* [Security] Bump lodash from 4.17.19 to 4.17.21 by @dependabot-preview in [#640]
+* [Security] Bump ini from 1.3.5 to 1.3.8 by @dependabot-preview in [#511]
+* Bump path-parse from 1.0.6 to 1.0.7 by @dependabot in [#699]
+* Bump ajv from 6.10.0 to 6.12.6 by @dependabot in [#766]
+* Bump prettier from 2.1.2 to 2.5.1 by @dependabot in [#787]
+* Bump prettier from 2.5.1 to 2.6.2 by @dependabot in [#809]
+* Bump prettier from 2.6.2 to 2.7.1 by @dependabot in [#864]
+
+[#627]: https://github.com/just-the-docs/just-the-docs/pull/627
+[#606]: https://github.com/just-the-docs/just-the-docs/pull/606
+[#641]: https://github.com/just-the-docs/just-the-docs/pull/641
+[#640]: https://github.com/just-the-docs/just-the-docs/pull/640
+[#511]: https://github.com/just-the-docs/just-the-docs/pull/511
+[#699]: https://github.com/just-the-docs/just-the-docs/pull/699
+[#766]: https://github.com/just-the-docs/just-the-docs/pull/766
+[#787]: https://github.com/just-the-docs/just-the-docs/pull/787
+[#809]: https://github.com/just-the-docs/just-the-docs/pull/809
+[#864]: https://github.com/just-the-docs/just-the-docs/pull/864
 
 ### New Contributors
-* @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
-* @JeffGuKang made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/221
-* @dougaitken made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/782
-* @max06 made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/783
-* @sehilyi made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/499
-* @nathanjessen made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/473
-* @waldyrious made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/549
-* @MichelleBlanchette made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/554
-* @henryiii made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/835
-* @jmertic made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/726
-* @jacobhq made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/846
-* @UnclassedPenguin made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/814
-* @alyssais made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/829
-* @nascosto made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/857
-* @SPGoding made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/876
-* @iridazzle made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/727
-* @ivanskodje made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/891
-* @Eisverygoodletter made their first contribution in https://github.com/just-the-docs/just-the-docs/pull/893
+
+* [@AdityaTiwari2102] made their first contribution in [#477]
+* [@svrooij] made their first contribution in [#544]
+* [@alexsegura] made their first contribution in [#519]
+* [@burner1024] made their first contribution in [#364]
+* [@JeffGuKang] made their first contribution in [#221]
+* [@dougaitken] made their first contribution in [#782]
+* [@max06] made their first contribution in [#783]
+* [@sehilyi] made their first contribution in [#499]
+* [@nathanjessen] made their first contribution in [#473]
+* [@waldyrious] made their first contribution in [#549]
+* [@MichelleBlanchette] made their first contribution in [#554]
+* [@henryiii] made their first contribution in [#835]
+* [@jmertic] made their first contribution in [#726]
+* [@jacobhq] made their first contribution in [#846]
+* [@UnclassedPenguin] made their first contribution in [#814]
+* [@alyssais] made their first contribution in [#829]
+* [@nascosto] made their first contribution in [#857]
+* [@SPGoding] made their first contribution in [#876]
+* [@iridazzle] made their first contribution in [#727]
+* [@ivanskodje] made their first contribution in [#891]
+* [@Eisverygoodletter] made their first contribution in [#893]
+
+[@AdityaTiwari2102]: https://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", "vendor"]
+
+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"

_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,72 +1,139 @@
 {%- comment -%}
-  Pages with no `title` are implicitly excluded from the navigation.
+  The `nav_order` values of pages affect the order in which they are shown in
+  the navigation panel and in the automatically generated tables of contents.
+  Sibling pages with the same `nav_order` value may be shown in any order.
+  Sibling pages with no `nav_order` value are shown after all pages that have
+  explicit `nav_order` values, ordered by their `title` values.
   
-  The values of `title` and `nav_order` can be numbers or strings.
-  Jekyll gives build failures when sorting on mixtures of different types,
-  so numbers and strings need to be sorted separately.
+  The `nav_order` and `title` values can be numbers or strings. To avoid build
+  failures, we sort numbers and strings separately. We sort numbers by their
+  values, and strings lexicographically. The case-sensitivity of string sorting
+  is determined by the configuration setting of `nav_sort`. Pages with no `title`
+  value are excluded from the navigation.
 
-  Here, numbers are sorted by their values, and come before all strings.
-  An omitted `nav_order` value is equivalent to the page's `title` value
-  (except that a numerical `title` value is treated as a string).
-
-  The case-sensitivity of string sorting is determined by `site.nav_sort`.
+  Note: Numbers used as `title` or `nav_order` values should not be in quotes,
+  unless you intend them to be lexicographically ordered. Numbers are written
+  without spaces or thousands-separators. Negative numbers are preceded by `-`.
+  Floats are written with the integral and fractional parts separated by `.`.
+  (Bounds on the magnitude and precision are presumably the same as in Liquid.)
 {%- endcomment -%}
 
-{%- assign titled_pages = include.pages
+{%- assign title_pages = include.pages
       | where_exp: "item", "item.title != nil" -%}
 
-{%- assign string_ordered_pages = titled_pages
-      | where_exp: "item", "item.nav_order == nil" -%}
-{%- assign nav_ordered_pages = titled_pages
-      | where_exp: "item", "item.nav_order != nil" -%}
-
 {%- comment -%}
-  Add the nav-ordered pages to the number-ordered pages or the string-ordered pages,
-  depending on their `nav_order` value.
+  A page with `nav_exclude: true` does not appear in the main navigation.
+  If it has a `parent`, it may appear in the parent's table of contents.
+  If it specifies `has_children: true`, it should appear in the breadcrumbs
+  of the child pages, but its order in relation to other pages is irrelevant.
+  Pages that never appear can be removed from the pages that need to be sorted.
+  This optimisation can be significant on a site with many pages.
   
-  The first character of the `jsonify` result is `"` only for strings.
+  In Jekyll 4, the pages to be sorted can be filtered by:
+  
+  {%- assign title_pages = title_pages
+        | where_exp: "item", "item.nav_exclude != true or item.parent != nil" -%}
+  
+  That filter is not allowed in Jekyll 3. The following iterative code gives the
+  same effect, but it is activated only when it will filter more than 50% of the
+  pages.
 {%- endcomment -%}
 
-{%- assign nav_ordered_groups = nav_ordered_pages
-      | group_by_exp: "item", "item.nav_order | jsonify | slice: 0" -%}
+{%- 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 number_ordered_pages = "" | split: "" -%}
-{%- for group in nav_ordered_groups -%}
+{%- 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 -%}
 
-{%- assign sorted_number_ordered_groups = number_ordered_pages
-      | sort: "nav_order" | group_by: "nav_order" -%}
+{%- unless nav_number_pages == empty -%}
+  {%- assign nav_number_pages = nav_number_pages | sort: "nav_order" -%}
+{%- endunless -%}
+
+{%- unless nav_string_pages == empty -%}
+  {%- if site.nav_sort == 'case_insensitive' -%}
+    {%- assign nav_string_pages = nav_string_pages | sort_natural: "nav_order" -%}
+  {%- else -%}
+    {%- assign nav_string_pages = nav_string_pages | sort: "nav_order" -%}
+  {%- endif -%}
+{%- endunless -%}
+
+{%- assign title_number_pages = "" | split: "" -%}
+{%- assign title_string_pages = "" | split: "" -%}
+{%- assign title_order_groups = title_order_pages
+      | group_by_exp: "item", "item.title | jsonify | slice: 0" -%}
+{%- for group in title_order_groups -%}
+  {%- if group.name == '"' -%}
+    {%- assign title_string_pages = group.items -%}
+  {%- else -%}
+    {%- assign title_number_pages = title_number_pages | concat: group.items -%}
+  {%- endif -%}
+{%- endfor -%}
+
+{%- unless title_number_pages == empty -%}
+  {%- assign title_number_pages = title_number_pages | sort: "title" -%}
+{%- endunless -%}
+
+{%- unless title_string_pages == empty -%}
+  {%- if site.nav_sort == 'case_insensitive' -%}
+    {%- assign title_string_pages = title_string_pages | sort_natural: "title" -%}
+  {%- else -%}
+    {%- assign title_string_pages = title_string_pages | sort: "title" -%}
+  {%- endif -%}
+{%- endunless -%}
+
+{%- assign pages_list = nav_number_pages | concat: nav_string_pages
+      | concat: title_number_pages | concat: title_string_pages -%}
+
+{%- assign first_level_pages = pages_list
+      | where_exp: "item", "item.parent == nil" -%}
+{%- assign second_level_pages = pages_list
+      | where_exp: "item", "item.parent != nil"
+      | where_exp: "item", "item.grand_parent == nil" -%}
+{%- assign third_level_pages = pages_list
+      | where_exp: "item", "item.grand_parent != nil" -%}
 
 {%- comment -%}
-  Group the string-ordered pages by `nav_order`, if non-nil, and otherwise `title`
-  (but appending the empty string to a numeric title to convert it to a string).
-  
-  Then sort the groups according to the site setting for case (in)sensitivity.
+  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 -%}
 
-{%- assign string_ordered_groups = string_ordered_pages
-      | group_by_exp:"item", "item.nav_order | default: item.title | append: '' " -%}
-
-{%- if site.nav_sort == 'case_insensitive' -%}
-  {%- assign sorted_string_ordered_groups = string_ordered_groups
-        | sort_natural: "name" -%}
-{%- else -%}
-  {%- assign sorted_string_ordered_groups = string_ordered_groups
-        | sort:"name" -%}
-{%- endif -%}
-
-{%- assign groups_list = sorted_number_ordered_groups
-      | concat: sorted_string_ordered_groups -%}
-
 <ul class="nav-list">
-  {%- for node_group in groups_list -%} 
-  {%- for node in node_group.items -%}
-    {%- if node.parent == nil -%}
+{%- 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 -%}
@@ -76,13 +143,8 @@
         {%- 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 = "" | split: "" -%}
-          {%- for parent_group in groups_list -%}
-            {%- assign children_list = children_list 
-                  | concat: parent_group.items
-                  | where: "parent", node.title
-                  | where_exp:"item", "item.grand_parent == nil" -%}
-          {%- endfor -%}
+          {%- assign children_list = second_level_pages
+                | where: "parent", node.title -%}
           {%- if node.child_nav_order == 'desc' -%}
             {%- assign children_list = children_list | reverse -%}
           {%- endif -%}
@@ -97,21 +159,17 @@
               {%- endif -%}
               <a href="{{ child.url | relative_url }}" class="nav-list-link{% if page.url == child.url %} active{% endif %}">{{ child.title }}</a>
               {%- if child.has_children -%}
-                {%- assign grandchildren_list = "" | split: "" -%}
-                {%- for grandparent_group in groups_list -%}
-                  {%- assign grandchildren_list = grandchildren_list
-                        | concat: grandparent_group.items
+                {%- assign grand_children_list = third_level_pages
                       | where: "parent", child.title
                       | where: "grand_parent", node.title -%}
-                {%- endfor -%}
-                {%- if node.child_nav_order == 'desc' -%}
-                  {%- assign grandchildren_list = grandchildren_list | reverse -%}
+                {%- if child.child_nav_order == 'desc' -%}
+                  {%- assign grand_children_list = grand_children_list | reverse -%}
                 {%- endif -%}
                 <ul class="nav-list">
-                {%- for grandchild in grandchildren_list -%}
-                  {%- unless grandchild.nav_exclude -%}
-                  <li class="nav-list-item {% if page.url == grandchild.url %} active{% endif %}">
-                    <a href="{{ grandchild.url | relative_url }}" class="nav-list-link{% if page.url == grand_child.url %} active{% endif %}">{{ grandchild.title }}</a>
+                {%- for grand_child in grand_children_list -%}
+                  {%- unless grand_child.nav_exclude -%}
+                  <li class="nav-list-item {% if page.url == grand_child.url %} active{% endif %}">
+                    <a href="{{ grand_child.url | relative_url }}" class="nav-list-link{% if page.url == grand_child.url %} active{% endif %}">{{ grand_child.title }}</a>
                   </li>
                   {%- endunless -%}
                 {%- endfor -%}
@@ -124,64 +182,52 @@
         {%- endif -%}
       </li>
     {%- endunless -%}
-    {%- endif -%}
-  {%- endfor -%}
-  {%- endfor -%}
-  {%- assign nav_external_links = site.nav_external_links -%}
-  {%- for node in nav_external_links -%}
+{%- endfor -%}
+{%- assign nav_external_links = site.nav_external_links -%}
+{%- for node in nav_external_links -%}
       <li class="nav-list-item external">
         <a href="{{ node.url | absolute_url }}" class="nav-list-link external">
           {{ node.title }}
           {% unless node.hide_icon %}<svg viewBox="0 0 24 24" aria-labelledby="svg-external-link-title"><use xlink:href="#svg-external-link"></use></svg>{% endunless %}
         </a>
       </li>
-  {%- endfor -%}
+{%- 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_group in groups_list -%}
-  {%- for node in node_group.items -%}
-    {%- if node.parent == nil -%}
-      {%- if page.grand_parent == node.title 
-              or page.parent == node.title
-              and page.grand_parent == nil -%}
+  If the current page is in the collection (if any) whose navigation is currently
+  being generated, the following code sets `first_level_url` to the URL used in
+  the page's top-level breadcrumb (if any), and `second_level_url` to that used
+  in the page's second-level breadcrumb (if any).
+  
+  For pages with children, the code also sets `toc_list` to the list of child pages.
+{%- 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 = "" | split: "" -%}
-        {%- for parent_group in groups_list -%}
-          {%- assign children_list = children_list | concat: 
-                parent_group.items | where: "parent", node.title -%}
-        {%- endfor -%}
-        {%- if node.child_nav_order == 'desc' -%}
-          {%- assign children_list = children_list | reverse -%}
-        {%- endif -%}
+        {%- 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 -%}
+            {%- if page.url == child.url or page.parent == child.title and page.grand_parent == child.parent -%}
               {%- assign second_level_url = child.url | relative_url -%}
             {%- endif -%}
           {%- endif -%}
         {%- endfor -%}
       {%- endif -%}
-    {%- endif -%}
   {%- endfor -%}
-  {%- endfor -%}
-
-  {% if page.has_children == true and page.has_toc != false %}
-    {%- assign toc_list = "" | split: "" -%}
-    {%- for parent_group in groups_list -%}
-      {%- assign toc_list = toc_list
-            | concat: parent_group.items
+  {%- if page.has_children == true and page.has_toc != false -%}
+    {%- assign toc_list = pages_list
           | where: "parent", page.title
           | where: "grand_parent", page.parent -%}
-    {%- endfor -%}
-    {%- if node.child_nav_order == 'desc' -%}
+    {%- 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

@@ -49,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"
@@ -112,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 %}
@@ -157,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>
@@ -215,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;
-  background-image: linear-gradient($border-color 0%, $border-color 100%);
-  background-repeat: repeat-x;
-  background-position: 0 100%;
-  background-size: 1px 1px;
+  text-decoration: underline;
+  text-decoration-color: $border-color;
+  text-underline-offset: 2px;
 
   &:hover {
-    background-image: linear-gradient(
-      rgba($link-color, 0.45) 0%,
-      rgba($link-color, 0.45) 100%
-    );
-    background-size: 1px 1px;
+    text-decoration-color: rgba($link-color, 0.45);
   }
 }
 
@@ -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

@@ -106,6 +106,7 @@ figure.highlight {
   }
 
   td.gl {
+    width: 1em;
     padding-right: $sp-3;
   }
 

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,11 +140,27 @@ 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
 

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.
-
-> _Note for users of previous versions:_ `nav_sort: case_insensitive` previously affected the ordering of numerical `nav_order` parameters: e.g., `10` came before `2`. Also, all pages with explicit `nav_order` parameters previously came before all pages with default parameters. Both were potentially confusing, and they have now been eliminated.
+By default, all Capital letters come before all lowercase letters; you can add `nav_sort: case_insensitive` in the configuration file to ignore the case. Enclosing strings in (single or double) quotation marks is optional. Numeric values are not enclosed in quotation marks, e.g., `42`, `-1.0`; numbers in quotation marks are lexicographically ordered, so `"10"` comes before `"2"`, for example.
 
 ---
 
@@ -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/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
-GitHubPages::Dependencies.gems.each do |gem, version|
-  s.add_dependency(gem, "= #{version}")
+def foo
+  puts 'foo'
 end
 {% endhighlight %}

index.md

@@ -17,18 +17,18 @@ Just the Docs gives your documentation a jumpstart with a responsive Jekyll them
 ---
 
 {: .new }
-> **Pre-release version `0.4.0.rc2` is available!**
-> See [the CHANGELOG](https://github.com/just-the-docs/just-the-docs/blob/main/CHANGELOG.md) for a detailed breakdown.
+> **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.rc2"
+> gem "just-the-docs", "0.4.0.rc3"
 > ```
 > and/or
 > ```yaml
-> remote_theme: just-the-docs/just-the-docs@v0.4.0.rc2
+> 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.rc2"
+  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,7 +10,7 @@
       "license": "MIT",
       "devDependencies": {
         "prettier": "^2.7.1",
-        "stylelint": "^14.11.0",
+        "stylelint": "^14.13.0",
         "stylelint-config-prettier-scss": "0.0.1",
         "stylelint-config-standard-scss": "^5.0.0",
         "stylelint-prettier": "^2.0.0"
@@ -429,9 +429,9 @@
       "dev": true
     },
     "node_modules/fast-glob": {
-      "version": "3.2.11",
-      "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.2.11.tgz",
-      "integrity": "sha512-xrO3+1bxSo3ZVHAnqzyuewYT6aMFHRAd4Kcs92MAonjwQZLsK9d0SF1IyQ3k5PoirxTW0Oe/RqFgMQ6TcNE5Ew==",
+      "version": "3.2.12",
+      "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.2.12.tgz",
+      "integrity": "sha512-DVj4CQIYYow0BlaelwK1pHl5n5cRSJfM60UA0zK891sVInoPri2Ekj7+e1CT3/3qxXenpI+nBBmQAcJPJgaj4w==",
       "dev": true,
       "dependencies": {
         "@nodelib/fs.stat": "^2.0.2",
@@ -1671,9 +1671,9 @@
       "dev": true
     },
     "node_modules/stylelint": {
-      "version": "14.11.0",
-      "resolved": "https://registry.npmjs.org/stylelint/-/stylelint-14.11.0.tgz",
-      "integrity": "sha512-OTLjLPxpvGtojEfpESWM8Ir64Z01E89xsisaBMUP/ngOx1+4VG2DPRcUyCCiin9Rd3kPXPsh/uwHd9eqnvhsYA==",
+      "version": "14.13.0",
+      "resolved": "https://registry.npmjs.org/stylelint/-/stylelint-14.13.0.tgz",
+      "integrity": "sha512-NJSAdloiAB/jgVJKxMR90mWlctvmeBFGFVUvyKngi9+j/qPSJ5ZB+u8jOmGbLTnS7OHrII9NFGehPRyar8U5vg==",
       "dev": true,
       "dependencies": {
         "@csstools/selector-specificity": "^2.0.2",
@@ -1682,7 +1682,7 @@
         "cosmiconfig": "^7.0.1",
         "css-functions-list": "^3.1.0",
         "debug": "^4.3.4",
-        "fast-glob": "^3.2.11",
+        "fast-glob": "^3.2.12",
         "fastest-levenshtein": "^1.0.16",
         "file-entry-cache": "^6.0.1",
         "global-modules": "^2.0.0",
@@ -1709,7 +1709,7 @@
         "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",
@@ -1854,9 +1854,9 @@
       }
     },
     "node_modules/supports-hyperlinks": {
-      "version": "2.2.0",
-      "resolved": "https://registry.npmjs.org/supports-hyperlinks/-/supports-hyperlinks-2.2.0.tgz",
-      "integrity": "sha512-6sXEzV5+I5j8Bmq9/vUphGRM/RJNT9SCURJLjwfOg51heRtguGWDzcaBlgAzKhQa0EVNpPEKzQuBwZ8S8WaCeQ==",
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/supports-hyperlinks/-/supports-hyperlinks-2.3.0.tgz",
+      "integrity": "sha512-RpsAZlpWcDwOPQA22aCH4J0t7L8JmAvsCxfOSEwm7cQs3LshN36QaTkwd70DnBOXDWGssw2eUoc8CaRWT0XunA==",
       "dev": true,
       "dependencies": {
         "has-flag": "^4.0.0",
@@ -2359,9 +2359,9 @@
       "dev": true
     },
     "fast-glob": {
-      "version": "3.2.11",
-      "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.2.11.tgz",
-      "integrity": "sha512-xrO3+1bxSo3ZVHAnqzyuewYT6aMFHRAd4Kcs92MAonjwQZLsK9d0SF1IyQ3k5PoirxTW0Oe/RqFgMQ6TcNE5Ew==",
+      "version": "3.2.12",
+      "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.2.12.tgz",
+      "integrity": "sha512-DVj4CQIYYow0BlaelwK1pHl5n5cRSJfM60UA0zK891sVInoPri2Ekj7+e1CT3/3qxXenpI+nBBmQAcJPJgaj4w==",
       "dev": true,
       "requires": {
         "@nodelib/fs.stat": "^2.0.2",
@@ -3263,9 +3263,9 @@
       "dev": true
     },
     "stylelint": {
-      "version": "14.11.0",
-      "resolved": "https://registry.npmjs.org/stylelint/-/stylelint-14.11.0.tgz",
-      "integrity": "sha512-OTLjLPxpvGtojEfpESWM8Ir64Z01E89xsisaBMUP/ngOx1+4VG2DPRcUyCCiin9Rd3kPXPsh/uwHd9eqnvhsYA==",
+      "version": "14.13.0",
+      "resolved": "https://registry.npmjs.org/stylelint/-/stylelint-14.13.0.tgz",
+      "integrity": "sha512-NJSAdloiAB/jgVJKxMR90mWlctvmeBFGFVUvyKngi9+j/qPSJ5ZB+u8jOmGbLTnS7OHrII9NFGehPRyar8U5vg==",
       "dev": true,
       "requires": {
         "@csstools/selector-specificity": "^2.0.2",
@@ -3274,7 +3274,7 @@
         "cosmiconfig": "^7.0.1",
         "css-functions-list": "^3.1.0",
         "debug": "^4.3.4",
-        "fast-glob": "^3.2.11",
+        "fast-glob": "^3.2.12",
         "fastest-levenshtein": "^1.0.16",
         "file-entry-cache": "^6.0.1",
         "global-modules": "^2.0.0",
@@ -3301,7 +3301,7 @@
         "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",
@@ -3393,9 +3393,9 @@
       }
     },
     "supports-hyperlinks": {
-      "version": "2.2.0",
-      "resolved": "https://registry.npmjs.org/supports-hyperlinks/-/supports-hyperlinks-2.2.0.tgz",
-      "integrity": "sha512-6sXEzV5+I5j8Bmq9/vUphGRM/RJNT9SCURJLjwfOg51heRtguGWDzcaBlgAzKhQa0EVNpPEKzQuBwZ8S8WaCeQ==",
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/supports-hyperlinks/-/supports-hyperlinks-2.3.0.tgz",
+      "integrity": "sha512-RpsAZlpWcDwOPQA22aCH4J0t7L8JmAvsCxfOSEwm7cQs3LshN36QaTkwd70DnBOXDWGssw2eUoc8CaRWT0XunA==",
       "dev": true,
       "requires": {
         "has-flag": "^4.0.0",

package.json

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