Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 18 commits into from
Apr 30, 2024

Commits on Apr 25, 2024

  1. Configuration menu
    Copy the full SHA
    da52d2a View commit details
    Browse the repository at this point in the history

Commits on Apr 26, 2024

  1. Integrate rewrite into an mdBook preprocessor

    - 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.
    chriskrycho committed Apr 26, 2024
    Configuration menu
    Copy the full SHA
    d098a33 View commit details
    Browse the repository at this point in the history
  2. Configuration menu
    Copy the full SHA
    077b0c9 View commit details
    Browse the repository at this point in the history
  3. Add support for headings.

    This kind of thing works now:
    
    ```markdown
    > ## Something Big
    >
    > Here is the content!
    ```
    
    The book does a lot of that (not just `> Note: …`). 😅
    chriskrycho committed Apr 26, 2024
    Configuration menu
    Copy the full SHA
    563d52b View commit details
    Browse the repository at this point in the history
  4. Configuration menu
    Copy the full SHA
    301c704 View commit details
    Browse the repository at this point in the history
  5. Invert the order of the pattern match for readability.

    Trying to make changes to this made my head hurt: the fundamental split
    is on the state, *not* on the tag. So flip it.
    chriskrycho committed Apr 26, 2024
    Configuration menu
    Copy the full SHA
    5f19f77 View commit details
    Browse the repository at this point in the history
  6. Configuration menu
    Copy the full SHA
    804a6ad View commit details
    Browse the repository at this point in the history
  7. Configuration menu
    Copy the full SHA
    215420a View commit details
    Browse the repository at this point in the history
  8. Correctly handle adjacent quotes and notes.

    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.
    chriskrycho committed Apr 26, 2024
    Configuration menu
    Copy the full SHA
    8c899a3 View commit details
    Browse the repository at this point in the history
  9. Remove aria-label from <section>s.

    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
    chriskrycho committed Apr 26, 2024
    Configuration menu
    Copy the full SHA
    2eabe4e View commit details
    Browse the repository at this point in the history

Commits on Apr 29, 2024

  1. Prepare to merge into TRPL repo

    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.
    chriskrycho committed Apr 29, 2024
    Configuration menu
    Copy the full SHA
    3032068 View commit details
    Browse the repository at this point in the history
  2. Convert to a workspace

    This will let us pull in, and work directly on, things like the
    `mdbook-trpl-notes` preprocessor.
    chriskrycho committed Apr 29, 2024
    Configuration menu
    Copy the full SHA
    f48b281 View commit details
    Browse the repository at this point in the history
  3. Configuration menu
    Copy the full SHA
    da9e96e View commit details
    Browse the repository at this point in the history
  4. Merge mdbook-trpl-note into the repository

    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.
    chriskrycho committed Apr 29, 2024
    Configuration menu
    Copy the full SHA
    456a8dc View commit details
    Browse the repository at this point in the history
  5. Configuration menu
    Copy the full SHA
    33fb62e View commit details
    Browse the repository at this point in the history
  6. Emit semantic HTML instead of blockquotes for notes

    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.)
    chriskrycho committed Apr 29, 2024
    Configuration menu
    Copy the full SHA
    da7a20f View commit details
    Browse the repository at this point in the history
  7. Do not apply semantic note handling to nostarch

    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.
    chriskrycho committed Apr 29, 2024
    Configuration menu
    Copy the full SHA
    593ec2a View commit details
    Browse the repository at this point in the history
  8. Update CI config for workspace and mdbook-trpl-note

    - Add building `mdbook-trpl-note` to the relevant workflow.
    - Explicitly exclude `linkcheck` from new workspace.
    chriskrycho committed Apr 29, 2024
    Configuration menu
    Copy the full SHA
    427f7d3 View commit details
    Browse the repository at this point in the history