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
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: {
enrichSpeech: 'none', // or 'shallow', or 'deep'
}
};
Option Descriptions¶
-
enrichSpeech: 'none'
This setting controls whether MathJax uses the Speech-Rule Engine (SRE) to generate a speech string for the expressions on the page. If set to
'none'
(the default), no speech is generated. When set to'shallow'
, speech is generated only for the complete equation, and when set to'deep'
, every speakable element is marked with its speech string. These speech strings are put indata-semantic-speech
attributes, when generated. The output processors will find the top-most speech string and set the appropriate attributes on the output they generate so that screen readers can find it.
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: {
makeCollapsible: true // insert maction to allow collapsing
}
};
Option Descriptions¶
-
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 ofCollapse
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 ofComplexityVisitor
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: {
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
speechRules: 'mathspeak-default', // speech rules as domain-style pair
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¶
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.
-
speechRules: 'mathspeak-default'
This option selects the speech rules used for speech generation in a domain-style pair. For a list of possible selections please see the documentation of the Speech Rule Engine, e.g., by running
npx speech-rule-engine --options
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 highligher, 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 override that by using the following configuration.
MathJax = {
options: {
renderActions: {
assistiveMML: []
}
}
};