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.
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.)
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.)
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>
A couple of changes to prep for v0.4.0-rc1:
- bump the version
- add myself to the authors + email (this is primarily so that Patrick doesn't get siloed as the only maintainer; if you'd like to be added @just-the-docs/maintainers, let me know!)
- adds some more metadata ([gemspec docs](https://guides.rubygems.org/specification-reference/#metadata))
- updated the path to also include the CHANGELOG and favicon in the gem bundle
This PR has a bit of scope creep! This PR now:
- changes the mermaid opt-in logic to only check for the existence of a `mermaid` key instead of `mermaid != false`: this resolves the follow-up in #857
- changes the behaviour of mermaid configuration
- instead of using `mermaid_init.html` with default settings, makes the include `mermaid_config.js`
- the include is loaded directly into the contents of `mermaid_initialize`
- by default, it is an empty object (i.e. `{}`), triggering the defaults
- updates docs
- adds an example to the markdown kitchen sink
It does significantly change the interface provided in #857, and I apologize for the confusion. However, given the discussion in this PR, I think it's the best move forward!
The nav scroll feature had stopped working (altogether),
due to the change from absolute to relative urls.
This update uses the document location pathname as the `href`.
It appears to work locally.
