A Guide To ‘accessrmd’.

A Guide To ‘accessrmd’.

Richard Leyshon

03 December 2021

Introduction

At A Glance

{accessrmd} is currently in development. If you discover bugs or improvements, please review the code of conduct and contribute on GitHub.

{accessrmd} is a package written to help improve the accessibility of Rmarkdown documents. The standard Rmarkdown outputs have HTML structural issues that result in problems for people using screen readers. The purpose of {accessrmd} is to help developers in writing accessible Rmarkdown documents and in converting a back catalogue of documents in need of accessibility amendments.

{accessrmd} is currently limited to html_output only. It is not available on CRAN yet, but this is the aim once the first release has been published.

To install the development version:

devtools::install_github("datasciencecampus/accessrmd")

To attach the package:

library(accessrmd)

What problem does it solve?

The HTML structure of standard rmarkdown outputs are not AA WCAG2.1 standard. AA is the standard required by all UK government digital services. In order to present HTML checks, I will be enlisting the help of the excellent, open-source WAVE accessibility tool. It doesn’t catch everything required for AA-compliance, but it’s a great way to get started with an accessibility audit, including helpful explanations for newcomers to WCAG 2.1 compliance.

The below image shows the output of a WAVE check on the standard Rmarkdown html output. As you can see, there are a number of errors and warnings. Click the image for more detail.

Accessibility check of a standard rmarkdown output showing errors & warnings. Click the image to view the full check on wave.webaim.org, opens in new window.

By executing a few functions from the {accessrmd} package, the html format issues can be easily remedied, without the developer needing to write any HTML. Please observe the output of an Rmarkdown which has been adjusted by {accessrmd} functions (again, you can click for an interactive check):

Accessibility check of an rmarkdown output modified by acessrmd, showing no errors or warnings. Click the image to view the full check on wave.webaim.org, opens in new window.


Testing Styles

Rmarkdown comes with some pre-packaged themes and highlight options.

Themes

Themes control the appearance of the document’s text and headers, applying specific fonts and colours. On testing the accessibility of these themes, the following accessibility issues were found:

  • cerulean: This theme presented very low contrast errors on the use of H4 or H5 headings.

  • simplex: This theme presented very low contrast errors on thhe use of standard or bold text.

The other built-in themes available were found to present no accessibility issues.

Highlights

All of the highlight options tested presented various accessibility errors apart from one. It is recommended to specify highlight: null. Note that this is not the default highlight option, which presented accessibility errors.

A summary of the accessibility errors found on testing:

  • Empty links used to apply code styling in chunks. Links contain no meaningful text.
  • Many of the highlights presented very low contrast errors.