toc
Audit
- Macro ID
- toc
- Source
- XS
- Type
- Generator
- Classification reason
- Status
- Reviewed
- Criteria version
- 15.20
- XWiki version
- 18.8.0
- Audit date
- 2026-10-14
- Auditor
- Compared macros
- children documentTree
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 | KO | the description "Generates a table of contents." repeats the name, and does not say that the macro lists the headings of the page as links to them. |
| D3 category | OK | |
| D4 quick-action | KO | Quick Actions finds the macro first for "toc", "Table of contents", the French name "Table des matières" and the synonym "contents". The synonyms "outline", "headings", "index" and "summary" give no result: "headings" only lists the Heading 1 to 6 actions. |
| L1 consistency | OK | compared with children and documentTree: like them, no parameter is mandatory, there is no content, and the Quick Action inserts the macro right away, with no dialog. |
| L2 doc-parameters | KO | the parameters are only documented on the legacy extensions.xwiki.org page, not in the new documentation. |
| L3 doc-example | OK | |
| I1 pattern | OK | compared with children, the reference generator: both are inserted by their Quick Action without a dialog, and through the Insert Macro dialog with an Edit Macro dialog whose fields are all optional. |
| I2 zero-config | KO | Quick Actions and the Edit Macro dialog submitted with the default values insert {{toc/}} . On a page without headings it shows the generic "macro:toc" placeholder in the editor and renders nothing in view mode, with no hint that the table fills in once headings are added. In the editor, then in view mode:   |
| I3 instant | N/A | |
| I4 cursor | N/A | |
| I5 focus | OK | the macro has no mandatory parameter, and its five fields are visible without scrolling, with the focus on the first field, Depth. The Quick Action inserts the macro without the dialog, so only the Insert Macro dialog shows it. |
| E1 wysiwyg | OK | |
| E2 errors | KO | invalid values are accepted silently or give a message that does not name the parameter. For example, {{toc numbered="maybe"/}} is read as false, {{toc start="7"/}} renders nothing, with no message. {{toc depth="abc"/}} renders "Failed to validate bean: [must be greater than or equal to 1]", which names neither the parameter nor the fact that a number is expected, and {{toc scope="abc"/}} gives the allowed values but not the parameter name. |
| E3 nesting | KO | in a list item and in a table cell, like * {{toc/}} , the macro is inline and renders "The [toc] macro is a standalone macro and it cannot be used inline." in the editor and in view mode. Inserting it from Quick Actions at the end of a list item gives the same error and saves * two{{toc/}}((( ))) . It renders only when wrapped in a group, * two ((( {{toc/}} ))) , which the editor does not create. In a box it works. |
| E4 inline-support | OK | the macro declares no inline support, and its output is a nested list, which cannot be inside a sentence. |
| E5 empty | N/A | |
| E6 inplace | N/A |
Parameters
| Parameter | C1 clarity | C2 mandatory | C3 defaults | C4 input-assistance | C5 groups | C6 order | C7 alternatives | C8 advanced | C9 technical | C13 constraints | Notes |
|---|---|---|---|---|---|---|---|---|---|---|---|
| depth | OK | OK | OK | KO | OK | OK | N/A | OK | OK | OK | C4: a plain text field where any text can be typed, while the value is a heading level from 1 to 6, which a select or a number field would fit. |
| numbered | OK | OK | OK | OK | OK | OK | N/A | OK | OK | N/A | |
| reference | OK | OK | OK | OK | OK | OK | N/A | OK | OK | N/A | C1: "Reference" is a technical name, but the description explains it: "Reference to the document for which to generate the table of contents. Leave empty for the current page." C3: no default is declared, but the field opens empty, which means the current page, the value of the most common example. |
| scope | OK | OK | OK | OK | OK | OK | N/A | OK | OK | N/A | C1: "Scope" and its values Local and Page are technical names, but the description explains them with an example: "if the macro is written in a section, only subsections of this section will be listed". |
| start | KO | OK | OK | KO | OK | OK | N/A | OK | OK | OK | C1, minor: the name "Start" does not say that it is the first heading level listed; the description "the minimum section level" does. The French name "niveau de début" is clearer. C4: a plain text field where any text can be typed, while the value is a heading level from 1 to 6, which a select or a number field would fit. C6: the fields are in the order depth, reference, scope, start, numbered: start comes after depth, reference and scope, although it is set together with depth. The most common example sets none of them, so the order is OK per the measure. |
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 |
|---|---|---|---|
| D2 | D2 summary | XWIKI-25493 | |
| D4 | D4 quick-action | XWIKI-25444 | |
| L2 | L2 doc-parameters | XINFRA-525 | |
| I2 | I2 zero-config | XWIKI-25512 | |
| E2 | E2 errors | XWIKI-25182 (partial) | XCOMMONS-3847 (partial), XRENDERING-823 (partial), XWIKI-25512 (partial) |
| E3 | E3 nesting | XWIKI-23501 | |
| C4:depth | C4 input-assistance, depth | XWIKI-25182 | |
| C1:start | C1 clarity, start | XWIKI-25493 | |
| C4:start | C4 input-assistance, start | XWIKI-25182 |
Tickets
| Ticket | Origin | KOs covered | KOs partly covered |
|---|---|---|---|
| XWIKI-23501 | Existing | E3 | |
| XWIKI-25182 | Existing | C4:depth C4:start | E2 |
| XCOMMONS-3847 | New | E2 | |
| XRENDERING-823 | New | E2 | |
| XWIKI-25444 | New | D4 | |
| XWIKI-25493 | New | C1:start D2 | |
| XINFRA-525 | New | L2 | |
| XWIKI-25512 | New | I2 | E2 |
Known issues of this macro
No known issue is specific to this macro.
68 more known issues affect every macro: see the Known issues.
