.. _a11y-extensions:

****************************
The Accessibility extensions
****************************

MathJax maintains a set of extensions for providing advanced 
accessibility features. These extensions are an official part
of MathJax but are stored in a separate code repository.

The full documentation is available `on GitHub <https://github.com/mathjax/MathJax-a11y/blob/master/docs/README.md>`_
and we summarize the options below.

Each accessibility extension can be loaded using the ``[a11y]``
path variable. The following extensions have configuration options.

accessibility-menu.js
---------------------

The standard approach is to only load the accessibility menu
extension which provides opt-ins for end-users via the MathJax 
menu. 

.. code-block:: javascript

  MathJax.Hub.Config({
    // ...your configuration options...
    extensions: ["[a11y]/accessibility-menu.js"]
  });
  
The accessibility menu extension can then be controlled in the
configuration block for the MathJax menu, e.g.,

.. code-block:: javascript

  MathJax.Hub.Config({
    // ...your configuration options...
    menuSettings: {
      collapsible: false, 
      autocollapse: false,
      explorer: false
    }
  });

.. note::

  The accessibility menu is part of all :ref:`combined configurations <config-files>`.

explorer.js
-----------

The Explorer extension provides exploration tools for 
sub-expressions. It is the largest piece of the accessibility 
extensions, controlling highlighting, navigation and voicing.

.. code-block:: javascript

  MathJax.Hub.Config({
    // ...your configuration options...
    explorer: {
      walker: 'syntactic',         // none, syntactic, semantic
      highlight: 'none',           // none, hover, flame
      background: 'blue',          // blue, red, green, yellow, cyan, magenta, white, black
      foreground: 'black',         // black, white, magenta, cyan, yellow, green, red, blue
      speech: true,                // true, false
      generation: 'lazy',          // eager, mixed, lazy
      subtitle: true,              // true, false
      ruleset: 'mathspeak-default' // mathspeak-default, mathspeak-brief, mathspeak-sbrief, chromevox-default, chromevox-short, chromevox-alternative
    }
  });


auto-collapse.js
----------------

This extension will automatically collapse sub-expressions
to allow the resulting equation to fit in the viewport width
and will react to changes in viewport width. 
It will automatically load ``collapsible.js`` (see below).


.. code-block:: javascript

  MathJax.Hub.Config({
    // ...your configuration options...
    "auto-collapse": {
      disabled: false;
    }
  });

collapsible.js
--------------

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.

The extension only offers a configuration option to disable it.


.. code-block:: javascript

  MathJax.Hub.Config({
    // ...your configuration options...
    collapsible: {
      disabled: false;
    }
  });

semantic-enrich.js
------------------

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 extension only offers a configuration option to disable it.

.. code-block:: javascript

  MathJax.Hub.Config({
    // ...your configuration options...
    "semantic-enrich": {
      disabled: false;
    }
  });
