# tagformat

The tagformat extension provides the ability to customize the format of the equation tags and automatic equation numbers. You do this by providing functions in the `tagformat` object of the `tex` block of your MathJax configuration. The functions you can provide are listed in the tagformat Options section.

To load the tagformat extension, add `'[tex]/tagformat'` to the `load` array of the `loader` block of your MathJax configuration, and add `'tagformat'` to the `packages` array of the `tex` block.

    window.MathJax = {
      loader: {load: ['[tex]/tagformat']},
      tex: {packages: {'[+]': ['tagformat']}}
    };

## tagformat Options

Adding the tagformat extension to the `packages` array adds a `tagformat` sub-object to the `tex` configuration block with the following values:

    tagformat: {
       number: (n) => n.toString(),
       tag:    (tag) => '(' + tag + ')',
       id:     (id) => 'mjx-eqn:' + id.replace(/\s/g, '_'),
       url:    (id, base) => base + '#' + encodeURIComponent(id),
     }

number: function (n) {return n.toString()}

  A function that tells MathJax what tag to use for equation number `n`. This could be used to have the equations labeled by a sequence of symbols rather than numbers, or to use section and subsection numbers instead.

tag: function (n) {return '(' + n + ')'}

  A function that tells MathJax how to format an equation number for displaying as a tag for an equation. This is what appears in the margin of a tagged or numbered equation.

id: function (n) {return 'mjx-eqn:' + n.replace(/\\s/g, '_')}

  A function that tells MathJax what ID to use as an anchor for the equation (so that it can be used in URL references).

url: function (id, base) {return base + '#' + encodeURIComponent(id)}

  A function that takes an equation ID and base URL and returns the URL to link to it. The `base` value is taken from the baseURL value, so that links can be make within a page even if it has a `<base>` element that sets the base URL for the page to a different location.

## Example: Section Numbering

This example shows one way to provide section numbers for the automatic equation numbers generated when the `tags` option in the `tex` configuration block is set to `'ams'` or `'all'`.

    MathJax = {
      section: 1,
      tex: {
        tagformat: {
          number: (n) => MathJax.config.section + '.' + n,
          id: (tag) => 'eqn-id:' + tag
        }
      },
      startup: {
        ready() {
          MathJax.startup.defaultReady();
          MathJax.startup.input[0].preFilters.add(({math}) => {
            if (math.inputData.recompile) {
              MathJax.config.section = math.inputData.recompile.section;
            }
          });
          MathJax.startup.input[0].postFilters.add(({math}) => {
            if (math.inputData.recompile) {
              math.inputData.recompile.section = MathJax.config.section;
            }
          });
        }
      }
    };

This arranges for automatic equation numbers to be of the form `1.n`, and uses ids of the form `eqn-id:1.n` as the `id` attribute of the tags within the web page. It also sets up pre- and post-filters for the TeX input jax that arrange for the section number to be properly handled for automatically numbered equations that contain forward references to later expressions. This example uses the modern function notation (using `=>`), but you could also use `function (n) {return ...}`.

You can adjust the section number using JavaScript by setting the `MathJax.config.section` variable. It is also possible to create TeX macros for controlling the section number. Here is one possibility:

    MathJax = {
      startup: {
        ready() {
          const Configuration = MathJax._.input.tex.Configuration.Configuration;
          const CommandMap = MathJax._.input.tex.SymbolMap.CommandMap;
          new CommandMap('sections', {
            nextSection: 'NextSection',
            setSection: 'SetSection',
          }, {
            NextSection(parser, name) {
              MathJax.config.section++;
              parser.tags.counter = parser.tags.allCounter = 0;
            },
            SetSection(parser, name) {
              const n = parser.GetArgument(name);
              MathJax.config.section = parseInt(n);
            }
          });
          Configuration.create(
            'sections', {handler: {macro: ['sections']}}
          );
          MathJax.startup.defaultReady();
        }
      }
    };

Of course, you will want to merge this configuration in with the rest of your configuration options.

This makes two new macros available: `\nextSection`, which increments the section counter, and `\setSection{n}`, which sets the section number to `n`. Note that these must be issued within math delimiters in order for MathJax to process them. In order to prevent them from producing any output in your page, you could enclose them within a hidden element. For example,

    <span style="display: hidden">\(\nextSection\)</span>

or something similar.