Tips

Remember to add alt text for all images!

![Caption](image.png "alt text")

HTML accessibility checks

Math is much more accessible in HTML than PDF

Otherwise, writing equations in MathJax is similar to \(\LaTeX\).

Inline: $\sum_{i=0}^n i^2 = \frac{(n^2+n)(2n+1)}{6}$

Inline: \(\sum_{i=0}^n i^2 = \frac{(n^2+n)(2n+1)}{6}\)

Display mode allows equation labels (see @eq-1a):
$$
\sum_{i=0}^n i^2 = \frac{(n^2+n)(2n+1)}{6}
$$ {#eq-1a}

Display mode allows equation labels (see Equation 1): \[\sum_{i=0}^n i^2 = \frac{(n^2+n)(2n+1)}{6} \tag{1}\]

Note

You don’t need \tag{} or \label{} if you have equation labels like {#eq-1a} above.

MathML+MathJax accessibility

MathML (Mathematical Markup Language) is the markup language for presenting math in an accessible manner inside digital content.

  • MathML is the preferred format for publishing accessible math in webpages, ebooks, PDFs, and online applications
  • It is recommended by W3C and codified as an ISO standard
  • MathML makes content readable by assistive technologies such as screen readers, and convertible into speech, Braille, and other formats

MathJax is set of open-source JavaScript libraries that enable MathML content in browsers and additional accessibility features from the American Mathematical Society (AMS) and the Society for Industrial and Applied Mathematics (SIAM).

PDF and Docx

Because all documents on this course website are HTML and the optional PDF and DOCX files are just copies of the HTML automatically rendered with pandoc, the accessibility of PDF and DOCX files is not a big concern (presumably, most people will use the HTML format). Indeed, you may not want to include PDF and DOCX documents at all because they take time to render and add little value.

My students report that they really appreciate materials in HTML because they are accessibility on mobile devices (especially with links for easy navigation).

However, we may need PDF- or DOCX-formatted documents in some cases. If those cases require accessibility, then you are probably better off using a DOCX version, created with pandoc by adding docx: default below format: in the document header, unless your document includes math or complex tables, which may not render as well in Word.

\(\LaTeX\)

Accessible PDFs require tagging. For LaTeX, this means adding \DocumentMetadata{tagging=on} before \documentclass and requires installing some packages.1

Normally, when rendering qmd to PDF via LaTeX, we can add lines to the LaTeX preamble with include-in-header: in the YAML header. But adding lines before \documentclass causes an error:

 pdf: 
   include-in-header: 
     - text: |
        \DocumentMetadata{tagging=on} # DOES NOT WORK!  
        \documentclass{article}

Thus, I believe a LaTeX template is required to allow tagging when rendering qmd documents as PDFs via LaTeX.

General tips for LaTeX-generated PDFs

General tips for Quarto-generated PDFs

More accessibility discussions

revealjs HTML slides

Fixes

assets/accessiblity-fixes.js is JavaScript that fixes the following issues with web pages and HTML slides:

Scrollboxes

Issue:

Serious: Ensure elements that have scrollable content are accessible by keyboard. A scrollable region must have keyboard access.

To make scrollboxes accessible, I added a JavaScript patch that makes the scrollable region focusable via keyboard (Tab), allowing keyboard users to read and scroll using arrows:

// Add tabindex=0 to scrollable <pre> elements
  document.querySelectorAll('pre').forEach(function(pre) {
    if (pre.scrollWidth > pre.clientWidth) {
      pre.setAttribute('tabindex', '0');
      pre.setAttribute('aria-label', 'Code sample');
    }
  });

Collapsable callout chunks

Issue:

Critical: Ensure an element’s role supports its ARIA attributes

.collapsed

To make callout chunks accessible, I added a JavaScript patch to label them as buttons:

  document.querySelectorAll('.callout-header.collapsed').forEach(function(header) {
  if (!header.hasAttribute('role')) {
    header.setAttribute('role', 'button');
    header.setAttribute('tabindex', '0');
  }});

Website navigation buttons

Issue:

Critical: Ensure an element’s role supports its ARIA attributes

.navbar

This seems to be related to how the navigation bar is constructed (by Quarto defaults, I did not modify this):

The HTML originally included:

aria-controls="navbarCollapse" role="menu" aria-expanded="false" aria-label="Toggle navigation"

GPT’s response:

The role=“menu” is usually reserved for a list of menu items (think dropdown menus for accessibility, not a toggle button). You’re probably applying role=“menu” to the navbar toggle button, which is incorrect per ARIA standards. ARIA attribute permissions:

aria-expanded makes sense for interactive elements like a button, a link, or something toggling visibility. aria-label=“Toggle navigation” is fine for such a toggle. role=“menu” is not appropriate for a toggle button—it is used for containers of menu items, not the toggle itself. Common toggle buttons should have role=“button”, not role=“menu”.

Accessibility checkers will flag this combo because: aria-expanded, aria-label, and aria-controls are meant for elements like buttons. role=“menu” does not support these attributes (see W3C ARIA roles reference).

This issue seems to have been fixed by the same fix as the next.

“div” vs. “main”

Issue:

Moderate: Ensure all page content is contained by landmarks

From GPT:

Quarto’s default template uses <div id="quarto-content"> instead of <main id="quarto-content">. Your accessibility checker wants your main content inside a <main> — the most robust, semantically correct landmark.

How to Fix It: Override the HTML Template by creating a custom HTML template for your Quarto site. You can replace the <div> with <main>.

Fix:

This issue seems to have been fixed by adding <script> to assets/accessibility-fixes.js.