Seven accessibility tips for Quarto and R Markdown -users R-Bloggers

Introduction

When teaching, for my practical/tutorials and for about half of my lectures I notice that I am preparing them with r -markdown and Lately quarto. I enjoy preparing the material in R Markdown and Quarto because it gives me a reproducible way to regenerate my material every year and I can follow changes in the RMD/QMD files very precisely with GIT.

The subject of accessibility has recently become more prominent within universities. In the UK and in many other countries we are required to produce accessible accessible learning materials that do not approach students with a disability.

My university uses Blackboard for its online learning environment (OLE)/Learning Management System (LMS). There are other Oles, for example Moodle, Canvas, etc. They all work in the same way in the same way because they offer a website per unit/module/course within a secured online system.

Every document that I upload to Blackboard receives an accessibility score (out of 100%) and every module I learn receives a general accessibility score. My university uses Ally Accessibility Report LTI 1.3 to generate these scores. My university has no rule about what an acceptable score is for a document or a course.

It appears that accessibility is sometimes abbreviated to A11Y, which, like K8S (for Kubernetes), is a numeronym, where the 11 stands for the 11 letters between the beginning A and the end y by accessibility.

I should say that there are many guides for accessibility for HTML documents online, and indeed for R and R -Markdown there are at least two packages on Cran,
Accessrmd And
AccessrousTackling accessibility problems. I have also not covered any topics, such as choosing an accessible color palette in, for example GGPLOT2.

What follows is a set of tips that help improve accessibility score for individual documents and therefore your general accessibility score module.

Tip 1: Replace all PDFs with DOCX, PPTX or HTML-Documents

For a PDF to achieve a high accessibility score, it must be a special type of PDF that is called a ‘tagged PDF’, otherwise it will get a very low score (about 6%).

As I will show in the following tips, it is much easier to make Word, PowerPoint and HTML documents accessible. If you are looking for the most effective boost for your accessibility scores, you can easily remove all PDF documents from your site and replace them with Word, PowerPoint or HTML documents.

Tip 2: Add alt text to all figures

I think that, like many R users I remember about accessibility, there was something that is called alt text and it is best practice for HTML documents to give alt texts of each image they contain. Subsequently, screen readers have a description of the image for visually handicapped readers.

It appears that other types of document can also contain alt text for images; Including Word, PowerPoint and PDF documents.

Let’s say we have a quarto (or r markdown) document that we display DOCX and HTML exports. To add alt text to figures in the HTML -Document fig-alt Brok option (fig.alt In R Markdown). However, it appears that alt text for a Word document has been taken from the fig-cap Brok option (fig.cap In R Markdown). That’s why I specify both fig-alt And fig-cap Chunk options in all code -chunks -generating figures.

```{r}
#| fig-cap: Kaplan-Meier survival curve.
#| fig-alt: Plot of a Kaplan-Meier survival curve.
# code to generate plot
```

Tip 3: (The surprising headache that is) make tagged PDFs 😬🤯

It is possible for a PDF to achieve a perfect accessibility score; But as I said above, it must be a tagged PDF.

You can check whether a PDF tags has by opening them in Adobe Acrobat Reader and then bringing the Document Properties window forward. The information is at the bottom left of the Description Tab (on Windows I thought that SumatrapDF also reported that information reported, but on macOS I thought I could not see this reported in the preview app).

It appears that we can make tagged PDFs in a few ways;

The surprise here is that PDF documents produced by Latex and Typs standard do not (still) generate tagged PDFs. Therefore do not adjust pdf/typst Output formats in quarto nor pdf_document In r -markdown (neither pdf_document2 In Bookdown).

Generate tagged PDFs in latex

It turns it out
is possible to generate a tagged PDF from latexBut this is extremely awkward from R -Markdown and Quarto. First use quarto/r Markdown to generate the Tex file of your document, eg.
Quarto specify one of them

format:
  pdf:
    keep-tex: true

Or the latex export format.

format:
  latex

You need then
The following latex packages.

tinytex::tlmgr_install(c('latex-lab', 'pdfmanagement-testphase', 'tagpdf', 'luamml'))

You must then change the top of your TEX file to a \DocumentMetadata{tagging=on} Submission. And possibly the Unicode-Math Package is useful. The start of your Tex file looks like the following.

\DocumentMetadata{tagging=on}
\documentclass{article}
\usepackage{unicode-math}
\begin{document}
% the rest of your document ...
\end{document}

When I tried this, I discovered that compiling with Luualatex generated a tagged PDF.

lualatex mydocument.tex

But I can’t face this hassle for every document I produce. So the somewhat unexpected message home here is here that if you want to give your students a PDF document, the most useful way to produce a tagged PDF, make your quarto document to DOCX or HTML and then performs the PDF from Word of Chrome or Ally the conversion for you.

Tip 4: Improve accessibility

I think that tables generated using the Markdown syntaxis generate warnings in Ally Accessibility Checker 1.3. It reports that it cannot find the header row. However, I think tables are generated using the GT Package and other table packages usually pass. So I avoid making tables with Markdown Syntax.

Tip 5: Different accessibility controls can report different results

Microsoft has built an accessibility control in many of his office package. You can open this in Word and PowerPoint of the Judgement Tab then Check accessibility.

In comparison with Ally Accessibility Checker 1.13, I find these checks for more conditions. For the items they both check, I think they usually agree. But sometimes they do not agree, for example, the Microsoft Checker reported that the DIA numbers in a PowerPoint -Deck were OK, while Ally Accessibility Checker 1.13 reported that they had not achieved his color contrast control (although they were black text on a white slide).

Tip 6: Improvement of the accessibility of adapted text document templates

If you have one
Custom Template Word -Document For your DOCX output, it must be based on the underlying Pandoc DOCX template. You can get that by running

pandoc --print-default-data-file reference.docx > reference.docx

You can then make the layout of the different styles in the word in the Styles windowAnd even if you are in the UK/EU, you can change the layout size of the American stationery to A4.

Then perform the Microsoft Accessibilty Checker on this document (Judgement Tab | Check accessibility) and Word gives the option to upgrade the format of the document so that it can be executed, so click on the Transfer button when asked.

If you have then added an image to the document head, you can add alt text. Then reserve the document. Then specify the use of the reference document in your Quarto Yaml header.

format:
  docx:
    reference-doc: reference.docx

Tip 7: Quarto/Complex HTML -Upload documents to Blackboard Ultra

My university has upgraded to the latest version of Blackboard. Prior to this upgrade I had no problems uploading any type of document. But if I now try to upload HTML documents with embedded sources generated by Quarto, the upload animation is hanging (the 3 squares on the right side of the screenshot below, simply animate) and the file is not uploaded.

It appears that this is because Blackboard scans every document that we upload, what it calls its content remediation control. For some reason, Quarto HTML documents, including Revealjs HTML cover, are now too complex and fail this check. Annoying that Blackboard does not broadcast error message to tell us this. However, there is a solution.

• First place your HTML file in a ZIP archive
• Then go from your modulesite to Content collection When adding an item
  
• Then select Upload | Upload zip package (Choosing another option will fail)
  
• Make sure you select the button to overwrite an existing file with the same name
• And click Submit And that’s it.

This is the only way I can find to bypass the content of remediation control. Note if you try to upload the ZIP archive of your Content collection Did not visit from the course site – according to the screenshot below (don’t go here!) – the upload will also fail (confusing I know!).

Summary

I hopefully described 7 useful tips on improving accessibility scores for documents produced from quarto and r -markdown. With the help of these tips I increased the accessibility score for my 67% module for last year’s site to 98% for this year’s site.

I hope you have similar success.

Related