7.14 Improve accessibility of HTML pages

It is important to make your HTML output documents accessible to readers who are visually impaired or blind. These readers often have to use special tools, such as screen readers, to hear instead of visually reading your documents. Usually, screen readers can only read out text, but not (raster) images. This means you need to provide enough text hints to screen readers. The good news is that with some small efforts, you can actually greatly enhance the accessibility of your documents. Jonathan Godfrey has provided some tips in the article at https://r-resources.massey.ac.nz/rmarkdown/ on making accessible R Markdown documents.13 Based on this article, we highlight some tips below for the convenience of the readers of this book:

  • HTML documents are often more accessible than PDF.

  • Try to provide the Rmd source document along with the HTML output document if possible (e.g., Section 7.7 demonstrates one way to do this). In case anything in the HTML document is not accessible, the blind reader may be able to figure it out from the Rmd source, or fix it in the source.

  • Provide informative text tags to your graphics. At the useR! conference in 2014, Jonathan explained this issue to me in person. It was the first time that I had learned about the importance of the alt attribute of images on web pages.

    To understand this problem, first you have to know that images on web pages are generated by the HTML tag <img />. This tag has an src attribute, which points to the source of the image, e.g., <img src="foo_figures/image.png" />. Sighted readers can see the image, but it is hard for blind users to know anything about the image, because usually screen readers cannot read it, especially when it is a raster image (vector graphics can be better, such as SVG). In this case, it is helpful to provide a text hint, which screen readers can read out to the blind reader. This text hint can be provided in the alt attribute of the image, which stands for “alternate text.”

    For images generated from code chunks in R Markdown, the alt attribute will be generated if you provide the chunk option fig.cap (i.e., figure caption). Alternatively, you can insert an image using the Markdown syntax ![](). You input the image path in parentheses, and the alt text in square brackets, e.g., ![an informative text](path/to/image.png).

    The alt text is not displayed to sighted readers on an HTML page. However, when you provide the figure caption or alternate text to an image, the rmarkdown::html_document format will render a visible figure caption element by default. If you do not want the real figure captions, you can turn off the fig_caption option, e.g.,

    output:
  html_document:
    fig_caption: false

    In this case, the alt attributes will still be generated, but are no longer visible.

  • Write mathematical content using the LaTeX syntax (e.g., $ $ or $$ $$) instead of images. By default, R Markdown uses the MathJax library to render math content, and the result is readable to screen readers.

  • Get rid of the leading hashes (##) in the text output of code chunks by setting the chunk option comment = "" (see Section 11.12).

We are not experts on accessibility, so we recommend that you read the original article to learn more details.

  1. JooYoung Seo has also published a post about a few R packages to help visually impaired users at https://jooyoungseo.com/post/ds4blind/. It is not directly related to R Markdown, but it can be helpful for you to learn how blind users read graphs.↩︎