Improve the accesibility of rmarkdown created html-documents

I’m using rmarkdown to produce a number of reports for my employer (example: https://filer.skane.se/kommunrapporter/Kommunrapport_Kristianstad.html ). From September we need to improve the accessibility for visual impaired of all our web documents (following an EU regulation). There are many things that need to be changed, but I have identified two major issues. 1) It must be possible to move between headings and links with TAB.2) Figures need to be provided with an “ alt - text ”-attribute. Does anyone have a solution or is able to point me to the right direction?

I have tried to do some homework and have read https://forum.posit.co/t/adding-alt-text-to-figures-generated-in-r-markdown/65191 and https://r-resources.massey.ac.nz/rmarkdown/ but I probably need more help than they provide.

If anybody want to help me, I provide a simple test case below:

---
title: "Accessibility"
author: "C Lindell"
date: '2020-06-23'
output:
  html_document:
    toc: yes
    toc_float: yes
---


```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = FALSE, warning = FALSE, message = FALSE)
```

# Navigate with the TAB-key?

I want to navigate the toc with the TAB-key and go to the right part of the document by pressing RETURN. I also want to be able to tab between links and headings.


# Diagrams and pictures

How do I provide a generated diagram with a "alt text"-tag to make it readable for the vison impaired?

```{r}
library(ggplot2)

ggplot(cars, aes(speed, dist)) +
  geom_line()
```

When you enclose your Rmd file with four backticks instead of the standard three we will be able to see the unformatted Rmd file.
No answers yet: no R installation on my phone.

2 Likes

This SO may help. Citing @yihui:

The chunk option fig.cap will generate the alt text.

```{r myplot, fig.cap = "A caption...", echo = FALSE}
ggplot(cars, aes(speed, dist)) +
  geom_line()
```
1 Like

Thanks! But do you know if I can have different captions and alt-text-labels?

You may find RMarkdown for Scientists helpful (see there how you can use knitr::include_graphics()).

The markdown syntax to insert an image is: ![caption]("path/to/image")

So, the markdown syntax for images (ex.: .png, .jpg) on the web or local files in the same directory (here in figures subfolder):

![This image/figure/plot/diagramm represent...](figures/my_image.png)

wiil be turned in .html output:

<img src="...base64..." alt="This image/figure/plot/diagramm represent..." ... />
1 Like

In the markdown syntax described by @radovan it is also possible to add (alternative) alt-text :

![This image/figure/plot/diagramm represent...](figures/my_image.png "Alt text for this object")

I found this here.

2 Likes

Big thanks to HanOostdijk and radovan! Your solutions have really helped me, but I seems a bit to complicated to add an "alt-text"-label. Soon we have to adapt all documents from public organizations in the EU to make them readable to people with visual impairments. It would help if rmarkdown could distinguish between "caption" and "alt-text". The text in "alt-text" must explain the contents of the chart or image, while "caption" contains only the title. This could be a win or loose feature for rmarkdown in the public sector. I hope someone could add that feature to rmarkdown (I don't have the technical skills myself). And the html-documents produced by rmarkdown must be possible to navigate with the keyboard.

Thanks! RMarkdown for Scientists is a great resource! But the "alt"-tag and "caption"-tag will have the same text?

@ChristianL,
you already referred to https://forum.posit.co/t/adding-alt-text-to-figures-generated-in-r-markdown/65191. I am afraid that that is the way to go until the knitr package is changed: you would have to change the knit hook for the plot.
While that is not so difficult to do (the reference shows how in the case of a Hugo document) the problem lies more in handling correctly all the different cases.
Therefore I suggest you do a request in the knitr GitHub repository .

In SO mentioned earlier, see @yihui's comment:

Is there a way to generate the alt text without fig.cap option? (i.e. for images that aren't captioned?)
Yes, fig_caption: false for html_document: 3.1 HTML document | R Markdown: The Definitive Guide

So, if we include fig_caption: false into YAML:

---
title: "Accessibility"
author: "C Lindell"
date: '2020-06-23'
output:
  html_document:
    toc: yes
    toc_float: yes
  fig_caption: false
---

![This image/figure/plot/diagramm represent...](figures/my_image.png "Figure 1: Title")

we get .html output (with both, title= & alt=, under the hood):

<img src="...base64..." title="Figure 1: Title" alt="This image/figure/plot/diagramm represent…"" ... />

but without showing caption/title on the surface.

With fig_caption: true we get following .html output:

<img src="...base64..." title="Figure 1: Title" alt="">
<p class="caption">This image/figure/plot/diagramm represent…</p>

having the caption showed on the surface, without alt text under the hood.
It seems that there is no perfect solution (with knitr), as pointed by @HanOostdijk.

2 Likes

@ChristianL,

this is an example of a knitr plot hook that supports only the arguments caption and alt.
All other arguments you would like to use you should include yourself.
For my convenience I also used nocaption and noalt but because these are not recognized they have the same meaning as not specifying caption resp. alt .

---
author: "C Lindell"
title: "my title"
date: '2020-06-24'
output:
  html_document:
    toc: yes
    toc_float: yes
    keep_md: yes
---


```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = FALSE, warning = FALSE, message = FALSE)

knitr::knit_hooks$set(plot = function(x,options) {
      base = knitr::opts_knit$get('base.url')
      if (is.null(base)) base = ''
      alt = ifelse (is.null(options$alt),"",options$alt)
      cap = ifelse (is.null(options$caption),"",options$caption)
      if (alt != ""){
        sprintf('![%s](%s%s "%s")', cap, base, x, alt)
      } else {
        sprintf('![%s](%s%s)', cap, base, x)  
        }
  })

```

# Diagrams and pictures

How do I provide a generated diagram with a "alt text"-tag to make it readable for the vision impaired?

```{r}
library(ggplot2)
```
### plot with caption and alt_text
```{r plot1,caption='nice plot',alt='my alt_text'}
ggplot(cars, aes(speed, dist)) +
  geom_line()
```

### plot without caption and with alt_text
```{r plot2,nocaption='nice plot',alt='my alt_text'}
ggplot(cars, aes(speed, dist)) +
  geom_line()
```

### plot with caption and without alt_text
```{r plot3,caption='nice plot',noalt='my alt_text'}
ggplot(cars, aes(speed, dist)) +
  geom_line()
```
5 Likes

Thanks! Great work! I didn't realise that I could use knitr hooks to define my own attributes. I have to dig deeper into that.

1 Like

This topic was automatically closed 7 days after the last reply. New replies are no longer allowed.

The last issue you mentioned was probably a bug of Pandoc. If you use knitr::include_graphics() to include the image, the alt attribute shouldn't be empty.

```{r, fig.cap="alt text"}
knitr::include_graphics('figures/my_image.png')
```

This should work regardless of fig_caption: true or false.

2 Likes