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>
* Remove `jekyll-default-layout` plugin
* Move docs/navigation-structure to docs/navigation
* Fix uses of line-nos in md files
* Update CHANGELOG.md
---------
Co-authored-by: Matt Wang <matt@matthewwang.me>
In #1058, I noted:
> Tangentially related work:
> ...
> - better annotate new features (motivated by writing these docs)
> - we should add "New" to new features :)
> - we should note when a feature was introduced (I think this is a core part of most software documentation)
> - we should annotate things that are "Advanced" in so far as the average Just the Docs user will not use them / they require significant Jekyll knowledge
>
This came up again in https://github.com/just-the-docs/just-the-docs/discussions/1136#discussioncomment-4716253, so I think it's best for us to resolve this sooner rather than later.
This PR is me doing that. I:
- have added a headings-level "New" label to every new heading introduced since `v0.3`
- added, when possible, inline YAML comments when new configuration options have been introduced
I did this by scanning through the CHANGELOG and selecting each feature that is either tagged with `Add` and has documentation.
I may have also missed any new features, so some double-checking would be helpful!
In touching up the migration guide, I noticed that many of our documentation site links are broken! For example, on the homepage, this link:
<img width="782" alt="screenshot of homepage; code snippet is in next block" src="https://user-images.githubusercontent.com/14893287/210462690-31aa7bf5-dd79-4e8f-a3c5-1213e73771c4.png">
which has the following href
```code
<a href="/just-the-docs/just-the-docs/CHANGELOG/">the CHANGELOG</a>
```
duplicates the `baseurl` twice. There are 14 such broken links across the site. Each link duplicates the `baseurl` and `link` tags, which has since been resolved with links being relative by default (there's a set of PRs that document this - I can't find the exact paper trail right now).
To resolve this, I:
- find and replace site-wide `{{ site.baseurl }}{% link` with `{% link`
- tested each link, which now works properly locally *and* on the deploy preview
I'm surprised we didn't catch this earlier! I also could be missing something else, in which case feedback on this PR is certainly welcome.
This PR updates the home page and the CHANGELOG to refer to v0.4.0.rc1 as a pre-release or release candidate, rather than a release. See [this comment](https://github.com/just-the-docs/just-the-docs/pull/613#issuecomment-1240442518) for motivation.
It also adds the versioned docs issue (#728) to the roadmap in the CHANGELOG.
As the config for the theme docs now needs to declare callouts, the [callouts docs](https://just-the-docs.github.io/just-the-docs/docs/ui-components/callouts/) can now illustrate the rendered appearance. (These callouts are merely examples: the names and colors should eventually be replaced by a principled collection, taking account of WCAG.)
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>
