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
altattribute 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
srcattribute, 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
altattribute of the image, which stands for “alternate text.”
For images generated from code chunks in R Markdown, the
altattribute 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
alttext in square brackets, e.g.,
![an informative text](path/to/image.png).
alttext 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_documentformat will render a visible figure caption element by default. If you do not want the real figure captions, you can turn off the
output: html_document: fig_caption: false
In this case, the
altattributes will still be generated, but are no longer visible.
Write mathematical content using the LaTeX syntax (e.g.,
$$ $$) 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.