html
Last modified by Lucas Charpentier on 2026/10/27 10:28
Audit
- Macro ID
- html
- Source
- XS
- Type
- Generator
- Classification reason
- Generator, like the script macros: the output is what the browser renders from the HTML typed in the content, which the reader never sees as typed. The parameters only change how the content is processed.
- Status
- Reviewed
- Criteria version
- 15.20
- XWiki version
- 18.8.0
- Audit date
- 2026-10-16
- Auditor
- Compared macros
- velocity groovy
Lucas CharpentierSources
Where to gather the information the criteria are checked against, see Gather the sources.
| Other sources specific to this macro |
|---|
|
| Criterion | Result | Notes |
|---|---|---|
| D1 wording | OK | |
| D2 summary | OK | |
| D3 category | OK | |
| D4 quick-action | OK | Quick Actions finds the macro first for "html", "HTML" and the synonym "xhtml". "raw" lists Box, sequence and diagram, and "markup" is not a good synonym. For a technical macro whose name is its technical name, this is a good result. The French and German names are "HTML" too. |
| L1 consistency | OK | compared with velocity and groovy, which also take code as a mandatory text content: all three open the Edit Macro dialog from their Quick Action, with a required Content text area, and declare inline support. The wiki parameter defaults to false for html and to true for velocity and groovy, which is by design: the content of html is HTML, not wiki syntax. |
| L2 doc-parameters | KO | the parameters are documented only on the legacy extensions.xwiki.org page, https://extensions.xwiki.org/xwiki/bin/view/Extension/HTML%20Macro, not in the new documentation. The legacy table matches the descriptor for clean and wiki. |
| L3 doc-example | KO | minor: both documentation examples show off the wiki parameter, {{html wiki="true"}}<table><tr><td>* listitem</td></tr></table>{{/html}} , or hold no HTML, {{html}}**some escaped text**{{/html}} ; none shows the plain use, inserting HTML markup, which is as frequent in XWiki itself. The audit uses the wiki="true" table as the most common example. |
| I1 pattern | OK | compared with the reference generator, children. The HTML Quick Action opens the Edit Macro dialog with an empty Content text area, and the macro needs its HTML to do anything, so the dialog is OK, like include and the script macros. |
| I2 zero-config | OK | the Edit Macro dialog cannot be submitted with the default values, since the content is mandatory and empty: it stays open, with no message, the generic behavior of the dialog. An empty HTML macro has no sensible result, and {{html/}} written in the source renders nothing, with no error. |
| I3 instant | N/A | N/A for a generator. The Quick Action opens the Edit Macro dialog with an empty Content text area, see I1. |
| I4 cursor | N/A | N/A for a generator. After submitting the dialog, the macro widget is selected, and the content can only be changed through the dialog. |
| I5 focus | OK | the content, the HTML, is the only mandatory parameter: the Edit Macro dialog shows its text area first, like the script macros, and every field is visible without scrolling. |
| E1 wysiwyg | OK | |
| E2 errors | KO | invalid values are accepted silently, with no message. For example, {{html wiki="abc"}}<p>**bold**</p>{{/html}} is read as false and shows "bold", while {{html wiki="yes"}}<p>**bold**</p>{{/html}} is read as true; {{html clean="maybe"}}...{{/html}} is accepted the same way. Malformed HTML in the content is fixed by the cleaning, which is the purpose of the clean parameter, not an error. |
| E3 nesting | KO | in a list item and in a table cell, like * item {{html}}<table><tr><td>Cell</td></tr></table>{{/html}} , the macro is inline and renders "When using HTML content inline, you can only use inline HTML content. Block HTML content (such as tables) cannot be displayed. Try leaving an empty line before and after the macro.", in the editor and in view mode; the advice to leave empty lines cannot be applied in a list item. It renders only when wrapped in a group, * ((( {{html}}<table>...</table>{{/html}} ))) . Inside a box it renders, and with wiki="true" a list, a table and a box inside its content render. |
| E4 inline-support | OK | the macro declares inline support, and inline HTML renders inside a sentence, like The text is {{html}}<span style="color: red;">red <strong>HTML</strong></span>{{/html}} in a sentence. . Block HTML, like the table of the most common example, gives the explicit error quoted in E3 when used inline, which the HTML itself causes. |
| E5 empty | N/A | N/A for a generator. An empty macro shows a visible "macro:html" placeholder that one click selects, and the content can only be typed in the Edit Macro dialog. |
| E6 inplace | N/A | N/A for a generator. The HTML is still edited only in a plain text area of the Edit Macro dialog, with no HTML editing aid, also when editing an existing macro, which is worth an improvement outside the criteria. |
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 | OK | OK | N/A | OK | N/A | OK | N/A | N/A | N/A | N/A | C4: a plain text area in the Edit Macro dialog, counted under E6. |
| clean | KO | OK | OK | OK | OK | OK | N/A | OK | OK | N/A | C1: the description "Indicate if the HTML should be transformed into valid XHTML or not." uses a wrong term: since XWiki 14.1 the cleaning follows the HTML version of the rendering, HTML 5 by default, not XHTML. It also does not say that unchecking it has no effect without script right, see the Security section of the documentation. Shown in the Edit Macro dialog of {{html}}<p>Text</p>{{/html}} . The French name, "Effacer", means "erase". |
| wiki | OK | OK | OK | OK | OK | KO | N/A | OK | OK | N/A | C3: the default, false, is preselected. The most common example sets wiki="true" only to show the parameter, and false is the right default for HTML content. C6, minor: the most common example sets wiki, which comes after clean. |
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 |
|---|---|---|---|
| L2 | L2 doc-parameters | XINFRA-525 | |
| L3 | L3 doc-example | XINFRA-526 | |
| E2 | E2 errors | XCOMMONS-3847, XRENDERING-823 | |
| E3 | E3 nesting | XWIKI-23501 | |
| C1:clean | C1 clarity, clean | XWIKI-25493 | |
| C6:wiki | C6 order, wiki | XRENDERING-825 |
Tickets
| Ticket | Origin | KOs covered | KOs partly covered |
|---|---|---|---|
| XCOMMONS-3847 | New | E2 | |
| XRENDERING-823 | New | E2 | |
| XWIKI-25493 | New | C1:clean | |
| XRENDERING-825 | New | C6:wiki | |
| XINFRA-525 | New | L2 | |
| XINFRA-526 | New | L3 | |
| XWIKI-23501 | Existing | E3 |
Known issues of this macro
| Issue | Title | Status | Criteria |
|---|---|---|---|
| XWIKI-19950 | Make the HTML macro editable inline | Open | E6 |
68 more known issues affect every macro: see the Known issues.
