* Fix default highlighting in custom schemes

Fix #982

The variable settings for highlighting in the default `light` scheme are currently (v0.4.0.rc2`) in `_sass/color_schemes/light.scss`.
This PR ensures that custom schemes are based on the `light` scheme.

It also adds a note explaining the default to the customization docs,
and gives an example of how to define a custom scheme based on the `dark` scheme

* Prettier

* Deleted test file

Co-authored-by: Matt Wang <matt@matthewwang.me>

Bumps [stylelint](https://github.com/stylelint/stylelint) from 14.12.1 to 14.13.0.
- [Release notes](https://github.com/stylelint/stylelint/releases)
- [Changelog](https://github.com/stylelint/stylelint/blob/main/CHANGELOG.md)
- [Commits](https://github.com/stylelint/stylelint/compare/14.12.1...14.13.0

)

---
updated-dependencies:
- dependency-name: stylelint
  dependency-type: direct:development
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* Add toc heading custom include

Closes #961.

* Revert "Add toc heading custom include"

This reverts commit 49813c341973e313db0a21f075a60ebf2120989e.

* Update code highlighting with line numbers

- Add the example of code highlighting with line numbers explained in the [Jekyll docs](https://jekyllrb.com/docs/liquid/tags/#line-numbers).
- Fix the styling of narrow code with line numbers, which floats to the centre without this CSS adjustment. (The line numbers column expands as needed with larger numbers of lines, despite using `width`; using `min-width` doesn't work.)

To apply HTML compression, I removed `vendor` from `exclude`; that change is left to a different PR.

* Make more CHANGELOG  urls clickable

Extension of PR #977 to v0.4.0.rc1:

- Make callouts `loud`.
- Replace a warning paragraph by a callout.
- Use a reference link instead of an explicit url for @pmarsceill .
- Add link reference definitions for PRs and new contributors in v0.4.0.rc1.
- Replace inline urls by shortcut link references.

The changes to replace URLs by link references would be too tedious and error-prone to do completely manually for v0.4.0.rc1.
The following regexp replacements were applied to the sections of v0.4.0.rc1, using Atom:

- Copy a section of changes.
- In the copy, replace `.*(https://.*pull/)([0-9]+).*$` by `[#$2]: $1$2`.
- In the original, replace `(https://.*pull/)([0-9]+)` by `[#$2]`.

- Copy a section of new contributors.
- In the copy, replace `\* @([^ ]+) .*$` by `[@$1]: https://githhub.com/$1`.
- In the original, replace `@([a-zA-Z0-9]+)` by `[@$1]`.

Add (co)authors in [#578]:

* [@AdityaTiwari2102] made their first contribution in [#477]
* [@svrooij] made their first contribution in [#544]

[@AdityaTiwari2102]: https://githhub.com/AdityaTiwari2102
[@svrooij]: https://githhub.com/svrooij

To test:

1. Check that the CHANGELOG contents looks the same in the docs and in the repo (apart from the callouts) with clickable links to all PRs and contributors for v0.4.0.rc1.

2. Check that none of the lines with changes or new contributors have been removed.

* Revert to quiet callouts

Fix #973

Update the array of excluded directories and files to be:

- those that Jekyll excludes by default (since our `exclude` replaces Jekyll's defaults in Jekyll 3) and
- the others that the theme previously excluded, but omitting `vendor` – also ones that are no longer in the repo.

Excluding `vendor` was preventing HTML compression of the theme docs, since the layout used for compression is in `_layouts/vendor/compress.html`.

The change from one-line to multi-line YAML layout for the array of excluded files enhances readability. The addition of explanatory comments supports maintenance.

To test the effect of this PR on the theme docs:

- Build and serve the theme docs.
- Check that  the HTML files are now compressed.
- Check that the last example of code with line numbers has incorrect formatting.

(This PR cannot affect sites that use the theme as a gem or as a remote theme, since we don't include our `_config.yml`.)

Closes #961. Replays a previous attempt.

Bumps [stylelint](https://github.com/stylelint/stylelint) from 14.12.0 to 14.12.1.
- [Release notes](https://github.com/stylelint/stylelint/releases)
- [Changelog](https://github.com/stylelint/stylelint/blob/main/CHANGELOG.md)
- [Commits](https://github.com/stylelint/stylelint/compare/14.12.0...14.12.1

)

---
updated-dependencies:
- dependency-name: stylelint
  dependency-type: direct:development
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* Make CHANGELOG urls clickable

- Add link reference definitions for PRs and new contributors in v0.4.0.rc2
- Replace inline urls by shortcut link references
- Add front matter so the page appears in the navigation
- Change the link to the CHANGELOG on the home page

The CHANGELOG contents should look the same in the docs and in the repo (apart from the callouts) with clickable links to PRs and some contributors.

The urls shown in the changes in v0.4.0.rc1 (and previous releases) haven't yet been made clickable – it would be too tedious and error-prone to do it manually.

* Make CHANGELOG urls clickable

- Add a callout

Change link/anchor styling to use `text-decoration`, `text-decoration-color`, `text-underline-offset`.

Looking to tackle some low-hanging fruit! Closes #636.

[Link to deploy preview](https://deploy-preview-967--just-the-docs.netlify.app/).

Old behaviour:

<img width="582" alt="Screen Shot 2022-09-16 at 11 56 26 AM" src="https://user-images.githubusercontent.com/14893287/190711440-8e56c3a2-250f-4121-8c57-8e6e20c4ae07.png">

New behaviour:

<img width="546" alt="Screen Shot 2022-09-16 at 11 56 19 AM" src="https://user-images.githubusercontent.com/14893287/190711520-2cc7fd4d-d449-4e14-9e75-96545f9f578d.png">


Some notes:

- the only visible change should be minor differences in the thickness of the line (browser defaults) + how underhangs (ex a "g") interact with the line
- color-wise, this is a no-op :) 
- I added an offset to mimic the behaviour of `background-size: 1px 1px;`

Let me know what we think!

Bumps [stylelint](https://github.com/stylelint/stylelint) from 14.11.0 to 14.12.0.
- [Release notes](https://github.com/stylelint/stylelint/releases)
- [Changelog](https://github.com/stylelint/stylelint/blob/main/CHANGELOG.md)
- [Commits](https://github.com/stylelint/stylelint/compare/14.11.0...14.12.0

)

---
updated-dependencies:
- dependency-name: stylelint
  dependency-type: direct:development
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

This is a bite-sized PR that fixes #681. It adds a very minimal styling set to `blockquote` that can be easily overridden by a user.

The [markdown kitchen sink](https://deploy-preview-965--just-the-docs.netlify.app/docs/index-test/) has the example described in the issue:

<img width="772" alt="Screen Shot 2022-09-15 at 5 49 44 PM" src="https://user-images.githubusercontent.com/14893287/190533247-60ddaba3-85b2-4c03-b520-a67f6b047345.png">


Note that it differs from GFM/GitHub's renderer:

> This is a blockquote!

I'm not sure if the intention is to bring it to one-to-one parity. If that's the case, I can dim the text color and make the sidebar thicker.

Closes #963.

- redundant `role="navigation"` on nav elements
- redundant `type="text/javascript"` on script tags
- misplaced mermaid script tag

Note that [running the validator on the deploy preview](https://validator.w3.org/nu/?doc=https%3A%2F%2Fdeploy-preview-964--just-the-docs.netlify.app%2F) has no errors now!

An occurrence of `grandchild` was miss-spelled `grand_child` (!).
That caused omission of the `active` class in the link in the nav panel for all grandchildren.

This bug was discovered using `diff` to compare the generated sites built using v0.4.0.rc1 and commit  4396b6b1c836f354bb7aa7edc1a06a49f137d615 on the fix-nav-performance PR branch.

Fixes #396.

Remove inaccurate comments about unpinned gem versions
- pre-release gems have lower precedence than release gems.

Clarify that there aren't yet any changes to `main` since the release of `v0.4.0.rc2`.

prep for v0.4.0.rc2

Fix #863.

The current Liquid code to generate the navigation panel involves the inefficient extraction of a list of pages from a list of page groups (identified by @captn3m0 in his original [explanation of the performance issue](https://github.com/just-the-docs/just-the-docs/issues/863)). 

The optimisation implemented by this PR generates navigation links directly from the list of page groups, thereby avoiding the extraction of a list of pages from it. The Liquid code is now a bit tedious, but I don't see a simpler solution. 

The need for grouping pages arises because Jekyll doesn't provide a filter to sort a list of pages on the value of an arbitrary expression.

Using Jekyll v4.2.2 (macOS 12.5, M2 MacBook Air, 16 GB memory), building https://github.com/endoflife-date/endoflife.date using https://github.com/pdmosses/just-the-docs/blob/fix-nav-performance/_includes/nav.html produced the following profile extract:

Filename                                                    | Count |    Bytes |   Time
------------------------------------------------------------|-------|----------|-------
| just-the-docs-0.4.0.rc1/_layouts/default.html                    |   130 |  3792.04K |  5.160 |
| _includes/nav.html                                               |   130 |  1405.20K |  4.054 |
| just-the-docs-0.4.0.rc1/_includes/head.html                      |   130 |   617.82K |  0.495 |
| _layouts/product.html                                            |   127 |  1014.38K |  0.413 |
| _includes/head_custom.html                                       |   130 |   427.83K |  0.393 |
| assets/js/zzzz-search-data.json                                  |     1 |   149.31K |  0.050 |

@nathancarter has tried adding the new `nav.html` to [a site with over 300 pages](https://nathancarter.github.io/how2data/site/), and reported that it improved the build time of more than 3 minutes to about 30 seconds.

Further optimisation of navigation might be possible (e.g., using [Jekyll include caching](https://github.com/benbalter/jekyll-include-cache)), but the current optimisation should be sufficient for v0.4.0.

To test that this PR does not appear to affect the navigation panel generated by v0.3.3:

1. Clone https://github.com/just-the-docs/just-the-docs-tests.
2. Update `_config.yml` and `Gemfile` to use this PR branch.
3. Run `bundle update`.
4. Inspect the rendering of the entire collection of navigation tests.

(Many of the differences reported in the GitHub visualisation of the changes are due to shifting much of the code 2 spaces to the left, in connection with moving the first `ul` element to be close to its first item.)

Why are these changes being introduced:

* The current tab order requires keyboard or screenreader users to tab
  though all of the navigation links before they get to the main content
  of the page

Relevant ticket(s):

* Discussed as part of larger WCAG ticket https://github.com/just-the-docs/just-the-docs/issues/566

How does this address that need:

* Introduces an off screen link as the first element in the tab order
  that will display when it has focus but remain off screen for users
  not using tab to navigate the document.
* Introduces a new scss file with the required style elements and uses
  colors variables to ensure both light and dark mode are respected.

Background information on this technique:

- https://www.w3.org/TR/WCAG20-TECHS/G1.html
- https://accessibility.oit.ncsu.edu/it-accessibility-at-nc-state/developers/accessibility-handbook/mouse-and-keyboard-events/skip-to-main-content/

This PR updates the home page and the CHANGELOG to refer to  v0.4.0.rc1 as a pre-release or release candidate, rather than a release. See [this comment](https://github.com/just-the-docs/just-the-docs/pull/613#issuecomment-1240442518) for motivation.

It also adds the versioned docs issue (#728) to the roadmap in the CHANGELOG.

As the config for the theme docs now needs to declare callouts, the [callouts docs](https://just-the-docs.github.io/just-the-docs/docs/ui-components/callouts/) can now illustrate the rendered appearance. (These callouts are merely examples: the names and colors should eventually be replaced by a principled collection, taking account of WCAG.)

Follow-up to #613. Relatively self-explanatory!

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

The jekyll-asciidoc plugin will take AsciiDoc markup like this:

	.A method that returns the string "Hello, world"
	[example]
	[source,ruby]
	----
	def hello
	  "Hello, world"
	end
	----

And produce HTML like this (syntax highlighting disabled):

	<div class="listingblock">
	  <div class="title">A method that returns the string "Hello, world"</div>
	  <div class="content">
	    <pre class="highlight"><code class="language-ruby" data-lang="ruby">def hello
	  "Hello, world"
	end</code></pre>
	  </div>
	</div>

Previously, because we were applying code block styling to the whole
listingblock, the title would be rendered as normal body text, inside
the code block, which did not look good.  With this change, it will
instead be rendered similarly to a Just The Docs rendered example —
the title will appear where the rendered example usually would.

Co-authored-by: Matt Wang <matt@matthewwang.me>

Adds accessible nav elements for nested pages

Why are these changes being introduced:

* The current links to show/hide the nested pages use a visual only
  svg image with no accessible affordance provided so screenreaders
  will not be able to provide appropriate context for users as to what
  they should expect when clicking these links
* You can see the problem by running a tool like ANDI on the current
  main branch of this repository and then running it again on this
  branch. ANDI shows what a screenreader would read.
* You can also use a tool like Voiceover to hear the importance of what
  this introduces to users that use that technology. Before this change,
  Voiceover would read all of these navigation links as
  "link image just-the-docs" but with this change it will read
  `link image toggle links in <categoryName> category`

Relevant ticket(s):

* This was discussed as part of the larger WCAG compliance ticket
  https://github.com/just-the-docs/just-the-docs/issues/566

How does this address that need:

* This adds an `aria-label` to the link https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label

Document any side effects to this change:

It appears it might be prefereable to use `aria-labelledby` whenever
possible, but from what I can tell these links are just the visual cue
of the svg with no other affordance given to users to understand what
they'll do so there is nothing to point `aria-labelledby` at.

An `svg` title was considered, but in reading more about it it seemed
like `aria-label` was more appropriate as it puts the label on the `a`
rather than the `svg` which feels more accurate.

* https://developer.mozilla.org/en-US/docs/Web/SVG/Element/title
* https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby



Co-authored-by: Matt Wang <matt@matthewwang.me>