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>
Just the Docs
A modern, highly customizable, and responsive Jekyll theme for documentation with built-in search.
Easily hosted on GitHub Pages with few dependencies.
A video walkthrough of various Just the Docs features
Installation
Use the template
The Just the Docs Template provides the simplest, quickest, and easiest way to create a new website that uses the Just the Docs theme. To get started with creating a site, just click "use the template"!
Note: To use the theme, you do not need to clone or fork the Just the Docs repo! You should do that only if you intend to browse the theme docs locally, contribute to the development of the theme, or develop a new theme based on Just the Docs.
You can easily set the site created by the template to be published on GitHub Pages – the template README file explains how to do that, along with other details.
If Jekyll is installed on your computer, you can also build and preview the created site locally. This lets you test changes before committing them, and avoids waiting for GitHub Pages.1 And you will be able to deploy your local build to a different platform than GitHub Pages.
More specifically, the created site:
- uses a gem-based approach, i.e. uses a
Gemfileand loads thejust-the-docsgem - uses the GitHub Pages / Actions workflow to build and publish the site on GitHub Pages
Other than that, you're free to customize sites that you create with the template, however you like. You can easily change the versions of just-the-docs and Jekyll it uses, as well as adding further plugins.
Use RubyGems
Alternatively, you can install the theme as a Ruby Gem, without creating a new site.
Add this line to your Jekyll site's Gemfile:
gem "just-the-docs"
And add this line to your Jekyll site's _config.yml:
theme: just-the-docs
And then execute:
$ bundle
Or install it yourself as:
$ gem install just-the-docs
Alternatively, you can run it inside Docker while developing your site
$ docker-compose up
Usage
View the documentation for usage information.
Contributing
Bug reports, proposals of new features, and pull requests are welcome on GitHub at https://github.com/just-the-docs/just-the-docs. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
Submitting code changes:
- Submit an Issue that motivates the changes, using the appropriate template
- Discuss the proposed changes with other users and the maintainers
- Open a Pull Request
- Ensure all CI tests pass
- Provide instructions to check the effect of the changes
- Await code review
Design and development principles of this theme:
- As few dependencies as possible
- No build script needed
- First class mobile experience
- Make the content shine
Development
To set up your environment to develop this theme: fork this repo, the run bundle install from the root directory.
A modern devcontainer configuration for VSCode is included.
Your theme is set up just like a normal Jekyll site! To test your theme, run bundle exec jekyll serve and open your browser at http://localhost:4000. This starts a Jekyll server using your theme. Add pages, documents, data, etc. like normal to test your theme's contents. As you make modifications to your theme and to your content, your site will regenerate and you should see the changes in the browser after a refresh, just like normal.
When this theme is released, only the files in _layouts, _includes, and _sass tracked with Git will be included in the gem.
License
The theme is available as open source under the terms of the MIT License.