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:
control over linebreaking and indentation
elementary math notation support (2D math, long division, ...)
support for bidirectional languages (eg, Arabic languages)
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 3.2.5.2.2 and Section 3.2.5.2.3 of the MathML 3 recommendation.
Elementary math
MathML has long been useful for notations used in algebra and higher math, but describing the twodimensional 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 crossouts
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 languageindependent MathML, content MathML smoothes over these differences and presentation MathML allows these specific notations to be encoded.
In Arabic countries, mathematical notation is written righttoleft using the same alphabetic characters. MathML 3 now makes it possible to encode righttoleft notations in presentation MathML. MathML 3 adds a dir
attribute to control whether layout is lefttoright or righttoleft (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 righttoleft notation (note: numbers are still lefttoright 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
, andcbytes
Deprecated content elements:
reln
,fn
, anddeclare
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.
Linking
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
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 nonstandard 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 3.2.1.2 of the MathML 3 recommendation.
mpadded
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.
semantics/annotation/annotationxml
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 annotationxml
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.
Entities
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="http://www.w3.org/1998/Math/MathML"> … </math>
Another namespace issue arises with the use of annotationxml
inside of semantics
. Inside of MathML, all elements are placed in the MathML namespace with two exceptions: inside some annotationxml
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 annotationxml
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 nonHTML5 elements are placed in the MathML namespace even if they are declared to be in another namespace (eg, http://www.openmath.org/OpenMath ). 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.