Updated just-the-doc #15
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Bumps [stylelint](https://github.com/stylelint/stylelint) from 16.8.2 to 16.9.0. - [Release notes](https://github.com/stylelint/stylelint/releases) - [Changelog](https://github.com/stylelint/stylelint/blob/main/CHANGELOG.md) - [Commits](stylelint/stylelint@16.8.2...16.9.0) --- updated-dependencies: - dependency-name: stylelint dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Splitting this out of just-the-docs#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 <[email protected]>
…e-docs#1531) This PR fixes some accessibility issues in our theme docs (i.e. not generated code) flagged by just-the-docs#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 just-the-docs#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 just-the-docs#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: just-the-docs#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 <[email protected]>
Bumps [jekyll](https://github.com/jekyll/jekyll) from 4.3.3 to 4.3.4. - [Release notes](https://github.com/jekyll/jekyll/releases) - [Changelog](https://github.com/jekyll/jekyll/blob/master/History.markdown) - [Commits](jekyll/jekyll@v4.3.3...v4.3.4) --- updated-dependencies: - dependency-name: jekyll dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Bumps [google-protobuf](https://github.com/protocolbuffers/protobuf) from 4.28.1 to 4.28.2. - [Release notes](https://github.com/protocolbuffers/protobuf/releases) - [Changelog](https://github.com/protocolbuffers/protobuf/blob/main/protobuf_release.bzl) - [Commits](https://github.com/protocolbuffers/protobuf/commits) --- updated-dependencies: - dependency-name: google-protobuf dependency-type: indirect ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Bump main Ruby version to 3.3, change Node to 20.x (LTS)
Bumps [stylelint](https://github.com/stylelint/stylelint) from 16.9.0 to 16.10.0. - [Release notes](https://github.com/stylelint/stylelint/releases) - [Changelog](https://github.com/stylelint/stylelint/blob/main/CHANGELOG.md) - [Commits](stylelint/stylelint@16.9.0...16.10.0) --- updated-dependencies: - dependency-name: stylelint dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Bumps [rexml](https://github.com/ruby/rexml) from 3.3.7 to 3.3.9. - [Release notes](https://github.com/ruby/rexml/releases) - [Changelog](https://github.com/ruby/rexml/blob/master/NEWS.md) - [Commits](ruby/rexml@v3.3.7...v3.3.9) --- updated-dependencies: - dependency-name: rexml dependency-type: indirect ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Bumps [webrick](https://github.com/ruby/webrick) from 1.8.1 to 1.8.2. - [Release notes](https://github.com/ruby/webrick/releases) - [Commits](ruby/webrick@v1.8.1...v1.8.2) --- updated-dependencies: - dependency-name: webrick dependency-type: indirect ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.