alphagov / tech-docs-gem

Gem to distribute the tech docs project
https://tdt-documentation.london.cloudapps.digital/
MIT License
15 stars 38 forks source link

Add tabindex and focus states to code blocks #215

Closed richardTowers closed 3 years ago

richardTowers commented 3 years ago

This is required for accessibility reasons. Because some code blocks have scrollbars they need to be focusable using a keyboard.

I've copied the styles from the design system's documentation (see the code blocks in the HTML / Nunjucks tabs here: https://design-system.service.gov.uk/components/button/)

The implementation is simple when syntax highlighting is not enabled, because we can simply implement block_code to surround the code with the markup we want.

When syntax highlighting is enabled it's a bit more complicated. Middleman already includes its own implementation of block_code, which renders the source code highlighted with spans. This method doesn't look like it would be easy to customise, so instead I've resorted to post-processing the HTML (i.e. replacing the attributes on the <pre> tag using a regex).

Testing this was a bit tricky, because you need to monkey patch the class to include the block_code method. I had to clone the class and patch the clone to do avoid affecting other tests.

Example from a locally running version of the paas tech docs:

image


⚠️ Don't forget to update the gem version in the CHANGELOG before merging! When you're ready to release bump version file and generate a tag. ⚠️

richardTowers commented 3 years ago

Thanks! Addressed in a0c9bfddbc2749514a17c867ac3f3512a388542d