mathjax
Last modified by Lucas Charpentier on 2026/10/27 10:29
Audit
- Macro ID
- mathjax
- Source
- Mathjax Macro
- Type
- Wrapper
- Classification reason
- Wrapper: the output is the formula the user types, which MathJax typesets in the browser. The macro only marks the text for the JavaScript library and adds no decoration or generated content.
- Status
- Reviewed
- Criteria version
- 15.20
- XWiki version
- 18.8.0
- Audit date
- 2026-10-20
- Auditor
- Compared macros
- code html
Lucas CharpentierSources
Where to gather the information the criteria are checked against, see Gather the sources.
| Source | What it gives | Used for | Where |
|---|---|---|---|
| Documentation | Parameters, default values and examples, including the most common example | L2, L3, and the criteria measured with the most common example | https://extensions.xwiki.org/xwiki/bin/view/Extension/MathJax/MathJaxMacro/#HUsage |
| Source code | How the macro declares its parameters and content: types, groups, features, advanced and hidden flags, constraints, content type, inline support | C4, C5, C7, C8, C9, C13, E4, E6 | https://github.com/xwiki-contrib/macro-mathjax/blob/master/macro-mathjax-ui/src/main/resources/Macros/MathJaxMacro.xml |
| Macro descriptor | What the Edit Macro dialog is built from, on design.xwiki.org | D1, D2, C1 to C9, E4 | Descriptor, list of macros with their categories |
| Translations | The name, description and parameter names in each language | D1, D2, D4, C1 | l10n.xwiki.org |
| Uses in XWiki pages | How XWiki itself uses the macro, a realistic example when the documentation has none | L3, C2, C3, C6, C8, C9 | Search the xwiki organization on GitHub |
| Compared macros | The audits of the macros of the same type | L1, D3 | code, html |
| Other sources specific to this macro |
|---|
|
| Criterion | Result | Notes |
|---|---|---|
| D1 wording | KO | "MathJax" is the name of the JavaScript library that typesets the formulas, written in camelCase, not the word a user types for what the macro produces, like formula, equation or math. A user who does not know the library cannot guess what it does from the name, and the macro is not a product that XWiki defines. The documentation and the Confluence converter of xwiki-contrib/confluence call it "MathJax" too. |
| D2 summary | KO | "Enter content supported by the MathJax javascript engine." repeats the name and describes an input, not what the macro adds to the page. It never says that it displays mathematical formulas, nor which notation to type, and "javascript engine" is technical wording. The French and German descriptions are the English text. |
| D3 category | OK | the macro is in Content, while the compared macros code and html are in Formatting and Development. A formula is content the user inserts in the text, so Content is where a user looks, and a user could also look under Formatting, but a missing category there is not counted here. |
| D4 quick-action | KO | Quick Actions finds the macro first for "mathjax", "MathJax" and "math", where the last one matches the name itself. The synonyms "formula", "latex", "equation" and "tex" do not find it: "formula" lists a Formula entry that belongs to another extension, "latex" lists Template, "equation" lists nothing and "tex" lists Context, Paragraph, Find and Replace and PlantUML. The French and German names are "MathJax", the same as the English one, so no language with a different name can be tested. The rule of html, a technical macro named after its technology, does not apply as is, since users type the notation or the result, not the library. |
| L1 consistency | OK | compared with code and html, the two wrappers whose content is technical text typed in the Edit Macro dialog: all three open the dialog from their Quick Action with a required Content text area and declare inline support. mathjax has no parameter besides the content, and its mandatory content makes sense, since an empty formula shows nothing. The differences are by design. |
| L2 doc-parameters | KO | the macro is documented only on the legacy extensions.xwiki.org page, https://extensions.xwiki.org/xwiki/bin/view/Extension/MathJax/MathJaxMacro/, and a search of the new documentation tree by "mathjax", "latex" and "formula" finds only blog posts. The page has a Usage section but no parameter table: the content parameter, the only one, is not listed with its mandatory flag. |
| L3 doc-example | OK | the Usage example, a page with a numbered eqnarray, references to its equations, an equation and an inline sentence, is used as the most common example. It can be copied into a page and renders without error, once the browser has typeset it, which takes a few seconds in view mode. |
| I1 pattern | KO | the reference wrapper, warning, is inserted by its Quick Action without a dialog. The MathJax Quick Action opens the Edit Macro dialog with an empty Content text area, like code, html and velocity, see I3. |
| I2 zero-config | OK | submitting the Edit Macro dialog with the default content does nothing, with no message, since the content is required: the generic behavior of the dialog, and an empty formula has no sensible result. {{mathjax/}} written in the source renders the error "Failed to execute the [mathjax] macro. Cause: [Missing macro content: this macro requires content (a body)]", which the editor never produces. |
| I3 instant | KO | inserting from the Quick Actions menu opens the Edit Macro dialog with an empty Content text area, and the macro is only inserted after typing a formula and submitting. |
| I4 cursor | KO | after submitting the dialog, the macro widget is selected and the cursor is not in its content: typed text goes nowhere, and the content can only be changed through the dialog, see E6. |
| I5 focus | N/A | |
| E1 wysiwyg | KO | the editor shows the formulas as raw LaTeX, like \begin{equation} y = \frac{c}{cb-ad} \end{equation} , still after 30 seconds and after saving and reopening the page, while view mode shows them typeset, with numbered equations and fractions. The macro output depends on JavaScript that the editor does not run, and it has no edit representation that keeps the meaning of a formula. To reproduce: edit a page holding the Usage example, then view it. |
| E2 errors | KO | a malformed formula is accepted silently: {{mathjax}}\(\frac{a}{\){{/mathjax}} is displayed as its raw source, with no message and no error style. An unknown command like $$\nosuchcommand{x}$$ is displayed in red by MathJax, which says what is wrong. The empty content gives the error described in I2, which names the missing content. |
| E3 nesting | OK | in a list item, a table cell and a box, the macro renders inside the text with its formula typeset and no error. A list, a table and a box written in the content are shown as raw text, like {{box}} Boxed formula ... {{/box}} , which is expected since the content is LaTeX, not wiki syntax. The content is never edited in place, at the top level or nested, see E6. |
| E4 inline-support | OK | the macro declares inline support, and an inline formula renders inside a sentence, as in Solving equation {{mathjax}}\ref{eq:second}{{/mathjax}} for {{mathjax}}x{{/mathjax}} . A display formula written with $$ in the content breaks the line, which is what MathJax does for display math. |
| E5 empty | KO | the content is never editable in place: the macro is a widget whose raw LaTeX is read-only, one click selects it and the cursor never enters it, so the content can only be typed in the Edit Macro dialog, see I4 and E6. |
| E6 inplace | KO | the content is never edited in place: the editor shows the raw LaTeX as a read-only widget, and changing it needs the Edit Macro dialog, where it is a plain text area with no formula editing aid and no preview, also when editing an existing macro. |
Parameters
| Parameter | C1 clarity | C2 mandatory | C3 defaults | C4 input-assistance | C5 groups | C6 order | C7 alternatives | C8 advanced | C9 technical | C13 constraints | Notes |
|---|---|---|---|---|---|---|---|---|---|---|---|
| $content | KO | OK | N/A | OK | N/A | OK | N/A | N/A | N/A | N/A | C1: the name "Content" is clear, but the description "Macro content" is the generic one of every macro and says nothing about the expected text. The content must be LaTeX with MathJax delimiters, like \( ... \) for an inline formula and $$ ... $$ or an environment such as \begin{equation} for a display one, and a text without delimiters, like {{mathjax}}x{{/mathjax}} , is shown as plain text. The description is not translated in French and German. C2: the content is mandatory, which is right since an empty formula shows nothing, and the dialog refuses an empty value. C4: a text area is the field for LaTeX text. A formula editor or a preview would help, but that is an editing aid of the content, counted under E6. C6: the content is the only parameter. |
KOs and tickets
Every KO needs a ticket covering it, see Report the KOs. One ticket can cover several KOs. Known issues filed for this macro are suggested in italics: link them as existing tickets when they cover the KO.
| KO | Criterion | Existing tickets | New tickets |
|---|---|---|---|
| D1 | D1 wording | MATHJAX-38 | |
| D2 | D2 summary | MATHJAX-38 | |
| D4 | D4 quick-action | XWIKI-25444 | |
| L2 | L2 doc-parameters | XINFRA-525 | |
| I1 | I1 pattern | XWIKI-25563 | |
| I3 | I3 instant | XWIKI-25563 | |
| I4 | I4 cursor | XWIKI-25569 | |
| E1 | E1 wysiwyg | XWIKI-25523 (partial), MATHJAX-39 | |
| E2 | E2 errors | XCOMMONS-3847 (partial), XRENDERING-823 (partial), MATHJAX-39 (partial) | |
| E5 | E5 empty | MATHJAX-40 | |
| E6 | E6 inplace | MATHJAX-40 | |
| C1:$content | C1 clarity, $content | MATHJAX-38 |
Tickets
| Ticket | Origin | KOs covered | KOs partly covered |
|---|---|---|---|
| XCOMMONS-3847 | New | E2 | |
| XRENDERING-823 | New | E2 | |
| XWIKI-25444 | New | D4 | |
| MATHJAX-38 | New | C1:$content D1 D2 | |
| XINFRA-525 | New | L2 | |
| XWIKI-25523 | New | E1 | |
| MATHJAX-39 | New | E1 | E2 |
| XWIKI-25563 | New | I1 I3 | |
| MATHJAX-40 | New | E6 E5 | |
| XWIKI-25569 | New | I4 |
Known issues of this macro
No known issue is specific to this macro.
68 more known issues affect every macro: see the Known issues.
