Accessible R Markdown Documents

Introduction

At the end of a presentation I gave at the UseR conference in July 2016, I was asked what authors could do to make their R markdown documents more readable by the blind students I support. This page is my first attempt at meeting this request.

My initial suggestion is to provide the original source files as well as the final HTML documents you create. My reasons are two-fold.

If you do something wrong and there is something in the HTML that is not accessible (unlikely but possible) the source files can be referred to by your blind reader.
The blind reader can benefit from learning how to write in markdown so that they can create accessible documents for themselves. Your documents will be the examples your blind audience needs.

What is accessible?

I am blind and so are many students around the world. We need to have documents that our screen reading software can handle. HTML content can be made very accessible, while the majority of pdf files that contain graphics and mathematical content are not.

The increasing popularity of markdown in general, and the R implementation of it in particular, is a grand opportunity to create documents that can be read by blind people, and there is very little needed to make it work for us; so little in fact, that you’ll probably not really notice it after a while. We’ll be benefitting from your work so please do read on.

Making accessible documents

Markdown files will be pretty easy to read. There are some things you ought to be doing for all readers of your work, but following the ideas given in the following subsections will assist your blind readers a lot.

Some basics for markdown

This list is my own opinion. There are standards for web content and other accessible documents, but no standard exists for accessibility and markdown documents in particular. Many of the accessibility requirements for web content are automatically generated by standard markdown document practices, including:

Use proper heading styles. This is automatic in markdown when you use hash/number signs to create headings of the right “level”.
use of tables for tabulation, not for presentation (some people space out a page using tables inside tables inside tables which is quite impractical in markdown). Stick to using tables for information.
label all graphics with alt text tags. This is automatic in markdown when you insert a graphic, but please make the text informative rather than just a filename.
Use the standard LaTeX style method for inserting mathematical content. It is probably easier than doing anything else in markdown but if the choice is to retype a formula or pull it in as a graphic, then get busy typing please. See the Levene Test document in HTML, or the corresponding Levene Test source R markdown text.

Optional helping hints

I found the flow of some documents was unnecessarily clunky when simple mathematical elements were entered as math mode elements. Sentences will read better if x and y are in italicised font and not math mode, and the sighted readers won’t notice the difference. This won’t work for Greek, some subscripts and superscripts, or symbols. If in doubt, use math mode everywhere.

Some basics for R markdown

This is the recommended workflow and R markdown practices that lead to documents that work the best for blind students. It may change, but I am hopeful that this bare minimum of suggestions is all that is required for a long time to come.

Use rmarkdown::render() to convert your Rmd files to HTML. Yes, I know you can use knitr::knit2html() but there are additional things that the rmarkdown package does for you behind the scenes, such as the processing of mathematical content using mathjax. This page and all the examples have been created this way. Do not use knitr::pandoc() either. The results may “look” the same, but they do not sound the same when read by screen reading software. Screen reader users may look at the same content processed using pandoc without settings and then the benefits of
using the rmarkdown package.
Include a header block in your documents. A bare minimum would be:

---
title: "Accessible R Markdown Documents"
author: "A. Jonathan R. Godfrey"
output: html_document
---

This is used in all of the examples. Note that inclusion of this header is tailored to use of rmarkdown::render() as it inserts the title and author as headings for you; knitr::knit2html() throws an error message if you use this style of header.

Did you see the use of brackets after function names in the last point? Blind people won’t see that change in font that says something is a function name. The () is going to help us, and your sighted audience won’t mind so much.
Use fig.cap in the figure chunk headers. This inserts the alt text on those graphs. This will label the graphic and then insert a caption so screen readers will hear that text twice. See the multiple comparisons document in HTML, or the corresponding multiple comparisons source R markdown text.
Get rid of those hash/number signs on the R output by using comment="" for all chunks that generate output.
1. You could put that in the opening chunk of your documents. For example:
```
library(knitr)
opts_chunk$set(comment="")
```
See any of the examples.
1. If you want your audience to get numerous code chunks and re-run them in one go, then give them an R script of the commands by using knitr::purl() on your Rmd Files. (You could put that as the last chunk of the Rmd file itself!)
…

Notes for screen reader users

I’ve tested the outcome from the above suggestions using JAWS and NVDA screen readers. Both of these products have made significatn improvements over the last few years for handling mathematical content in particular. You may need to refresh the browser you use, and you may also need to pay attention to allowing blocked content.

You ought to test the performance of the screen readers you have on your system, and also try several browsers. In 2016, I was happy using JAWS 17 and Internet Explorer. When I get to a mathematical element the screen reader will separate it out from the surrounding text and tell me it is “math content”. This then lets me click on it (just like I would click on a link) to open up a new window specifically allowing me to explore the math content.

Future development

It is my hope that one day soon, the default graph files used by R markdown will shift from the png format to a scalable vector graphic. Once we make use of an SVG file with the correct augmentation, we ought to be able to explore the content of these files in a similar way to the math content exploration that is possible today.