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>
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!
- add an extra filter to children-list to fix#854
- strengthen condition for assignment to first_level_url
Tested with Jekyll 3.9.2 and 4.2.2
Note: Jekyll 3.9.2 doesn't support `| where: "grand_parent: nil"`
**Rationale**
I would like to customize the site footer content without needing to override the entire default layout. Ideally, I'd like to shorten the attribution to something like "Built with Just the Docs"
**Implementation**
Create a new `site_footer.html` include that users can override.
**Possible changes**
I debated whether or not the `<footer class="site-footer">` should be in/out of the include. I opted for placing it inside the include so I have the option of disabling the footer entirely by creating an empty site_footer file in my site.
Co-authored-by: Matt Wang <matt@matthewwang.me>
Co-authored-by: Patrick Marsceill <pmarsceill@users.noreply.github.com>
* implements search placeholder configuration
* changes implementation approach to use search_placeholder_custom
Thanks to @pdmosses for the suggestion!
* strips whitespace and HTML for both placeholder and aria-label
This PR combines (and resolves conflicts between) #448, #463, #466, #494, #495, #496, #498, and #572.
The main aim is to facilitate use of several of the implemented features _together_, when using the fork as a remote theme. It should also simplify merging the included PRs into a future release.
The branch [combination-rec-nav](https://github.com/pdmosses/just-the-docs/tree/combination-rec-nav) adds [multi-level navigation](https://github.com/pmarsceill/just-the-docs/pull/462) and (NEW:) [sibling links](https://github.com/pmarsceill/just-the-docs/pull/394) to the branch used for this PR. It includes updated [documentation for the navigation structure](https://pdmosses.github.io/just-the-docs/docs/navigation-structure/), and reorganised and extended [navigation tests](https://pdmosses.github.io/just-the-docs/tests/navigation/). The documentation and the tests can be browsed at the (temporary) [website published from the combination-rec-nav branch](https://pdmosses.github.io/just-the-docs/).
_Caveat:_ The changes to v0.3.3 in this PR and #462 have not yet been reviewed or approved, and may need updating before merging into a release of the theme. If you use a branch from a PR as a remote theme, there is a risk of such updates affecting your website. Moreover, these branches are likely to be deleted after they have been merged. To avoid such problems, you could copy the branch that you want to use to your own fork of the theme.
Co-authored-by: Matt Wang <matt@matthewwang.me>
- Limit the effect of `nav_exclude: true` to the main navigation.
- Include links to excluded pages in auto-generating lists of child pages
and in breadcrumbs.
- Refactor implementation by moving assignment of `first_level_url` and `second_level_url` from `_includes/nav.html` to `_layouts/default.html`.
- Clarify the effect of `nav_exclude` in the documentation.
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.
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`.
Pages with `nav_exclude: true` were included when sorting on `title` or `nav_order`. That could cause build failures when the type of value of the field differs from that on other pages, as reported in https://github.com/pmarsceill/just-the-docs/issues/406.
Pages with `nav_exclude: true` or no `title` are never displayed in the navigation, so removing them from `pages_list` cannot break existing sites. This change also allows the removal of some tests in the code. (The indentation of the code should now be adjusted, but that has been deferred, to restrict the size of the diff for review.)
For testing, the title of `404.html` has been changed to the number `404`, the page `docs/untitled-test.md` has been added, and `nav_sort_order` has been set to `case_sensitive`. Those updates give build failures with the current version of `_includes/nav.html`, but not after the suggested changes.
It will still be possible for build failures to occur due to sorting fields of *non-excluded* pages with differing types of values (e.g., `nav_order`a mixture of numbers and strings). To make the code completely safe will require relatively complicated changes,.
Fixes a bug where content after headings in header elements disappeared.
Header elements are not currently used in JtD, but could make the HTML more semantic.
I ran Lighthouse on just-the-docs and noticed the anchor links
were missing a "discernible name".
This adds aria-labelledby to the header element to improve these for
screenreaders.
Added a configuration option to determine whether the sort order is case-sensitive.
The default is case-insensitive.
To test:
- open `/just-the-docs/docs/utilities/` in the browser,
and check that the navigation links in `Utilities` are sorted alphabetically;
- in `docs/utilities/layout.md', change the preamble to `title: layout`,
and check that the links in `Utilities` are still sorted alphabetically;
- add `nav_sort: case_sensitive` in the configuration file,
and check that the link to `layout` is now listed last under `Utilities`.
