Skip to main content

MathML 3

Why MathML 3?

MathML 2 was first adopted in 2001. Experience with MathML has accumulated over the years and the web environment has changed somewhat since then. Released in 2010 and updated in 2014, MathML 3 includes several requested features and some changes to update the recommendation to the current and emerging standards. MathML 3 also contains lots of smaller changes to clarify the spec and unify attribute values so that compatibility between implementations is more likely. With the exception of a few very minor changes for features not widely implemented, MathML 3 is backward compatible with MathML 2.

The big changes are:

Some of the smaller changes are:

The big changes

Linebreaking and indentation

MathML 3 introduces several attributes for controlling line breaks and indentation after line breaks. The new controls can be used for both automatic line breaks when the renderer determines that there is not enough room to display an expression in a given width and for manual (forced) line breaks. In MathML 3, linebreaking and indentation are specified on operators (mo). The controls include:

  • whether a line break should or should not happen at an operator;

  • whether the break should be before or after the operator;

  • what character to use (if any) in place of an "⁢" character at a line break

  • the amount of vertical space to be used after the line break

MathML 3 offers a good deal of control over how to indent after a line break. This allows for many different styles of linebreaking and also makes it possible to align the new line with a previous point in the expression (e.g., at an "="). Alignment at a particular point is done by marking the element you want to align to with an id attribute and then telling MathML to indent to that id value.

The indenting controls include:

  • alignment -- left/center/right/automatic/id

  • shift amount -- amount to shift it from the aligned point

These options can be set for all of the lines or specifically for either the first or last line to override the indentation behavior for those lines. This flexibility accommodates many different styles of indenting.

For some examples, see Linebreaking of Expressions. For details, see Section and Section of the MathML 3 recommendation.

Elementary math

MathML has long been useful for notations used in algebra and higher math, but describing the two-dimensional layout used in elementary math required tedious layout using mtable, with each digit in its own column and clever tricks to get the lines to come out correctly. This was both difficult to do and the result was inaccessible. MathML 3 adds support for a wide variety of notations used in lower grade math for:

  • addition, subtraction, and multiplication (with carries/borrows)

  • long division

  • repeating digits in decimal numbers

Here are some examples:

subtraction with borrows

long division (US, etc., style)

repeating decimal




The support for these notations is very flexible in MathML 3 to handle the wide variety of notations that are used around the world. The flexibility allows for:

  • different positions for the operator in addition, subtraction, and multiplication problems

  • different positions for the carries

  • different styles of cross-outs

  • control over the length, position, and thickness of lines

  • different notations for long division

  • different notations for showing repeating decimals

For more examples, including a video showing how MathPlayer will speak these for accessibility, see our elementary math examples page. For complete details about the elements and attributes used for elementary math, see Section 3.6 of the MathML 3 recommendation.

Bidirectional layout support

Mathematical notation is mostly consistent around the world. However, there are some notations that differ depending upon the language/locale such as "." versus "," for a decimal separator and "tan" (English) versus "tg" (French) for the tangent function. For people who want to produce language-independent MathML, content MathML smoothes over these differences and presentation MathML allows these specific notations to be encoded.

In Arabic countries, mathematical notation is written right-to-left using the same alphabetic characters. MathML 3 now makes it possible to encode right-to-left notations in presentation MathML. MathML 3 adds a dir attribute to control whether layout is left-to-right or right-to-left (see Section 3.1.5 of the MathML 3 recommendation for details). MathML 3 also introduces some mathvariant values for handling different styles of Arabic characters (see Section 3.2.2).

Here are two examples of Arabic math that use right-to-left notation (note: numbers are still left-to-right in Arabic math notation):

Square root

Long division



Content MathML

The chapter on content MathML was completely rewritten for MathML 3. Content MathML is used when the semantics of the math are more important than the visual display (the presentation) of the math. In MathML 3, a subset of content MathML is defined with semantics specified by OpenMath. This subset of content MathML is called Strict Content MathML and each element in strict content MathML is associated with a specific OpenMath Content Dictionary entry. OpenMath Content Dictionaries are extensible and permit a more precise definition of the semantics of each element. The meaning of most content MathML elements remains basically unchanged, although a mapping for each element into strict content MathML is given.

In order to accomplish alignment with OpenMath, the following changes were made to the elements:

  • New content elements were added: bind, share, cerror, cs, and cbytes

  • Deprecated content elements: reln, fn, and declare

The little changes

New attributes for ‹math›

Additional attributes were added to the math element. Probably the biggest difference is that any attribute that can be specified for mstyle can now be specified for math. Other additions include the ability to set the width for linebreaking, control over the altimg size and alignment, and the ability to set the cdgroup (used for content MathML). See Section 2.2.1 of the MathML 3 recommendation for full details.


In MathML 2, linking was done via XLink. However, XLink did not catch on and HTML5 doesn't use it. In MathML 3, all elements accept an href attribute to allow for hypertext links. Note that what should happen for hypertext links depends on the environment in which the MathML resides. In MathPlayer, links cannot point to places inside of a MathML expression. See Section 2.1.6 and Section 6.4.3 of the MathML 3 recommendation for full details on linking and href.


mglyph was extended to support general image inclusion (sort of like a img element in HTML). In earlier versions of MathML, the idea was that mglyph was a way of including characters from a non-standard font. This was not used much and the old usage of specifying a font and index into that font is deprecated in MathML 3. mglyph now takes attributes to specify the source of the image, size, and alignment. For accessibility reasons, an alt attribute value is required. For complete details on mglyph, see Section of the MathML 3 recommendation.


mpadded is used to adjust the spacing around its children. The allowed attribute values have been extended and new attributes for positioning the children within the specified spacing have been added. See Section 3.3.6 of the MathML 3 recommendation for full details.


This element was previously grouped with content MathML, but properly spans both presentation and content MathML and should be implemented by any system that implements only content or only presentation MathML. It is now in Chapter 5, which discusses mixing content and presentation MathML. annotation and annotation-xml both take the content MathML attributes cd and name, and also take a src attribute to specify the location of an external source for semantic information.

Interactions with the host environment

MathML 3 adds a new Chapter 6 that discusses how MathML should interact with its host environment. There is an emphasis on MathML in web pages, but there is a discussion with embedding MathML in other environments. Among the topics covered are:

  • names and "flavors" to use for encodings on the clipboard and the format to use for data in those encodings

  • how MathML can be mixed with other markup, including embedding SVG in MathML

  • using CSS with MathML

New schema

In a step forward into today's web environment, the normative version of the grammar is now expressed in Relax NG, not as a DTD. A DTD and XSD version still exist and are derived from the Relax NG grammar.

New operator dictionary

The Operator Dictionary table has been greatly expanded (and cleaned up) to include lots of new characters and attributes. The format is new and includes the ability to sort on different columns.


Most of the information about entities has been moved from chapter 6 and is now its own recommendation:  XML Entity Definitions for Characters. That new recommendation includes changes made to Unicode characters along with a discussion of some problematic characters.

MathML and HTML5

HTML5 updated HTML4 to help meet the needs of modern web architecture. One of those updates brought math support into HTML5 via MathML. Most MathML will work just fine in HTML5, but here are a few things to watch out for:

HTML5 normally doesn't care about namespaces and puts all of the elements in the HTML namespace; MathML and SVG are the two exceptions to this rule. For compatibility with XTHML 1.x and XHTML5, the math tag should include the MathML namespace as shown below:

<math xmlns="">

Another namespace issue arises with the use of annotation-xml inside of semantics. Inside of MathML, all elements are placed in the MathML namespace with two exceptions: inside some annotation-xml elements and inside of mtext elements.

The first exception allows you to include an HTML alternative encoding inside of a semantics elements. The exception happens when the encoding attribute for annotation-xml is either "text/html" or "application/xhtml+xml". In these cases, the elements are placed inside the HTML namespace and can be manipulated by script or styled by CSS if made visible. For other encodings, the non-HTML5 elements are placed in the MathML namespace even if they are declared to be in another namespace (eg, ). If you use XHTML5 which is namespace aware, namespaces inside of MathML should be handled properly.

The second exception is inside of mtext. HTML5 extends MathML by allowing HTML5 elements inside of mtext. These elements are placed in the HTML namespace. It is not recommended that you make use of this extension because it is unlikely to work in other environments.

If HTML tags occur elsewhere inside of a MathML element (with the two exceptions above), the MathML element is terminated (closed off) by the HTML5 parser at that point. That is almost certainly not what most authors intend, so care should be taken when adding HTML5 in MathML.

Trying MathML 3

Other than MathPlayer, there are still very few complete implementations of MathML 3. Many other implementations, such as Firefox and MathJax have implemented some of MathML 3; we expect more and more of the features of MathML 3 will be implemented in those and other applications.

See also…