mirror of
https://github.com/snachodog/just-the-docs.git
synced 2025-04-20 10:02:23 -06:00
8292f46be9
This PR fixes some accessibility issues in our theme docs (i.e. not generated code) flagged by #1513. Here, I target changes that I say are not "systemic", i.e. issues that are easily resolvable by changing our copy and page structure (rather than issues that are created by how kramdown/rouge generates HTML, or reworking our color themes). Here's a quick summary of the manual changes I made: - ~~writing some JS to set `tabindex="0"` on all code blocks; I'd prefer a ruby-native solution, but that involves writing Ruby code, which is incompatible with the pages gem~~ I've moved this to #1533 - rewriting many headings named "Example" which were almost always h4s into more descriptive headings + the appropriate heading level, adding .text-delta to maintain the previous style when necessary - removing some old heading ID hacks in `index-test` that are no longer necessary, since Jekyll does this automatically now - fixing the table headings in `docs/utilities/layout.md` - adding accessible titles + descriptions to the mermaid examples - occasionally, slightly moving around copy to make it align with new headings If you test with #1513 with the following rules disabled: ```rb skipped_rules = [ 'color-contrast', # requires theme auditing # issues w/ autogenerated footnotes 'aria-allowed-role', 'landmark-no-duplicate-contentinfo', 'landmark-unique', 'aria-deprecated-role', # issues w/ markdown checkboxes 'label' ] ``` You should get passing tests :) which is awesome! ## next steps 1. we need to do a pass over our docs copy - very inconsistent. This has been a pain point for me for a while now, just need to find time to sit down and do it. In particular, I'd love to standardize how we display example code (perhaps even hiding it with `<details>` and `<summary>`?), our headings language, what goes into the ToC, our overall writing style, etc. 2. ~~I don't love the JS hack for adding `tabindex="0"` to code blocks (so that they are keyboard-focusable). Ideally, we'd add a custom formatter to rouge to do this, but we can't execute arbitrary Ruby code when users use `github-pages`. I'll look into this some more - maybe rouge would be open to adding this as a feature.~~ see: #1533 4. There are some systemic issues that need a deeper look: 1. The most common issue is still color-contrast. Fixing this involves: - looking at our whites/blacks/grays for core text and highlighting - reevaluating our syntax highlighting themes - fixing dark mode, once and for all :) - also, picking accessible callout colours! 2. kramdown's autogenerated footnotes feature creates a bunch of errors that aXe flags: it seems like a deprecated aria role is being used, and perhaps some misuse of markup. Need to look into this more before I can make a solid attempt at resolving this issue. 3. We demonstrate the use of `- [ ]`, but this generates `<input type="checkbox">` values with no label. I'm not entirely sure what the best way to fix this problem is (without writing custom Ruby code). I'll have to think about this some more. --------- Co-authored-by: Michael Ball <michael@mball.co>
70 lines
2.3 KiB
Markdown
70 lines
2.3 KiB
Markdown
---
|
|
title: Collections
|
|
parent: Main Navigation
|
|
nav_order: 5
|
|
---
|
|
|
|
# Collections
|
|
|
|
By default, the navigation includes only [normal pages](https://jekyllrb.com/docs/pages/).
|
|
However, you can configure Just the Docs to include also pages from [Jekyll collections](https://jekyllrb.com/docs/collections/).
|
|
|
|
{: .note }
|
|
> You store collection pages in directories that start with an underscore (`_`), e.g., `_tests`. You won't see your `tests` collection pages in the navigation if you store them in a `tests` directory![^1]
|
|
|
|
[^1]: You can optionally specify a directory to store all your collections. For example, if you specify `collections_dir: my_collections` in `_config.yml`, you should then store the pages of the `tests` collection in the `my_collections/_tests` directory.
|
|
|
|
## Example: defining custom collections
|
|
{: .text-delta }
|
|
|
|
To define a Jekyll `tests` collection named `Tests` in your main navigation, store its pages in the `_tests` directory, and add the following to `_config.yml`:
|
|
|
|
```yaml
|
|
collections:
|
|
tests:
|
|
output: true
|
|
|
|
just_the_docs:
|
|
collections:
|
|
tests:
|
|
name: Tests
|
|
```
|
|
|
|
Together with the `name` to be used for a collection in the navigation, you can configure the following options:
|
|
|
|
* `nav_exclude: true` to exclude the entire collection from the main navigation
|
|
* `nav_fold: true` to fold the collection, instead of showing links to all its top-level pages[^2]
|
|
* `search_exclude: true` to exclude all the collection pages from search results
|
|
|
|
[^2]:
|
|
When JavaScript is disabled in the browser, all folded collections are automatically expanded,
|
|
since clicking expander symbols has no effect.
|
|
|
|
The main navigation for all your normal pages (if any) is displayed before those in collections. When *all* your pages are in a single collection, its name is not displayed.
|
|
|
|
## Example: multiple collections
|
|
{: .text-delta }
|
|
|
|
You can configure multiple collections. This creates categories in the main navigation with the configured names.
|
|
|
|
```yaml
|
|
collections:
|
|
tests:
|
|
output: true
|
|
tutorials:
|
|
output: true
|
|
|
|
just_the_docs:
|
|
collections:
|
|
tests:
|
|
name: Tests
|
|
search_exclude: true
|
|
tutorials:
|
|
name: Tutorials
|
|
nav_fold: true
|
|
```
|
|
|
|
The navigation for each collection is a separate name space for page titles: a page in one collection cannot be the `parent` of a page in a different collection, nor of a normal page.
|
|
|
|
----
|