Describing HTML snippets

A number of MathJax configuration options allow you to specify an HTML snippet using a JavaScript object. This lets you include HTML in your configuration files even though they are not HTML files themselves. The format is fairly simple, but flexible enough to let you represent complicated HTML trees.

An HTML snippet is an array consisting of a series of elements that format the HTML tree. Those elements are one of two things: either a string, which represents text to be included in the snippet, or an array, which represents an HTML tag to be included. In the latter case, the array consists of three items: a string that is the tag name (e.g., “img”), an optional object that gives attributes for the tag (as described below), and an optional HTML snippet array that gives the contents of the tag.

When attributes are provided, they are given as name:value pairs, with the name giving the attribute name, and value giving its value. For example

[["img",{src:"/images/mypic.jpg"}]]

represents an HTML snippet that includes one element: an <img> tag with src set to /images/mypic.jpg. That is, this is equivalent to

<img src="/images/mypic.jpg">

Note that the snippet has two sets of square brackets. The outermost one is for the array that holds the snippet, and the innermost set is because the first (and only) element in the snippet is a tag, not text. Note that the code ["img",{src:"/images/mypic.jpg"}] is invalid as an HTML snippet. It would represent a snippet that starts with “img” as text in the snippet (not a tag), but the second item is neither a string nor an array, and so is illegal. This is a common mistake that should be avoided.

A more complex example is the following:

[
  "Please read the ",
  ["a",{href:"instructions.html"},["instructions"]],
  " carefully before proceeding"
]

which is equivalent to

please read the <a href="instructions.html">instructions</a> carefully
before proceeding.

A final example shows how to set style attributes on an object:

[["span",
  {
    id:"mySpan",
    style: {color:"red", "font-weight":"bold"}
  },
  [" This is bold text shown in red "]
]]

which is equivalent to

<span id="mySpan" style="color: red; font-weight: bold;">
This is bold text shown in red
</span>

Since HTML snippets contain text that is displayed to users, it may be important to localize those strings to be in the language selected by the user. See the Localization Strings documentation for details of how to accomplish that.