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>
2.4 KiB
| title | parent | nav_order |
|---|---|---|
| In-Page Navigation | Navigation | 5 |
In-Page Navigation
{: .no_toc }
Table of Contents
{: .no_toc .text-delta }
- TOC {:toc}
To support in-page navigation, you can generate a Table of Contents (TOC) with links to headings, like the one shown above, as well as a link to the top of the page.
Generating Table of Contents
To generate a Table of Contents in a page, you use Kramdown's {:toc} method, immediately after the start of a list. This will automatically generate a list of anchor links to various sections of the page, based on headings and heading levels.
Omitting Heading from Table of Contents
If you want to omit a particular heading from the TOC, follow it immediately by {: .no_toc } (possibly together with other CSS class names).
# In-Page Navigation
{: .no_toc }
## Table of Contents
{: .no_toc .text-delta }
1. TOC
{:toc}
This example omits the top-level heading (In-Page Navigation) from the TOC, as well as the heading for the Table of Contents itself.
To get an unordered list, replace 1. TOC by - TOC in the above example.
Collapsible Table of Contents (with <details> and <summary>)
You can make the Table of Contents collapsible using the <details> and <summary> elements, as in the following example.
<details open markdown="block">
<summary>
Table of contents
</summary>
{: .text-delta }
1. TOC
{:toc}
</details>
The attribute open (which expands the Table of Contents by default) and the styling (here with text-delta) are optional.
{: .note }
{:toc} can be used only once on each page.
Back to Top
{: .warning }
The default id for a section with heading "Back to Top" is "back-to-top".
To avoid invalid HTML, sites that set the back_to_top configuration variable
should override the default id for such sections. The Markdown source file for
the current page uses ## Back to Top {#back-to-top-doc}.
You can add a link from the bottom of each page to its top. You do this by including the back_to_top configuration option in your site's _config.yml file, together with back_to_top_text for the anchor link.
Example
{: .no_toc }
back_to_top: true
back_to_top_text: "Back to top"
{: .warning } Back-to-top links currently appear only when other configuration options require footer generation!