James Marszalek's OrganizationVisit Website →
← Back to blog

MathML in EPUB: Standards, Fallbacks, Examples for Authors, Alhora

October 7, 2026
MathML in EPUB: Standards, Fallbacks, Examples for Authors, Alhora

Use Presentation MathML for math in EPUB, and build in fallbacks from the start. This is the markup EPUB 3.3 supports natively in content documents, and it renders correctly across the widest range of reading systems. Set the mathml manifest property, add image fallbacks with descriptive alt text, and validate every file with epubcheck before you test it in your target reading systems.

Alhora
Prepare EPUBs With Greater Confidence
Alhora helps authors format books across operating systems, validate against publishing standards, and create professional-quality EPUB outputs.
Visit Alhora

Key Takeaways

Using Presentation MathML with proper fallbacks and validation ensures accessible, standards-compliant math content in EPUB 3.3 across reading systems.

PointDetails
Use Presentation MathML as standardEPUB 3.3 expects content documents to support Presentation MathML, which covers most mathematical needs.
Implement fallbacks for limited systemsPair MathML with images and descriptive alt text to maintain accessibility when native rendering is unavailable.
Validate markup thoroughlyRun epubcheck and manually test in various readers and screen readers to confirm correct rendering, fallbacks, and metadata.
Follow best practices for simple expressionsUse plain text with role='math' for trivial equations instead of full MathML markup, reducing complexity.
Align with Alhora’s approachWe utilize real-time validation and proper metadata management to produce accessible EPUBs with proper math handling.

Table of Contents

Which MathML EPUB supports and the spec constraints you must follow

Presentation MathML is the markup EPUB 3.3 expects inside content documents, and it covers the vast majority of math an author will ever need to typeset. Content MathML is allowed, but only in a narrow case: wrapped inside a semantics/annotation-xml element with an encoding attribute set to MathML-Content or application/mathml-content+xml, and a name attribute set to contentequiv. Skip that wrapper and a validator will flag the file.

A few rules keep your markup conformant:

  • Declare the MathML namespace on every <math> element: xmlns="http://www.w3.org/1998/Math/MathML".
  • Mark any manifest item containing MathML with the mathml property so reading systems and accessibility tools can detect it before rendering.
  • Avoid deprecated MathML attributes, which older authoring tools sometimes carry over from legacy exports.
  • Keep Content MathML out of general content documents unless it sits inside the required annotation-xml wrapper.

Authoring best practices for accessible MathML

Every math element starts with a valid wrapper: <math xmlns="http://www.w3.org/1998/Math/MathML">. From there, Presentation MathML is your default for anything beyond a trivial expression, because it preserves structure for screen readers and braille converters in a way that plain text cannot.

Not every equation needs full markup, though. For a simple inline expression like "x = 5," DAISY's guidance suggests plain text with a role="math" attribute instead, since MathML can disrupt reading flow when the math is trivial and the surrounding prose is the real content.

  • Use altimg and alttext attributes on <math> elements so reading systems without MathML rendering still show something meaningful.
  • Write extended descriptions for complex equations, especially multi-line derivations, following DAISY structure guidelines.
  • Mark invisible operators (⁢ for implicit multiplication, for instance) so assistive technology voices the expression correctly instead of skipping silently over it.
  • Keep markup semantically accurate: nest mfrac, msqrt, and msup the way the expression is actually structured, not just to approximate the visual layout.

Pro Tip: Write your alttext as you would say the equation aloud. Screen reader users and sighted readers should get the same information, just through different channels.

Fallbacks and progressive enhancement for limited reading systems

Not every reading system renders MathML, so plan for graceful degradation from the first draft rather than patching it in later.

  1. Pair each <math> element with an altimg pointing to a rendered image of the equation, and write alttext that describes the math in words a reader can follow without seeing it.
  2. When your workflow requires Content MathML, wrap it in semantics/annotation-xml with the encoding and name attributes EPUB 3.3 requires, never as a bare top-level element.
  3. Where the reading system supports feature detection, use epub:switch or light scripting to choose between a native MathML render and an image fallback.
  4. Document which equations use fallbacks in your accessibility metadata, and confirm the fallback itself, usually an image, carries proper alt text rather than a blank or generic label.

Testing and validation checklist for MathML in EPUB

Automated checks catch most problems before a human ever opens the file. Run epubcheck first, and confirm it reports the mathml property on every manifest item that contains math, with no deprecated attributes flagged.

From there, move to manual checks:

  • Open the EPUB in a modern browser-based reading system to confirm visual rendering matches your source markup.
  • Test in one or two older or less common readers to see how your fallbacks behave when native MathML support is partial or absent.
  • Verify with a screen reader that supports math voicing, and check braille translation output where that matters to your audience.
  • Keep a small, fixed set of sample equations, inline, block, and one genuinely complex expression, as a regression suite you rerun after any formatting change.

Including small, canonical test cases in your workflow catches most regression problems with MathML rendering across updates to reading-system engines, according to EPUB 3.3. A fixed suite means you are comparing against a known baseline instead of re-checking everything from scratch each time.

Copy-paste-ready MathML examples and common validation fixes

Here is a minimal inline example, the Pythagorean identity:

<math xmlns="http://www.w3.org/1998/Math/MathML"><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></math>

For a case this simple, consider plain text with role="math" instead, per DAISY's recommendation, if it reads more naturally in context.

A block-level fraction with a root and an image fallback container:

<math xmlns="http://www.w3.org/1998/Math/MathML" altimg="quad-formula.png" alttext="x equals negative b plus or minus the square root of b squared minus 4ac, all over 2a"><mfrac><mrow><mo>-</mo><mi>b</mi><mo>±</mo><msqrt><mrow><msup><mi>b</mi><mn>2</mn></msup><mo>-</mo><mn>4</mn><mi>a</mi><mi>c</mi></mrow></msqrt></mrow><mrow><mn>2</mn><mi>a</mi></mrow></mfrac></math>

Common epubcheck fixes:

ErrorLikely causeFix
Unknown attributeDeprecated MathML attribute carried over from exportRemove and use current spec attributes
Missing namespace<math> tag lacks xmlns declarationAdd the MathML namespace string
Invalid Content MathML placementContent MathML outside annotation-xmlWrap in semantics/annotation-xml with encoding and name
Unclosed elementManual edit broke tag pairingValidate XML structure before packaging

Before testing in a reading system, you can preview the raw HTML output in a browser-based markdown-to-PDF tool to catch obvious rendering issues without repackaging the EPUB each time.

Packaging and metadata to declare MathML and accessibility features

Set the mathml property on every manifest item that contains a <math> element. This is how stores, discovery systems, and accessibility tooling detect the content without scanning every XHTML file.

  • Add schema.org/accessibilityFeature: MathML to your package metadata so the feature is declared, not just present.
  • Include describedMath where you have written extended descriptions for complex expressions.
  • Add accessModeSufficient if the EPUB can be fully consumed through a single sense, such as reading the fallback text alone.
  • Write an accessibilitySummary that names any known limitations, such as equations that rely on image fallbacks rather than native MathML.

How Alhora maps to the MathML in EPUB workflow

Real-time validation against publishing standards means markup issues, including missing manifest flags, surface while you are still editing, not after export. Our accessible EPUB export checks packaging metadata and fallback structure before the file leaves your machine, which covers the preflight, export, and metadata management work this workflow calls for.

MathML EPUB validation workflow diagram

Editorial perspective: deciding how much MathML to author

Full MathML markup earns its production cost for formal STEM content and math-dense manuscripts. For a handful of inline equations, plain text with role="math" or a simple image fallback often serves readers just as well, at a fraction of the effort. Build your test cases and metadata early either way.

— James

Get your EPUB ready for accessible math

We built the software to catch exactly the kind of manifest and markup gaps that MathML introduces, before you ever hit export. Real-time validation flags missing properties as you work, and the typesetting engine carries equations, fallbacks, and metadata through to a clean, accessible EPUB.

Alhora

  • Validate manifest properties and markup structure while you format, not after.
  • Export accessible EPUB files with fallback and metadata handling already built in.
  • Work across multiple operating systems without switching tools mid-project.

Start with our ebook formatting software to see how a math-heavy manuscript moves from draft to a validated, store-ready EPUB.

FAQ

Does EPUB support MathML natively?

Yes. EPUB 3.3 designates Presentation MathML as the supported markup for math in content documents, and most modern reading systems render it directly without a plugin.

Can I use Content MathML in an EPUB file?

Only inside a semantics/annotation-xml wrapper with the encoding and name attributes the EPUB 3.3 spec requires. A bare Content MathML element at the top level will fail validation.

What fallback should I use when a reading system can't render MathML?

Pair your <math> element with an altimg image and descriptive alttext, as DAISY's structure guidelines recommend. That keeps the equation accessible even when native rendering fails.

Should every equation be marked up in full MathML?

Not necessarily. DAISY guidance suggests plain text with role="math" for simple inline expressions, reserving full MathML markup for equations where structure genuinely matters to a reader or assistive technology.

How do I check that my EPUB's MathML will pass validation?

Run epubcheck to confirm your manifest items carry the mathml property and that no deprecated attributes remain, then test rendering directly in your target reading systems and with a screen reader that supports math voicing.

Sources