mirror of https://github.com/snachodog/just-the-docs.git synced 2025-04-10 14:01:22 -06:00

docs: fix (non-systemic) accessibility issues flagged by aXe (#1531 )

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>

2024-09-06 13:18:26 -07:00

2.3 KiB

Raw Blame History

title	parent	nav_order
Collections	Main Navigation	5

Collections

By default, the navigation includes only normal pages. However, you can configure Just the Docs to include also pages from Jekyll 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¹

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:

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²
search_exclude: true to exclude all the collection pages from search results

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.

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.

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. ↩︎
When JavaScript is disabled in the browser, all folded collections are automatically expanded, since clicking expander symbols has no effect. ↩︎

2.3 KiB Raw Blame History

Collections

Example: defining custom collections

Example: multiple collections

2.3 KiB

Raw Blame History