Introduce handling for accessible/semantic note rendering in HTML #3907

chriskrycho · 2024-04-29T19:46:33Z

Integrates the work I did over at mdbook-trpl-note to render quotes > which are intended to act as callouts/admonitions/notes as accessible, semantic HTML using <section> tags with the appropriate ARIA labels. This actually pulls over the history from that repo as well.¹
In support of that, refactors things a bit in the repo: this is now a Cargo workspace. We can choose to split out the other binaries later if we so choose, but it made it easier to integrate this existing project this way. It could also make it much easier to develop a support crate in-tree, especially for the async-await stuff where we are going to need to manage dependencies—futures at a minimum but almost certainly also a runtime.
Add CSS so the new note rendering matches the existing rendering of blockquotes. (We might want to change that at some point, but for now the goal is to maximizing continuity.)
Introduce a custom book.toml for the nostarch directory and update the configuration for it.
Modernizes a number of the library usage sites in the tools package: we don’t need extern crate or #[macro_use] anymore, thankfully!

Using the equivalent of git merge --allow-unrelated-histories, though in this case just via jj new. Jujutsu is great! ↩

- Rework the `rewrite` function to spit back out Markdown instead of going all the way to HTML. - Implement the `Preprocessor` type and wire up a CLI conforming to the mdBook preprocessor spec. - Add relevant deps, including for an integration test.

This kind of thing works now: ```markdown > ## Something Big > > Here is the content! ``` The book does a lot of that (not just `> Note: …`). 😅

Trying to make changes to this made my head hurt: the fundamental split is on the state, *not* on the tag. So flip it.

In a scenario like this: ```markdown > This is a quote. > Note: this is a note ``` The result should be this output: ```markdown > This is a quote. <section class="note" aria-label="Note" aria-role="note"> Note: this is a note </section> ``` The same goes for heading-type notes, and for the inverted flow.

My inspiration for these included the `aria-label` because the notes did not have a label like `Note: ` or a heading on them; these do, though. Keep the `aria-role` so screen readers present notes distinctively the same way the visual presentation is set off. Fix README: remove `aria-label` from there as well

In the destination, this will be part of a Cargo workspace, and should *not* be in the root, where a merge will conflict with the workspace Cargo config etc.

This will let us pull in, and work directly on, things like the `mdbook-trpl-notes` preprocessor.

I developed this in its own repo before we knew how we wanted to integrate it. We decided on a workspace, so this pulls it in with all its development history.

Use the newly-introduced `mdbook-trpl-note` to render accessible and semantic HTML for the notes/callouts in the book. This currently applies to the nostarch version as well, so a follow-on change will update the build process to undo that. Add CSS so the new note rendering matches the existing rendering of blockquotes. (We might want to change that at some point, but for now the goal is to maximizing continuity.)

Introduce a `book.toml` in the `nostarch` directory, which matches the existing `book.toml` except for specifying the correct relative input and output directories and disabling the `trpl-note` preprocessor. This also lets us simplify the invocation in the `nostarch.sh` script a bit, by providing the configuration directly in the file.

- Add building `mdbook-trpl-note` to the relevant workflow. - Explicitly exclude `linkcheck` from new workspace.

Update books ## rust-lang/book 3 commits in d207d894cc5e1d496ab99beeacd1a420e5d4d238..bebcf527e67755a989a1739b7cfaa8f0e6b30040 2024-04-30 02:06:57 UTC to 2024-04-25 21:04:25 UTC - [ch10-03] Fix wording change about mandatory type annotation (rust-lang/book#3904) - Introduce handling for accessible/semantic note rendering in HTML (rust-lang/book#3907) - Backport changes from print for ch7 (rust-lang/book#3901) ## rust-embedded/book 1 commits in aa7d4b0b4653ddb47cb1de2036d090ec2ba9dab1..17842ebb050f62e40a4618edeb8e8ee86e758707 2024-05-01 13:23:40 UTC to 2024-05-01 13:23:40 UTC - Update embedded rust debugging section of tooling.md (rust-embedded/book#369) ## rust-lang/reference 1 commits in 5854fcc286557ad3ab34d325073d11d8118096b6..51817951d0d213a0011f82b62aae02c3b3f2472e 2024-04-27 17:54:45 UTC to 2024-04-27 17:54:45 UTC - Add docs for `#[collapse_debuginfo]` attribute (rust-lang/reference#1468) ## rust-lang/rust-by-example 3 commits in 60d34b5fd33db1346f9aabfc0c9d0bda6c8e42be..229ad13b64d919b12e548d560f06d88963b25cd3 2024-05-06 00:15:45 UTC to 2024-04-24 18:29:38 UTC - Missing import (rust-lang/rust-by-example#1841) - Added missing word (rust-lang/rust-by-example#1838) - Raw string literal can contain up to 255 #s according to Rust Reference (rust-lang/rust-by-example#1839) ## rust-lang/rustc-dev-guide 5 commits in 07425fed36b00e60341c5e29e28d37d40cbd4451..2d1947ff34d50ca46dfe242ad75531a4c429bb52 2024-05-06 06:48:21 UTC to 2024-04-28 18:31:21 UTC - Add documentation for check-cfg by-default in UI tests (rust-lang/rustc-dev-guide#1966) - Add documentation on Apple notification group (rust-lang/rustc-dev-guide#1964) - Update CI documentation to avoid mentioning `expand-yaml-anchors` (rust-lang/rustc-dev-guide#1971) - Rename `-Z verbose` to `-Z verbose-internals` (rust-lang/rustc-dev-guide#1968) - typo traige->triage (rust-lang/rustc-dev-guide#1967)

Rollup merge of rust-lang#124815 - rustbot:docs-update, r=ehuss Update books ## rust-lang/book 3 commits in d207d894cc5e1d496ab99beeacd1a420e5d4d238..bebcf527e67755a989a1739b7cfaa8f0e6b30040 2024-04-30 02:06:57 UTC to 2024-04-25 21:04:25 UTC - [ch10-03] Fix wording change about mandatory type annotation (rust-lang/book#3904) - Introduce handling for accessible/semantic note rendering in HTML (rust-lang/book#3907) - Backport changes from print for ch7 (rust-lang/book#3901) ## rust-embedded/book 1 commits in aa7d4b0b4653ddb47cb1de2036d090ec2ba9dab1..17842ebb050f62e40a4618edeb8e8ee86e758707 2024-05-01 13:23:40 UTC to 2024-05-01 13:23:40 UTC - Update embedded rust debugging section of tooling.md (rust-embedded/book#369) ## rust-lang/reference 1 commits in 5854fcc286557ad3ab34d325073d11d8118096b6..51817951d0d213a0011f82b62aae02c3b3f2472e 2024-04-27 17:54:45 UTC to 2024-04-27 17:54:45 UTC - Add docs for `#[collapse_debuginfo]` attribute (rust-lang/reference#1468) ## rust-lang/rust-by-example 3 commits in 60d34b5fd33db1346f9aabfc0c9d0bda6c8e42be..229ad13b64d919b12e548d560f06d88963b25cd3 2024-05-06 00:15:45 UTC to 2024-04-24 18:29:38 UTC - Missing import (rust-lang/rust-by-example#1841) - Added missing word (rust-lang/rust-by-example#1838) - Raw string literal can contain up to 255 #s according to Rust Reference (rust-lang/rust-by-example#1839) ## rust-lang/rustc-dev-guide 5 commits in 07425fed36b00e60341c5e29e28d37d40cbd4451..2d1947ff34d50ca46dfe242ad75531a4c429bb52 2024-05-06 06:48:21 UTC to 2024-04-28 18:31:21 UTC - Add documentation for check-cfg by-default in UI tests (rust-lang/rustc-dev-guide#1966) - Add documentation on Apple notification group (rust-lang/rustc-dev-guide#1964) - Update CI documentation to avoid mentioning `expand-yaml-anchors` (rust-lang/rustc-dev-guide#1971) - Rename `-Z verbose` to `-Z verbose-internals` (rust-lang/rustc-dev-guide#1968) - typo traige->triage (rust-lang/rustc-dev-guide#1967)

chriskrycho added 18 commits April 25, 2024 16:48

Implement functionality for actual rewrite

da52d2a

Rename to mdbook-simple-note. No need to be so verbose!

077b0c9

Add support for headings.

563d52b

This kind of thing works now: ```markdown > ## Something Big > > Here is the content! ``` The book does a lot of that (not just `> Note: …`). 😅

Rename to mdbook-trpl-note. This is *very* specific.

301c704

Invert the order of the pattern match for readability.

5f19f77

Trying to make changes to this made my head hurt: the fundamental split is on the state, *not* on the tag. So flip it.

Do *not* remove the leading “Note: ” from notes.

804a6ad

Rename header tests for clarity (prep for adding more tests!).

215420a

Prepare to merge into TRPL repo

3032068

In the destination, this will be part of a Cargo workspace, and should *not* be in the root, where a merge will conflict with the workspace Cargo config etc.

Convert to a workspace

f48b281

This will let us pull in, and work directly on, things like the `mdbook-trpl-notes` preprocessor.

Modernize tools package contents

da9e96e

Merge mdbook-trpl-note into the repository

456a8dc

I developed this in its own repo before we knew how we wanted to integrate it. We decided on a workspace, so this pulls it in with all its development history.

Make mdbook a workspace root dependency

33fb62e

Update CI config for workspace and mdbook-trpl-note

427f7d3

- Add building `mdbook-trpl-note` to the relevant workflow. - Explicitly exclude `linkcheck` from new workspace.

chriskrycho force-pushed the chriskrycho/semantic-notes branch from 47c404f to 427f7d3 Compare April 29, 2024 22:19

chriskrycho merged commit 7813712 into main Apr 30, 2024
4 checks passed

chriskrycho deleted the chriskrycho/semantic-notes branch April 30, 2024 02:09

rustbot mentioned this pull request May 6, 2024

Update books rust-lang/rust#124815

Merged

ehuss mentioned this pull request May 16, 2024

preprocessors need to be integrated with the rust build system #3927

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Introduce handling for accessible/semantic note rendering in HTML #3907

Introduce handling for accessible/semantic note rendering in HTML #3907

chriskrycho commented Apr 29, 2024 •

edited

Loading

Introduce handling for accessible/semantic note rendering in HTML #3907

Introduce handling for accessible/semantic note rendering in HTML #3907

Conversation

chriskrycho commented Apr 29, 2024 • edited Loading

Footnotes

chriskrycho commented Apr 29, 2024 •

edited

Loading