Accessibility Extensions Options

MathJax contains several extensions meant to support those who need assistive technology, such as screen readers. See the Accessibility Components page for more details. The options that control these extensions are listed below.

Semantic-Enrich Extension Options
Complexity Extension Options
Explorer Extension Options
Assisitve-MML Extension Options

Because the accessibility extensions are controlled by the settings of the MathJax contextual menu, you may use the Contextual Menu Options to control whether they are enabled or not. There are settings below that can be used to disable the extensions, in case they are loaded automatically, but these are not the settings that control whether the extensions themselves are loaded. That is controlled by the menu settings:

MathJax = {
  options: {
    menuOptions: {
      settings: {
        assistiveMml: true,   // true to enable assitive MathML
        collapsible: false,   // true to enable collapsible math
        explorer: false      // true to enable the expression explorer
      }
    }
  }
};

Note that there is no control for the semantic enrichment per se, but it is enabled automatically by enabling the collapsible math or the expression explorer.

Although you can load the extensions explicitly using the Loader Options, it is probably better to use the men u options above, so that if a user turns the extensions off, they will not incur the network and startup costs of loading the extensions they will not be using.

Semantic-Enrich Extension Options

This extension coordinates the creation and embedding of semantic information generated by the enrichment process within the MathJax output for use by the other extensions.

The semantic-enrich extension adds two actions to the document’s default renderActions object: an enrich action to perform the semantic enrichment, and an attachSpeech action to attach speech (if it is being generated) to the output.

The Configuration Block

MathJax = {
  options: {
    enableEnrichment: true,   // false to disable enrichment
    sre: {
      speech: 'none',         // or 'shallow', or 'deep'
      domain: 'mathspeak',    // speech rules domain
      style: 'default',       // speech rules style
      locale: 'en'            // the language to use (en, fr, es, de, it)
    },
    enrichError: (doc, math, err) => doc.enrichError(doc, math, err),  // function to call if enrichment fails
  }
};

Option Descriptions

enableEnrichment: true: This setting controls whether semantic enrichment is applied to the internal MathML representation of the mathematics in the page. This is controlled automatically by the settings of the context menu, so you should not need to adjust it yourself. You can, however, use it to disable semantic enrichment if the semantic-enrich component has been loaded automatically and you don’t need that.

sre: {...}: This block sets configuration values for the Speech-Rule Engine (SRE) that underlies MathJax’s semantic enrichment features. See the SRE documentation for more details.

enrichError: (doc, math, err) => doc.enrichError(doc, math, err): This setting provides a function that gets called when the semantic enrichment process fails for some reason. The default is to call the MathDocument’s enrichError() method, which simply prints a warning message in the browser console window. The original (unenriched) MathML will be used for the output of the expression. You can override the default tbehavior by providing a function that does whatever you want, such as recording the error, or replacing the original MathML with alterntiave MathML containing an error message.

Note

As of version 3.1.3, the enrichSpeech option has been renamed as speech in the sre block of the configuration.

Complexity Extension Options

This extension generates a complexity metric and inserts elements that allow the expressions to be collapsed by the user by clicking on the expression based on that metric. Use the 'a11y/complexity' block of your MathJax configuration to configure the extension.

The complexity extension adds a complexity action to the document’s default renderActions object.

The Configuration Block

MathJax = {
  options: {
    enableComplexity: true,       // set to false to disable complexity computations
    makeCollapsible: true         // insert mactions to allow collapsing
  }
};

Option Descriptions

enableComplexity: true: This setting controls whether the complexity extension is to run or not. The value is controlled automatically by the settings of the context menu, so you should not need to adjust it yourself. You can, however, use it to disable it if the complexity component has been loaded automatically and you don’t need it.

makeCollapsible: true: This setting determines whether the extension will insert <maction> elements to allow complex expressions to be “collapsed” so that they take up less space, and produce condensed speech strings that are simpler to listen to. When false, the expression is not altered, but elements are marked (internally) if they would be collapsible.

Developer Options

identifyCollapsible: true: This setting determines whether the complexity numbers computed for each element in the expression should take collapsing into account. If true, parents of collapsible elements will get complexities that reflect the collapsible elements being collapsed. When false, the complexities assume no collapsing will take place.

Collapse: Collapse: The Collapse object class to use for creating the <maction> elements needed for collapsing complex expressions. This allows you to create a subclass of Collapse and pass that to the document.

ComplexityVisitor: ComplexityVisitor: The ComplexityVisitor object class to use for managing the computations of complexity values. This allows you to create a subclass of ComplexityVisitor and pass that to the document.

Explorer Extension Options

This extension provides support for interactive exploration of expressions within the page. See the Accessibility Features page for details about how this works.

The explorer extension adds an explorable action to the document’s default renderActions object.

The Configuration Block

MathJax = {
  options: {
    enableExplorer: true,                // set to false to disable the explorer
    a11y: {
      speech: true,                      // switch on speech output
      braille: true,                     // switch on Braille output
      subtitles: true,                   // show speech as a subtitle
      viewBraille: false,                // display Braille output as subtitles

      backgroundColor: 'Blue',           // color for background of selected sub-expression
      backgroundOpacity: .2,             // opacity for background of selected sub-expression
      foregroundColor: 'Black',          // color to use for text of selected sub-expression
      foregroundOpacity: 1,              // opacity for text of selected sub-expression

      highlight: 'None',                 // type of highlighting for collapsible sub-expressions
      flame: false,                      // color collapsible sub-expressions
      hover: false,                      // show collapsible sub-expression on mouse hovering

      treeColoring: false,               // tree color expression

      magnification: 'None',             // type of magnification
      magnify: '400%',                   // percentage of magnification of zoomed expressions
      keyMagnifier: false,               // switch on magnification via key exploration
      mouseMagnifier: false,             // switch on magnification via mouse hovering
      align: 'top',                      // placement of magnified expression

      infoType: false,                   // show semantic type on mouse hovering
      infoRole: false,                   // show semantic role on mouse hovering
      infoPrefix: false,                 // show speech prefixes on mouse hovering
    }
  }
};

Option Descriptions

enableExplorer: true: This setting controls whether the explorer extension is to run or not. The value is controlled automatically by the settings of the context menu, so you should not need to adjust it yourself. You can, however, use it to disable it if the explorer component has been loaded automatically and you don’t need it.

The a11y options belong roughly to one of the following four categories:

Speech Options

speech: true: Sets if speech output is produced. By default speech is computed for every expression on the page and output once the explorer is started.

braille: true: Sets whether or not Braille is produced and output for an expression.

subtitles: true: This option indicates whether the speech string for the selected sub-expression will be shown as a subtitle under the expression as it is explored.

viewBraille: false: This option indicates whether Braille output will be displayed under the expression as it is explored.

Note

As of version 3.1.3, the speechRules option has been broken into two separate options, domain and style, in the sre block of the configuration. See the Semantic-Enrich Extension Options above for more.

Highlighting Options

foregroundColor: 'Black': This specifies the color to use for the text of the selected sub-expression during expression exploration. The color should be chosen from among the following: 'Blue', 'Red', 'Green', 'Yellow', 'Cyan', 'Magenta', 'White', and 'Black'.

foregroundOpacity: 1: This indicates the opacity to use for the text of the selected sub-expression.

backgroundColor: 'Blue': This specifies the background color to use for the selected sub-expression during expression exploration. The color should be chosen from among the following: 'Blue', 'Red', 'Green', 'Yellow', 'Cyan', 'Magenta', 'White', and 'Black'.

backgroundOpacity: .2: This indicates the opacity to use for the background color of the selected sub-expression.

highlight: 'None': Chooses a particular highlighter for showing collapsible sub-expressions. Choices are 'None', 'Flame', and 'Hover'.

flame: false: This flag switches on the Flame highlighter, which permanently highlights collapsible sub-expressions, with successively darkening background for nested collapsible expressions.

hover: false

This switches on the Hover highlighter that highlights collapsible sub-expression when hovering over them with a the mouse pointer.

Note, that having both 'hover' and 'flame' set to true can lead to unexpected side-effects.

treeColoring: false: This setting enables tree coloring, by which expressions are visually distinguished by giving neighbouring symbols different, ideally contrasting foreground colors.

Magnification Options

magnification: 'None': This option specifies a particular magnifier for enlarging sub-expressions. Choices are 'None', 'Keyboard', and 'Mouse'.

magnify: '400%': This gives the magnification factor (as a percent) to use for the zoomed sub-expression when zoomed sub-expressions are being displayed during expression exploration. The default is 400%.

keyMagnifier: false: Switches on zooming of sub-expressions during keyboard exploration of an expression.

mouseMagnifier: false

Switches on zooming of sub-expressions by hovering with the mouse pointer.

Note, using both 'keyMagnifier' and 'mouseMagnifier together can lead to unwanted side-effect.

align: 'top': This setting tells where to place the zoomed version of the selected sub-expression, when zoomed sub-expressions are being displayed during expression exploration.

Semantic Info Options

Semantic information explorers are a feature that displays some semantic information of a sub-expression when hovering over it with the mouse pointer. Note, multiple information explorers work well together.

infoType: false: Activates an explorer that investigates the semantic type of sub-expressions. The type is an immutable property of an expression, that is independent of its particular position in a formula. Note, however that types can change depending on subject area of a document.

infoRole: false: Activates an explorer to present the semantic role of a sub-expression, which is dependent on its context in the overall expression.

infoPrefix: false

Activates explorer for prefix information, which pertains to the position of a sub-expression. Examples are 'exponent', 'radicand', etc. These would also be announced during interactive exploration with speech output.

For more details on these concepts, see also the documentation of the Speech Rule Engine.

Note

While multiple keyboard-based exploration techniques work well together and can be easily employed simultaneously, switching on multiple mouse-based exploration tools can lead to unexpected interactions of the tools and often unpredictable side effects.

Assisitve-MML Extension Options

This extension adds visually hidden MathML to MathJax’s output that can be voiced by some screen readers. See the Screen Reader Support section for more details on how this works.

The assisitive-mml extension is included in all the combined components, and is active by default, so screen reader users will not need to do anything to activate it. There is a menu item that controls whether to insert the assistive MathML, so visual users can turn it off if they wish.

The extension adds an action to the document’s default renderActions object that does the MathML insertion. You can disable that by using the following configuration.

MathJax = {
  options: {
    enableAssistiveMml: false
  }
};