Skip to main content

Section 6.26 Accessibility

Continuing our discussion from Section 3.25 we begin by listing features of our conversion to HTML which happen automatically.


Wherever possible we supply HTML elements and attributes that will be interpreted sensibly by a screen reader in the absence of the visual styling provided by CSS. This means we are cognizant of the role of headings (h1 through h6), provide HTML that passes validation checks, and so on. Employing attributes from the Accessible Rich Internet Applications suite of web standards (ARIA) at will go a long way to improving accessibility. This work is in-progress as of 2018-05-31.


MathJax ( is the JavaScript library we use to render mathematics within the HTML output. It provides extensive capabilities for screen readers to render the mathematics audibly, and by default your project's output is configured to take advantage of these features. We refer the reader to the MathJax documentation of Accessibility Features at for details. But here is a simple experiment you can do yourself right now to simulate how a blind reader could experience mathematics with the combination of PreTeXt, MathJax, and a screen reader.

  1. Find some moderately complicated mathematics, such as in the “Mathematics” section of the sample article, or your own project, or the sample from MathJax copied below.
  2. Bring up the context menu on that display (a mouse right-click for most).
  3. Turn on the Accessibility > Explorer > Activate menu item. The page will reload, and the Explorer menu item will earn many more menu items. This setting is reasonably sticky, so you should not have to do this repeatedly. Having this on will incur some processing time as part of each page load, so you may want to turn it off later.
  4. Turn on the Accessibility > Explorer > Subtitles menu item.
  5. TAB until some mathematics is given focus (a discrete border appears).
  6. SHIFT-SPACE will activate exploration of the mathematics with the Explorer. A subtitle, with an aural rendering of the mathematics, will appear below the display.
  7. You can navigate (explore) the expression tree with the up, down, left, and right arrow keys. The subtitles will change as you do this.

From the MathJax demonstration page, Maxwell's equations for practice:

\begin{align*} \nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} & = \frac{4\pi}{c}\vec{\mathbf{j}}\\ \nabla \cdot \vec{\mathbf{E}} & = 4 \pi \rho\\ \nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} & = \vec{\mathbf{0}}\\ \nabla \cdot \vec{\mathbf{B}} & = 0 \end{align*}
Skip to Main Content

Repeatedly pressing the Tab key will move a reader from one location to the next in a web document. Since your Table of Contents in the left sidebar is a series of many links, a reader will need to tab through all of these to eventually reach the interesting content on a page.

However, we support a common device. The first link on every page is hidden from all readers, but an initial Tab will present a link labeled Skip to Main Content which when executed will take the reader past the Table of Contents and to the start of the content at the top of the page.


We are sensitive to the fact that some readers have difficulty distinguishing between certain colors. So we do our best to distinguish text, or other elements, without relying exclusively on color. For example, the <delete> and <insert> elements may render text with strike-through and underlining (respectively) to show the distinction.

Here are features which are provided, but require your participation as the author.

Image Description

Images you author or supply will be invisible to some readers. Within every <image> element you can use a <description> element. The content here will migrate to places like the HTML @alt attribute to be picked up by screen readers.

Make the content very expressive and detailed, but not overly verbose. Also, do not use any markup whatsoever, just simple characters, and avoid quotation marks. You can learn more at sites such as the one provided by the Web Accessibility Initiative (WAI) at Text alternatives for non-text content.

We cannot do this one for you, this is for the author only. But we can give you the tools do it as easily and as correctly as possible.

Image Formats

University offices that provide services for students with disabilities are often interested in the images themselves from a text, as standalone files. For example, they might be able to manufacture tactile versions. You could use the mbx script to produce a variety of different formats and bundle these up in a single archive file for distribution at your book's website. Or you can make each image available through adjacent links placed automatically. We call these “image archives.” See Subsection 6.11.4.


Section 6.6 describes a variety of ways to customize the look and content of a cross-reference. You can create a larger target for clickable items by making the text as long as possible. So for example an <xref> authored as

<xref ref="theorem-FTC" text="type-global" />

would cause the clickable portion to be something like “Theorem 5.16”, whereas

<xref ref="theorem-FTC" text="global" />

would then cause the clickable portion to be simply the much shorter “5.16”. Of course, you can set a default style for your entire document, so it is not necessary to continually provide the @text attribute.

Watching a blind reader navigate a web page can be a very enlightening experience. Or you might even undertake learning one yourself. Here are some suggestions for getting started (current on 2018-05-31).