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>

docs/navigation/main/ancestry.md

@@ -10,7 +10,8 @@ If no two pages on your website have the same `title`, you only need to set the
 
 If two parents have the same `title`, but different grandparents, you can set their `grand_parent` titles to distinguish between their parents. The `grand_parent` title needs to be the same as the `parent` of the `parent`.
 
-#### Example
+## Example: distinguishing parents with `grand_parent`
+{: .text-delta }
 
 ```yaml
 ---

docs/navigation/main/collections.md

@@ -14,7 +14,8 @@ However, you can configure Just the Docs to include also pages from [Jekyll coll
 
 [^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
+## 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`:
 
@@ -41,9 +42,10 @@ Together with the `name` to be used for a collection in the navigation, you can
 
 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.
 
-You can configure multiple collections. This creates categories in the main navigation with the configured names.
+## Example: multiple collections
+{: .text-delta }
 
-#### Example
+You can configure multiple collections. This creates categories in the main navigation with the configured names.
 
 ```yaml
 collections:

docs/navigation/main/exclude.md

@@ -8,7 +8,8 @@ nav_order: 2
 
 For specific pages that you do not wish to include in the main navigation (e.g., a 404 page or a landing page) set `nav_exclude: true` in their front matter.
 
-#### Example
+## Example: using `nav_exclude`
+{: .text-delta }
 
 ```yaml
 ---
@@ -19,7 +20,7 @@ permalink: /404
 ---
 ```
 
-The `nav_exclude` parameter does not affect the [breadcrumbs]({% link docs/navigation/parents.md %}), nor the [lists of child pages]({% link docs/navigation/children.md %}), which you can use to access pages excluded from the main navigation. 
+The `nav_exclude` parameter does not affect the [breadcrumbs]({% link docs/navigation/parents.md %}), nor the [lists of child pages]({% link docs/navigation/children.md %}), which you can use to access pages excluded from the main navigation.
 
 Pages with no `title` are automatically excluded from the main navigation, except when they are in collections (where Jekyll provides default titles based on file names).
 

docs/navigation/main/external.md

@@ -9,7 +9,8 @@ nav_order: 6
 To add external links to the navigation, add them to the `nav_external_links` [configuration]({% link docs/configuration.md %}) option in your site's `_config.yml` file.
 External links will appear in the navigation after the links to ordinary pages, but before any collections.
 
-#### Example
+## Example: external links
+{: .text-delta }
 
 ```yaml
 # External navigation links

docs/navigation/main/levels.md

@@ -31,7 +31,8 @@ Sometimes you will want to create a page with many children. First, it is recomm
 └─ ...
 ```
 
-#### Example
+## Example: page with no parents
+{: .text-delta }
 
 ```yaml
 ---
@@ -42,13 +43,14 @@ nav_order: 3
 
 Here we're setting up the UI Components landing page that is available at URL `/docs/ui-components`, which is ordered second in the main navigation.
 
-The navigation links for all pages with children come with an expander. When you click the expander, the display of the children is toggled, so you can expand or collapse all the children displays, regardless of which page is currently active. 
+The navigation links for all pages with children come with an expander. When you click the expander, the display of the children is toggled, so you can expand or collapse all the children displays, regardless of which page is currently active.
 
 ## Child Pages
 
 On child pages, simply set the `parent` front matter to the parent page's `title`, and set a navigation order (relative to pages having the same parent).
 
-#### Example
+### Example: creating a child page
+{: .text-delta }
 
 ```yaml
 ---
@@ -67,9 +69,10 @@ The Buttons page appears as a child of UI Components and appears second in the U
 
 ## Multi-level Child Pages
 
-Child pages can themselves have children, to any number of levels. 
+Child pages can themselves have children, to any number of levels.
 
-#### Example
+### Example: pages with (recursive) children
+{: .text-delta }
 
 ```yaml
 ---

docs/navigation/main/order.md

@@ -8,7 +8,8 @@ nav_order: 1
 
 To specify a page order, you can use the `nav_order` parameter in the front matter of the pages.
 
-#### Example
+## Example: using `nav_order`
+{: .text-delta }
 
 ```yaml
 ---
@@ -30,6 +31,6 @@ Enclosing strings in quotation marks in front matter is optional, unless they co
 
 ----
 
-[^floats]: Jekyll treats each integer *N* as equal to the corresponding float *N.0*. 
+[^floats]: Jekyll treats each integer *N* as equal to the corresponding float *N.0*.
 
-[^case-insensitive]: *Note for users of previous versions of Just the Docs:* The option `nav_sort: case_insensitive` previously affected the ordering of numerical `nav_order` parameters: e.g., `10` came before `2`. Also, all pages with explicit `nav_order` parameters previously came before all pages with default parameters. Both were potentially confusing, and they have now been eliminated. 
+[^case-insensitive]: *Note for users of previous versions of Just the Docs:* The option `nav_sort: case_insensitive` previously affected the ordering of numerical `nav_order` parameters: e.g., `10` came before `2`. Also, all pages with explicit `nav_order` parameters previously came before all pages with default parameters. Both were potentially confusing, and they have now been eliminated.