Bumps [stylelint](https://github.com/stylelint/stylelint) from 14.13.0 to 14.14.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.13.0...14.14.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>

The regression tests in https://just-the-docs.github.io/just-the-docs-tests/navigation/grandparent/index/ include a section "A grandchild with the same parent title as a child or top-level page". Its last item fails, as can currently be seen at https://just-the-docs.github.io/just-the-docs-tests/navigation/grandparent/f/ : the first occurrence of `G` links to the grandchild of `E`., and shouldn't be included.

The regression can be fixed by changing `where: "grand_parent", page.parent` to `where_exp: "item", "item.grand_parent == page.parent"`. This should be apparent  when running the regressions tests with this PR branch as remote theme.

The two filters give the same results in Jekyll 4, but not in Jekyll 3. It seems that this was overlooked because the sanity-testing of v0.4.0.rc3 was inadvertently using Jekyll 4.2.2.

Fix external links and collections

The navigation should only display the external links once, after the links to pages that are not in collections.

The test for PR #876 at https://just-the-docs.github.io/just-the-docs-tests/navigation/external-links fails with v0.4.0.rc3,
and succeeds when the updated `nav.html` is added locally.

The docs need updating to clarify how the interaction between the collections feature and the external links feature is resolved.

GitHub with one `h` rather than two!

* 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>

* 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.)