Improve code block sections for screen readers

[janosdebugs]

Currently, the code blocks are not marked up to make them easy to navigate for screen readers. This causes them to be read in line with the rest of the text.

There are several solutions to make them stand out. The easiest is to wrap them in a <figure></figure>. More advanced options could be adding a role attribute to the block. A <figcaption></figcaption> can also be used to enhance the experience alongside the appropriate CSS rules:

<figure aria-roledescription="Code block">
    <!- This needs automation to inject the language: -->
    <figcaption class="sr-only">Language: hcl</figcaption>
    <pre>...</pre>
</figure>

[SypherSP]

Hi @janosdebugs, i would like to have a go at this issue.

Could you please help me out with the relevant part of the code that is responsible for rendering the .mdx files?

[janosdebugs]

Hey @SypherSP sorry I missed this, I've assigned you. Regarding the specific implementation, in order to make the code more accessible, we should do the following (in order, happy to have separate PRs for these):

1. Make sure that the code block has a tabindex="0" defined so that the screen reader can focus on it with keyboard navigation.
2. The code could be wrapped in a figure to provide additional context using the figcaption. The screen reader-only functions should have a CSS markup to make it visible to screen readers and Braille users, but not to "normal" browsers.

To test this feature you can:

1. Use the free NVDA software.
2. Use the Android Talkback or iOS Voiceover feature.

All 3 of these require some getting used to, please familiarize yourself with them so you can test this properly. Specifically, please look at the browse vs. focus mode when using NVDA, these can be a bit confusing at first.

[SypherSP]

<!- This needs automation to inject the language: -->

Could you explain what you mean by this.

What do you think about implementing a new component like

const FigureWithCaption: React.FC<FigureWithCaptionProps> = ({ children, caption }) => {
  return (
    <figure aria-roledescription="Code block">
    <figcaption className="sr-only" tabIndex={0}>Caption: {caption}</figcaption>
    {children}
</figure>
  );
};

which can be used in any mdx file like this

<FigureWithCaption caption="Sample code">
``hcl
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 1.0.4"
    }
  }
}
``
</FigureWithCaption>

[Yantrio]

I personally would rather have the mdx be agnostic of what is rendering it where possible.

[SypherSP]

Okay, ill look for another approach

[janosdebugs]

@Yantrio it may not be possible, we may have to create a subclass(?) of <CodeBlock> to improve this, but I agree that upstreaming the fixes would be preferable.

[SypherSP]

Using Swizzling we can add the figure wrapper easily, but to add a caption from markdown might be a little complicated.

[janosdebugs]

Let's try the figure wrapper first so we get a tabindex (if not present already). @SypherSP please test the changes with a screen reader before adding them, the code I posted is from another project and it may not work as well for this website.

[SypherSP]

Yeah, im testing things as im adding them. Will link a pr as soon as i figure out wrapping.

[codiini]

@janosdebugs I think this can be closed since the corresponding PR has been merged

[janosdebugs]

Thanks @codiini !