Caution

A solution for MathML that works in all reading systems does not currently exist. The techniques presented on this page will continue to be updated as new information becomes available.

Refer to the Best Practices for Authoring MathML in EPUB guide for the latest information.

Summary

Support for rendering of native MathML markup is increasing but workarounds may still be necessary in some support scenarios.

Techniques

Examples

Example 1 — Block-level MathML equation
<math xmlns="http://www.w3.org/1998/Math/MathML">
   <mfrac>
      <msqrt>
         <mtext>a</mtext>
      </msqrt>
      <mi>b</mi>
   </mfrac>
</math>
Example 2 — Inline MathML equation
In the Pythagorean equation,
   <math xmlns="http://www.w3.org/1998/Math/MathML">
      <mrow>
         <msup>
            <mi>a</mi>
            <mn>2</mn>
         </msup>
         <mo>+</mo>
         <msup>
            <mi>b</mi>
            <mn>2</mn>
         </msup>
         <mo>=</mo>
         <msup>
            <mi>c</mi>
            <mn>2</mn>
         </msup>
      </mrow>
   </math>,
   the sum of the square of …
Example 3 — Inline text math equation
If <span role="math">2 + x = 9</span>,
   what is the value of <var>x</var>?

Demo:

If 2 + x = 9, what is the value if x?

Example 4 — Image with alternative text

Note that although an image might be the only output, if a publisher has source MathML markup, it can be kept together with the image in a (possibly hidden) div. Publishers could then choose which format to use in their published content (i.e., filtering out the less-supported alternative). It could also allow both forms to be published, with scripting used to determine which to render (note that a CSS fallback might also be needed for the hidden attribute if older user agents like IE11 have to be accounted for).


<div class="mathml-eq">
   <img src="squarerootab.jpg" alt="Square root of the result of a divided by b"/>
   <div hidden="hidden">
      <math xmlns="http://www.w3.org/1998/Math/MathML">
         <mfrac>
            <msqrt>
               <mtext>a</mtext>
            </msqrt>
            <mi>b</mi>
         </mfrac>
      </math>
   </div>
</div>

Alternatively, to avoid any processing or rendering impact, the MathML markup could be hidden in an HTML comment (<!-- -->). This may pose re-processing challenges later.


<img src="squarerootab.jpg" alt="Square root of the result of a divided by b"/>
<!-- <math xmlns="http://www.w3.org/1998/Math/MathML">
         <mfrac>
            <msqrt>
               <mtext>a</mtext>
            </msqrt>
            <mi>b</mi>
         </mfrac>
      </math> -->

Frequently Asked Questions

Should I prefix the MathML tags?

No, it is not recommended to use prefixes with math tags (e.g., m:math).

Not all combinations of assistive technologies and user agents are XML aware, so even if they support MathML markup they may not support prefixed markup.

The use of unprefixed tags is also recommended as it ensures compatibility between both HTML and XHTML syntaxes (XML prefixes are not supported in HTML).

Should I use the ARIA math role with MathML markup?

No, it is strongly advised not to use the math role with MathML markup. In many cases, using this role will cause the MathML markup not to be accessible to users.

The math role should be restricted to text math equations (refer to example 3).

How can I provide a description?

There currently isn't a recommended practice for descriptions due to poor support.

The alttext attribute is not intended for descriptions but to be used in place of the MathML when it is not supported. Reading systems support for this replacement is poor.

MathML 4 is introducing the intent attribute to improve the voicing of equations, but it is still only a draft.

It is possible to use the aria-label and aria-details attributes to provide a description, but more testing is necessary.

This guide will be revised when a proven technique emerges.

Explanation

Although a benefit of native MathML support in HTML is the ability to provide voicing based on the markup, user agents capable of such voicings are still not widespread. MathML still presents the most accessible option in user agents that do support it, however.

As MathML rendering support has now become widespread in browsers, the best option for providing accessible math equations is to use MathML markup.

Although MathML should be preferred for math content, simple inline text equations are often not tagged (e.g., "x + y = z"). Although such equations may appear simple, assistive technologies will often not read out all the symbols, making them difficult for users to understand. If MathML is not used for these types of equations, they should be wrapped inside an element with the role "math" (refer to example 3). The use of this role allows assistive technologies to switch pronunciation modes.

Note

Support for MathML in EPUB depends heavily on the age of the reading system. Reading systems that actively update their browser cores can now handle MathML, but publishers will still have to consider the rendering of their content in older reading systems for a while.

A less robust solution, but more likely to work in older reading systems, is to provide an image of the math with a sufficiently descriptive alternative text, and extended description for more complex equations (refer to example 4).

For the most up-to-date information on support in EPUB, refer to the Best Practices for Authoring MathML in EPUB guide.

Related Links