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>
Splitting this out of #1513 to make my life reviewing a bit easier! Note that this does *not* affect our downstream users, just the docs site for this project itself.
---------
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>
* Allow unlimited multi-level navigation
This PR supersedes #462.
The only user-level difference from #462 is that disambiguation of parent pages has to use either `grand_parent` or `ancestor` titles: the somewhat unnatural `section_id` and `in_section` fields are not supported.
The implementation has been significantly simplified by the changes introduced in v0.7.0 of the theme.
* Detect cyclic parenthood
A page should not have a parent or ancestor with the same title. If it does, the location of the repeated link is marked by ∞, to facilitate debugging the navigation (and an unbounded loop leading to a build exception is avoided).
* Add nav_error_report warning in main navigation
When activated by `nav_error_report: true` in `_config.yml`, displays warnings about pages with the same title as their parent page or an ancestral page.
* Cache site-nav with links to all pages
The extra cached site-nav is used for determining breadcrumbs and children navigation, which may involve pages that are excluded from the main navigation.
* Replace code for determining children by inclusion of components/nav/children.html
* Update CHANGELOG.md
---------
Co-authored-by: Matt Wang <matt@matthewwang.me>
Changes are in three categories:
- whitespace
- devendoring prefixes for properties that have entered the CSS spec - reasonable to autofix
- removing a duplicate `monospace` in `monospace, monospace` `font-family` decl in normalize.scss - not autofix
Seems like this major update isn't caught by dependabot. Should be a straightforward upgrade!
Separately, going to plan on removing files from our `ignoreFiles` -- in particular, auditing our vendor files (which have some issues).
* Add nav_enabled variables for site/layout/page-level control
* _sass: Add a space around `+` operator
* assets: Do not compile based on site.nav_enabled
* _config.yml: nav_enabled can be selectively enabled
* CHANGELOG.md: Add nav_enabled feature and docs
* docs: Prefer em dash in describing minimal layout
* docs: Add section on Selectively hiding or showing the sidebar
* _layouts: Display sidebar based on variable importance
* docs: Update documentation on the minimal layout
* docs: Document site.nav_enabled configuration variable
---------
Co-authored-by: Matt Wang <matt@matthewwang.me>
This PR essentially updates the "default" Ruby version to 3.3. In the process, it:
- fixes a bug with the linux platform for `sass-embedded`
- regenerates the `Gemfile.lock` with Bundler 2.5.9
- adds Ruby 3.3 to the testing matrix & updates our deployment actions to use Ruby 3.3
- removes Ruby 3.0 from the testing matrix, as it is now end of life
This PR is motivated by https://github.com/just-the-docs/just-the-docs-template/pull/45, where I discovered that depending on the bundler/RubyGems version, the platform resolution for platformed gems can fail.
Fix#1445
Front matter defaults with unrestricted `scope` (`path: ""`) can affect theme code files. [Jekyll](https://jekyllrb.com/docs/front-matter/#predefined-global-variables) supports using `null` to "produce a file without using a layout file".
This PR adds `layout: null` to `just-the-docs.js`, to avoid this file being affected by the following front matter defaults:
```yaml
defaults:
-
scope:
path: ""
values:
layout: "default"
```
We are running into an issue upgrading from 0.7 to 0.8, suggesting that `trim` is not a method.
```
1.963 Liquid Exception: Liquid error (/usr/gem/gems/just-the-docs-0.8.0/_includes/components/breadcrumbs.html line 59): undefined filter trim included in /_layouts/default.html
1.968 /usr/gem/gems/liquid-4.0.4/lib/liquid/strainer.rb:58:in `invoke': Liquid error (/usr/gem/gems/just-the-docs-0.8.0/_includes/components/breadcrumbs.html line 59): undefined filter trim included (Liquid::UndefinedFilter)
```
Looking at the liquid docs, we're probably looking for `strip` and not `trim`
https://shopify.github.io/liquid/filters/strip/https://github.com/Shopify/liquid/blob/main/History.md#300--2014-11-12, I don't see a trim so it may have been an extension? This does work normally on just-the-docs itself running from scratch, so it might also be a bug in our application (or combination of different versions in plugins).
Adds a keyboard shortcut to use Ctrl/Cmd and a configurable key to focus the search input. The key is configurable with `search.focus_shortcut_key`; enables it on the core docs site with `'k'` (default on many sites).
---------
Co-authored-by: Matt Wang <mxw@cs.washington.edu>
Closes#1392.
Unfortunately, this PR has not actually diagnosed the root problem with the `scrollBy` calculation/method and Safari. However, by using the [`scrollIntoView`](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView) function (which essentially does what the calculation was meant to do), this problem is "magically" solved! As a side effect, I think this makes the code easier to maintain (I myself was thinking: why is there a magic `3` multiplier?).
~~I will point out that this does change *how much is scrolled*; following the spec for the method, the sidebar is now scrolled so that the active navigation link is top-aligned with the scroll container (which in this case, is the navigation sidebar's "cutoff"). I personally am fine with this change, but happy to fiddle around (e.g. we could vertically align to the `center` via [`scrollIntoViewOptions`](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView#parameters), though I'm not sure if this causes compatability problems).~~
I will point out that this does change *how much is scrolled*; we are now using the `center` option to `scrollBy`, which centers the target link. As Peter has commented in the PR thread, this seems to be the best compromise for maintaining the spirit of the previous calculation.
### testing
Peter did a great job writing a reproducible bug report in #1392. To test this,
1. first, follow the instructions verbatim on `main`. observe that the bug appears on Safari on macOS, but not Firefox and Chrome
2. then, apply this change (e.g. check out the branch)
3. next, replay the instructions - observing that
1. the bug is fixed on Safari
2. there is no change to the behaviour on Firefox and Chrome (other than the "start" of the scroll")
### compatability
On [Can I use](https://caniuse.com/scrollintoview), `scrollIntoView` has 98.15% adoption (the only "major" holdout being Opera Mini); and, the partial support from IE is about an option that we don't use. So, I'm pretty confident that we should be able to roll out this change without our users being locked out by a new-ish method.
Added link and short blurb about document collections to the navigation structure page, for quicker reference and suggestion during reading documentation.
Allows easier reference when trying to create page groups / categories without using a blank Parent page. Avoids automatically folded Parent page when Child pages are the necessary ones.
