Documentation status
Last modified by Lucas Charpentier on 2026/10/27 10:30
Contents
This page tracks the progress on the documentation and consistency criteria of the macros, then, as of 2026-09-23, where each of the 68 macros analysed in this proposal is documented, and whether that documentation has been migrated to the new documentation tree on xwiki.org.
Documentation and consistency criteria
The KOs of the criteria L1, L2 and L3 of the Triage are not reported macro by macro: L2 and L3 are each tracked by one generic JIRA issue, and L1 by one issue per macro; the tables below show their progress. When a fix is done, set the status of its row to In progress or Fixed and link the documentation page, the pull request or the ticket in the Fix column. A row is Other ticket when a ticket of another criterion makes the KO moot, like a macro moving to the Internal category, whose documentation is then not needed.
The documentation column says where the macro is documented at the time of the audit, see the Status per macro section below for the migration of each macro. "Minor" marks the KOs recorded as minor in the audit.
L1 consistency
JIRA issues: one per macro, in the Fix column. 2 KOs, as of 22 October 2026.
| Macro | Status | Documentation | Problem | Fix |
|---|---|---|---|---|
| gallery | To do | Legacy | Its mandatory content uses a format of its own, a plain text list of images, so its Quick Action opens the Edit Macro dialog, unlike figure and container. | XWIKI-25506 |
| office | To do | Legacy | It declares no mandatory parameter, unlike include and display, so its Quick Action inserts an empty call that renders an error box. | XWIKI-25507 |
L2 doc-parameters
JIRA issue: XINFRA-525. 51 KOs, as of 22 October 2026. Unless the Problem column says otherwise, the parameters are only documented on a legacy extensions.xwiki.org page, with no page in the new documentation tree: the fix is the migration of that page, checked against the macro descriptor.
| Macro | Status | Documentation | Problem | Fix |
|---|---|---|---|---|
| activity | To do | Legacy | Documents a "subentries" parameter that does not exist. The defaults of wikis, spaces and authors are only in the text. | - |
| cache | To do | Legacy | No new page, unlike async. The content is not listed, and the page gives id a default that the descriptor leaves empty. | - |
| chart | To do | Legacy | Lists colors as a parameter while it is a key of params. Documents width and height as strings instead of integers. The content is not in the table. | - |
| chartjs | To do | Legacy | The mandatory content is not in the table. The type list misses horizontalBar. Width and height only exist as keys of options. | - |
| children | To do | Legacy | Documents the "name" sort, which the Sort by select does not offer. | - |
| code | To do | Legacy | Documents only language, layout and source, and covers the box parameters with a reference to the Box Macro page. | - |
| comment | To do | Legacy | Minor. Says "No parameters." and does not describe the mandatory content. | - |
| container | To do | Legacy | cssClass and the content are not documented. | - |
| content | To do | Legacy | Gives syntax as mandatory, while it defaults to the current syntax since XWiki 15.1. The content is not documented. | - |
| context | To do | Legacy | The parameters are a list with no table. The content is not mentioned, and the default of transformationContext is not stated. | - |
| dashboard | To do | Legacy | Gives "none" as the default of layout, while the macro declares columns. | - |
| documents | To do | Legacy | The description parameter is not documented. Documents space and parent as deprecated parameters the macro does not declare. | - |
| documentTree | To do | Legacy | Documents showChildDocuments, which was removed, and gives sortDocumentsBy a title:asc default the macro does not declare. | - |
| example | Other ticket | None | No documentation at all. | XWIKI-25018: the macro becomes internal. |
| faq | To do | Legacy | Section of the FAQ Application page. filter is described in one sentence, with no table, and its keys only appear in the examples. | - |
| figure | To do | Legacy | The table lists only type. The content and its optional flag are only shown in the examples. | - |
| figureCaption | To do | Legacy | Section of the Figure Macro page. The content of the caption is not documented. | - |
| footnote | To do | Legacy | Describes the content as "text" and does not say that it is mandatory. | - |
| gallery | To do | Legacy | The content and its mandatory flag are missing. The documented defaults of width and height come from the stylesheet, not the descriptor. | - |
| groovy | To do | Legacy | The content and jars are not documented, output is only mentioned and wiki is not described. | - |
| html | To do | Legacy | The legacy table matches the descriptor: only the migration is missing. | - |
| iconPicker | To do | Legacy | Section of the Icon Theme Application page, with no parameter table. prefix is not documented and its stated default is wrong. | - |
| id | To do | Legacy | Only the migration is missing. | - |
| include | To do | Legacy | Gives "document" as the only value of type, while the macro accepts 13 entity types. | - |
| jwplayer | To do | Legacy | No mandatory or default column, and the values of attachment are split in two rows by version. | - |
| liveData | To do | New | New page. The documented defaults of showPageSizeDropdown and properties do not match the behavior. The content is not in the table. | - |
| mathjax | To do | Legacy | No parameter table: the mandatory content is not listed. | - |
| mention | To do | Legacy | Section of the Mentions Application page. Marks style and anchor as mandatory, and gives wrong or missing defaults for anchor, type and style. | - |
| menu | To do | Legacy | label and the content are not documented. Documents modifiers of type that the descriptor does not mention. | - |
| notificationsApplicationsPreferences | Other ticket | New | Minor. Shared Notification Settings Macros page: no parameter table, no default for target, no mandatory flags. | XWIKI-25468: the macro moves to the Internal category. |
| notificationsAutoWatchPreferences | Other ticket | New | Minor. Shared Notification Settings Macros page: no parameter table, no default for target, no mandatory flags. | XWIKI-25468: the macro moves to the Internal category. |
| notificationsCustomFiltersPreferences | Other ticket | New | Minor. Shared Notification Settings Macros page: no parameter table, no default for target, no mandatory flags. | XWIKI-25468: the macro moves to the Internal category. |
| notificationsEmailPreferences | Other ticket | New | Minor. Shared Notification Settings Macros page: no parameter table, no default for target, no mandatory flags. | XWIKI-25468: the macro moves to the Internal category. |
| notificationsFiltersPreferences | Other ticket | None | No documentation at all. | XWIKI-25468: the macro moves to the Internal category. |
| notificationsSystemFiltersPreferences | Other ticket | New | Minor. Shared Notification Settings Macros page: no parameter table, no default for target, no mandatory flags. | XWIKI-25468: the macro moves to the Internal category. |
| office | To do | Legacy | Marks both reference and attachment as mandatory, while only one is needed. Misdescribes filterStyles. No example of the plain call. | - |
| plantuml | To do | Legacy | The content is not in the table, and the documented defaults of format and type differ from the dialog. | - |
| putFootnotes | To do | Legacy | Section of the Footnote Macro page, accurate: only the migration is missing. | - |
| python | To do | Legacy | No parameter table. The content, jars and output are not documented, and wiki is only mentioned. | - |
| script | To do | Legacy | The content is not documented and language has no default. Documents the script bindings as if they were parameters. | - |
| tableToChartJS | To do | Legacy | Section of the Chart.js Integration page. The type list misses horizontalBar, width and height have no unit, and the useful options are only documented for chartjs. | - |
| tagcloud | To do | Legacy | Says to use the macro in xwiki/2.0 syntax, and gives limit a "no limit" default the macro does not declare. | - |
| template | To do | Legacy | The new Templates page only quotes the call. Documents name as mandatory, which the macro does not declare, and the description of output has a typo. | - |
| toc | To do | Legacy | Only the migration is missing. | - |
| translation | To do | Legacy | The content, the message shown when the key has no translation, is not documented. | - |
| tree | To do | Legacy | The content and exclusions are not documented, and the description of root differs from the one of the macro. | - |
| uiextension | To do | Legacy | Does not say what a UI extension is or where to find the identifiers. | - |
| uiextensions | To do | Legacy | Does not say what an extension point is or list the ones of XWiki Standard. | - |
| useravatar | To do | Legacy | Wrong default and description for height. Calls the avatar a URL, while it is an attachment of the profile. | - |
| velocity | To do | Legacy | Only filter is documented. The content and jars are missing, and output and wiki are only mentioned. | - |
| wikimacroparameter | To do | New | Minor. New page with no parameter table: name is not marked as mandatory, and the Content parameter is never mentioned. | - |
L3 doc-example
JIRA issue: XINFRA-526. 20 KOs, as of 22 October 2026. The fix is an example of the most common use that renders on XWiki Standard when copied, in the new documentation page of the macro.
| Macro | Status | Documentation | Problem | Fix |
|---|---|---|---|---|
| cache | To do | Legacy | Minor. Every example caches placeholder text, none shows the real use, the result of a slow script, and Example 1 fails when copied. | - |
| content | To do | Legacy | The example uses the confluence/1.0 syntax, missing from XWiki Standard, and renders an error. | - |
| dashboard | To do | Legacy | Minor. No example to copy: the only call is an unclosed {{dashboard}} in a sentence, and the suggested source is a page hidden from the picker. | - |
| example | Other ticket | None | No documentation, so no example. | XWIKI-25018: the macro becomes internal. |
| faq | To do | Legacy | Minor. The examples are filter fragments, not macro calls, and filter="tag=test" lists nothing. | - |
| groovy | To do | Legacy | Minor. The Parameters definition shows an incomplete fragment, and the Example section repeats the first example. | - |
| html | To do | Legacy | Minor. The examples show off wiki="true" or hold no HTML: none inserts plain HTML markup. | - |
| iconPicker | To do | Legacy | No documentation example calls the macro. | - |
| include | To do | Legacy | The usage starts with the hidden page parameter. The reference form only comes as Example 4, on a page that does not exist. | - |
| jwplayer | To do | Legacy | Minor. The block of examples fails when copied, since its 5 standalone calls are in one paragraph. | - |
| notificationsApplicationsPreferences | Other ticket | New | No example of the most common call, the one of the user profile with user. | XWIKI-25468: the macro moves to the Internal category. |
| notificationsAutoWatchPreferences | Other ticket | New | No example of the most common call, the one of the user profile with user. | XWIKI-25468: the macro moves to the Internal category. |
| notificationsCustomFiltersPreferences | Other ticket | New | No example of the most common call, the one of the user profile with user. | XWIKI-25468: the macro moves to the Internal category. |
| notificationsEmailPreferences | Other ticket | New | No example of the most common call, the one of the user profile with user. | XWIKI-25468: the macro moves to the Internal category. |
| notificationsFiltersPreferences | Other ticket | None | No documentation, so no example. | XWIKI-25468: the macro moves to the Internal category. |
| notificationsSystemFiltersPreferences | Other ticket | New | No example of the most common call, the one of the user profile with user. | XWIKI-25468: the macro moves to the Internal category. |
| template | To do | Legacy | The only example uses a placeholder template name and renders nothing. The most common call, loading a macro library, is not documented. | - |
| uiextension | To do | Legacy | The only example passes the Maven identifier of an extension and renders an error. | - |
| uiextensions | To do | Legacy | The only example uses an extension point with no extension, so it renders nothing. | - |
| velocity | To do | Legacy | Minor. Example 1 is a template with placeholders and Example 4 fails with a parse error. | - |
Summary
- 12 macros have a Reference page in the new documentation tree.
- 47 macros are still documented only in the legacy documentation, mostly on extensions.xwiki.org.
- 9 macros have no documentation at all.
Beyond the migration itself, a recurring problem shows in the table: 13 macros have no page of their own and are only covered by a section of the page of the application that ships them, which makes them hard to find and impossible to link to precisely.
Status per macro
Conventions
A macro counts as Migrated when a page built on the DocApp.Code.RenderingMacroClass template exists for it under documentation. The list of those pages comes from the Solr query class:"DocApp.Code.RenderingMacroClass", so this table can be refreshed by re-running it.
The migration conventions themselves, from the page template to the parameter table columns and the naming and placement rules, are discussed in the forum thread Consistency of the macro parameter table.
