WYSIWYG Usability of XWiki macros

Last modified by Vincent Massol on 2026/04/03 17:55

Manage
- Copy
Actions
Viewers
- Source
- Siblings
- Attachments (166)
- History
- Information
- Likes

Product: XWiki

Type: Requirements

Status: Idea

Participants

Lucas Charpentier

Accepted: No

Description

List of XS + recommended (non pro) macros

I currated this list to only contain macros that are completely open source, free, and kind of standard in the XWiki project: XWiki standard macros and the ones that are `Recommended`. This list and the following analysis was done on a XWiki 17.1.0-SNAPSHOT distribution ran locally.

Notably, I left out:

macros that are deprecated and replaced by another one
Macros from Pro extensions
Macros from non recommended extensions

Id of the macro	From project	Macro doc URL
async	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Async%20Macro/
attachmentGalleryPicker	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Attachment/Picker/Macro/
attachmentSelector	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Attachment%20Application#HAttachmentSelector
box	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Box%20Macro#HDescription
cache	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Cache%20Macro
chart	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Chart%20Macro#HUsage
chartjs	Chart.js Integration	https://extensions.xwiki.org/xwiki/bin/view/Extension/Chart.js%20Integration/#HChartJSMacro
children	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Children%20Macro/
code	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Code%20Macro/
comment	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Comment%20Macro
container	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Container%20Macro
content	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Content%20Macro#HUsage
context	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Context%20Macro#HUsage
dashboard	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Dashboard%20Macro#HDescription
display	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Display%20Macro#HFromWikiSyntax
displayIcon	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Icon%20Macro/#HFromWikiSyntax
documents	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Documents%20Macro#HDescription
documentTree	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Document%20Tree%20Macro#HWikiMacro
error	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Error%20Macro#HUsage
example	XS	NAN, no doc? https://www.xwiki.org/xwiki/bin/view/Help/Code/ExampleMacro#Information or https://extensions.xwiki.org/xwiki/bin/view/Extension/Help%20Application#HAvailableMacros which doesn't contain any reference to it... No backlinks on https://dev.xwiki.org/xwiki/bin/view/Help/Code/ExampleMacro#Information either. This macro is fairly difficult to find info about so I guess noone knows about it and barely noone uses it.
faq	FAQ Application	https://extensions.xwiki.org/xwiki/bin/view/Extension/FAQ%20Application#HFAQMacro
figure	Figure Macro	https://extensions.xwiki.org/xwiki/bin/view/Extension/Figure/Figure%20Macro/#HUsage
figureCaption	Figure Macro	https://extensions.xwiki.org/xwiki/bin/view/Extension/Figure/Figure%20Macro/#HUsage
figureTypeRecognizer	Figure Macro	https://extensions.xwiki.org/xwiki/bin/view/Extension/Figure/Figure%20Macro/#HFigureTypeIdentification (internal macro)
footnote	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Footnote%20Macro#HUsage
gallery	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Gallery%20Macro#HUsage
gdprSettings	GDPR Cookie Consent	https://store.xwiki.com/xwiki/bin/view/Extension/GDPRCookieConsent/#documentation store page only but LGPL 2.1 and no licences
groovy	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Groovy%20Macro#HUsage
html	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/HTML%20Macro#HUsage
iconPicker	XS	https://www.xwiki.org/xwiki/bin/view/IconThemesCode/IconPickerMacro https://extensions.xwiki.org/xwiki/bin/view/Extension/Icon%20Theme%20Application#HIconPickerMacro
id	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Id%20Macro#HUsage
include	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Include%20Macro#HUsage
info	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Info%20Macro#HUsage
jira	JIRA Macro	https://extensions.xwiki.org/xwiki/bin/view/Extension/JIRA/JIRA%20Macro#HUsage
jwplayer	JW Player Macro	https://extensions.xwiki.org/xwiki/bin/view/Extension/JW%20Player%20Macro#HUsage
liveData	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Live%20Data%20Macro/#HUsage
mathjax	Mathjax Macro	https://extensions.xwiki.org/xwiki/bin/view/Extension/MathJax/MathJaxMacro/#HUsage
mention	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Mentions%20Application/#HUsingtheSourceEditor
menu	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Menu%20Application#HUsage
notifications	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Notifications%20Macro/#HUsage
notificationsApplicationsPreferences	XS	? Mostly internal
notificationsAutoWatchPreferences	XS	? Mostly internal
notificationsCustomFiltersPreferences	XS	? Mostly internal
notificationsEmailPreferences	XS	? Mostly internal
notificationsFiltersPreferences	XS	? Mostly internal
notificationsSystemFiltersPreferences	XS	? Mostly internal
office	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Office%20Macro#HUsage
pdftoc	XS	https://github.com/xwiki/xwiki-platform/blob/769f06f65aaaa57b6614a818414629a0f35a64cf/xwiki-platform-core/xwiki-platform-export/xwiki-platform-export-pdf/xwiki-platform-export-pdf-api/src/main/java/org/xwiki/export/pdf/internal/macro/PDFTocMacro.java#L61 Internal? Not documented on https://extensions.xwiki.org/xwiki/bin/view/Extension/PDF%20Export%20Application/
plantuml	PlantUML Macro	https://extensions.xwiki.org/xwiki/bin/view/Extension/PlantUML%20Macro#HUsage
putFootnotes	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Footnote%20Macro#HUsage-1
python	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Python%20Macro#HUsage
reference	Reference Macro for the Numbered Content Applications	https://extensions.xwiki.org/xwiki/bin/view/Extension/Numbered%20Content/Reference/Macro/#HDescription
script	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Script%20Macro#HUsage
success	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Success%20Macro#HUsage
tableToChartJS	Chart.js Integration	https://extensions.xwiki.org/xwiki/bin/view/Extension/Chart.js%20Integration/#HUsage-1
tagcloud	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Tag%20Cloud%20Macro#HUsage
template	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Template%20Macro#HDescription
toc	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/TOC%20Macro#HFromWikiSyntax
translation	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Translation%20Macro#HUsage
tree	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Tree%20Macro#HWikiMacro
uiextension	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Extension%20Module/UI%20Extension%20Macro/#HUsage
uiextensions	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Extension%20Module/UI%20Extensions%20Macro/#HUsage
useravatar	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/User%20Avatar%20Macro#HUsage
velocity	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Velocity%20Macro#HUsage
warning	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Warning%20Macro#HUsage
wikimacrocontent	XS	https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/WritingMacros/WikiMacroTutorial/#HContent
wikimacroparameter	XS	https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/WritingMacros/WikiMacroTutorial/#HParameters
wikis	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Wiki%20Application#H22Wikis22Macro

There is 68 macros we want to analyse here.

Per macro analysis

Note that I've done most of the screenshots on a 2K screen. For the sake of brevity, when the extended dialog was over the size of the screen (and needed scrolling to see everything), I only provided what can be seen on my display without any scrolling or zooming. Note that in most use cases, users won't even be able to see that much at first emoticon_smile

async

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Async%20Macro/#HUsage

Parameters:

async WarningThe description of the parameter in the editor could be clearer on what happens when this is disabled.
cached
context ErrorThe description of the parameter in the editor must be made clearer. With the current one it's impossible to use the parameter without checking the external documentation.
id

Quick action? ✅

Just inserted screenshot:

When empty, this macro does not display anything in edit mode (except the box when hovering).

In edit mode, I'd have expected `macro:async` to show up.

Open the dialog with: popup under the macro.

The control pattern to open the dialog is fairly rare and we should probably make it easier.

Default dialog screenshot:

It doesn't make much sense to hide only the `id` parameter here.

The content of this macro cannot be edited in the edition dialog somehow. I'd have expected to be able to edit it from this dialog. This looks inconsistent. If technically not possible, it should be explained to the user to avoid providing an arbitrary inconsistency (looks like a bug).

Extended dialog screenshot:

attachmentGalleryPicker

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Attachment/Picker/Macro/

Parameters:

id
filter WarningThis parameter accepts lists, its picker should not be generic but help the user in figuring out how to convey multiple items.
limit
target

Quick action? ✅

Just inserted screenshot:

The user cannot interact with the search field, but can change the `current page`/`all pages` filter and pick an attachment.

We probably want to avoid this button interaction as it could lead to bugs. It should be disabled to make it clear that the macro is not functional in edit mode. (or make it completely functional)

Open the dialog with: double click anywhere on the macro.

Default dialog screenshot:

It doesn't make much sense to hide only the `target` parameter here.

Extended dialog screenshot:

attachmentSelector

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Attachment%20Application#HAttachmentSelector

Parameters:

classname
property
object WarningValidation should be done on this field to only allow numbers.
cssClass InformationGeneric style only parameter
savemode ErrorThis parameter accepts only a few defined values. The picker should not be generic text.
buttontext
defaultValue ErrorThis parameter expects an attachment reference, it should have a proper picker.
filter WarningThis parameter accepts lists, its picker should not be generic but help the user in figuring out how to convey multiple items.
displayImage
width InformationGeneric style only parameter
height InformationGeneric style only parameter
alternateText
link
targetdocname
versionSummary

15 parameters

FIXED: The documentation for these parameters does not use the standard table. Some info is missing from the documentation and can only be figured out by the user when trying things out...

Quick action? ✅

Just inserted screenshot:

Should check what are the most commonly used parameters. Does it make sense to only have `Object` in the collapsed view for non mandatory parameters?

No content in the page is created until the required parameters in the macro editor are filled up.

Open the dialog with: automatically done, focuses the first mandatory field.

Default dialog screenshot: See above

Extended dialog screenshot:

box

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Box%20Macro#HDescription

Parameters:

cssClass InformationGeneric style only parameter
title
image
width InformationGeneric style only parameter

The height generic style parameter is not here. Maybe it doesn't make sense here, but it should probably be added for consistency.

Quick action? ✅

Open the dialog with: Double click on the macro body

Respecting consistency, this macro's content should be inline editable.

Just inserted screenshot:

Default dialog screenshot:

Even if the content is not mandatory, it's really important for this macro and should be displayed by default, not hidden in the `more` section.

Extended dialog screenshot:

Note that it's a very common use case to just fill up some content and ignore the other parameters. When the content is filled up, it gets up the order in the dialog, which makes things easier later on. The default use case is really painful since there's at least 3 extra clicks that need to be done before being able to fill up content (compared to inline edition or having content as the first field).

cache

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Cache%20Macro

Parameters:

content
id
maxentries
timetolive

Quick action? ✅

Open the dialog with: Double click on the macro body.

For consistency, I'd have expected the macro parameters to open here, and start edition of the Content, since it's a required parameter. The macro body should not be created without a Content...
https://jira.xwiki.org/browse/XWIKI-21362

Just inserted screenshot:

The id of the macro flashed when inserting but ends up not being visible.

Default dialog screenshot:

Extended dialog screenshot:

chart

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Chart%20Macro#HUsage

Parameters:

type
content
height
params
source
title
width

6 parameters + content

Quick action? ✅

Open the dialog with: Automatically, focuses the required parameter `Type`.

Just inserted screenshot:

Default dialog screenshot: See above

Extended dialog screenshot:

chartjs

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Chart.js%20Integration/#HChartJSMacro

Parameters:

content
type ErrorThe type parameter should display a list of options to pick from.
options ErrorFor better usability, an actual link to the option details should be provided instead of `go see in docs`.
cssClass
title
id

Quick action? ✅

Open the dialog with: Automatically on macro creation, focuses the first required field.

Just inserted screenshot:

Default dialog screenshot: See above

Extended dialog screenshot:

children

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Children%20Macro/

Parameters:

- sort

Quick action? ✅

Open the dialog with: Double click on macro body

Double clicking anywhere in the page content will open the children macro parameters.

Just inserted screenshot:

Somehow the macro box covers the whole content.

Default dialog screenshot:

Extended dialog screenshot: NA

In order for this macro to be a bit more powerful, we'd want to add a parameter to allow picking the parent page (similar to the confluence bridge macro).

code

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Code%20Macro/

Parameters:

language
layout
source
(Box Macro parameters)

Quick action? ✅

Open the dialog with: Automatically on macro creation

There is no mandatory parameter. Automatic opening is usually reserved for macros with a mandatory param. This inconsistency looks arbitrary and is difficult to understand. I would have expected the macro to be created and have to double click its body before accessing parameters.

Just inserted screenshot:

Nothing is inserted in the content at first. When leaving the form empty, an empty code block is created, as expected

Default dialog screenshot: See above

Extended dialog screenshot:

comment

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Comment%20Macro

Parameters:

<None>

Quick action? ✅

Open the dialog with: Double click on macro body.

https://jira.xwiki.org/browse/XWIKI-21362

Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot: NA

container

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Container%20Macro

Parameters:

layoutStyle
justify

Quick action? ✅

Open the dialog with: Double click on macro body.

Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot:

content

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Content%20Macro#HUsage

Parameters:

syntax
source

Quick action? ✅

Open the dialog with: Dropdown appearing when editing the macro content

Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot:

For macros like this, it can be a bit difficult to select the macro in itself (ie. not its content field) in order to delete it. The easiest way I found to do it is to grab the handle on the left. IMO this is a bit awkward. Same problem with other macros that rely on the dropdown to access their parameters.

context

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Context%20Macro#HUsage

Parameters:

document
transformationContext
restricted
source

Quick action? ✅

Open the dialog with: Double click on the macro body.

Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot:

dashboard

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Dashboard%20Macro#HDescription

Parameters:

style
layout
source

Quick action? ✅

Open the dialog with: Double click on macro body.

Just inserted screenshot:

Even if the current user dashboard is empty, we expect some kind of visualization. When leaving the macro zone, it cannot be seen except by the small space left.

Default dialog screenshot:

Extended dialog screenshot: NA

display

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Display%20Macro#HFromWikiSyntax

Parameters:

page
referenceInformationFIXED: This parameter does not appear when editing the macro? Doc should be updated or there's something missing... Later note: there's a @PropertyDisplayHidden on the macro property, this is expected behaviour but doc should be updated.
type InformationFIXED: This parameter does not appear when editing the macro? Doc should be updated or there's something missing... Later note: there's a @PropertyDisplayHidden on the macro property, this is expected behaviour but doc should be updated.
section
excludeFirstHeading

Quick action? ✅

Open the dialog with: Double click on macro body.

Just inserted screenshot:

In theory, there's no "mandatory" parameter. In practice, there should be at least one parameter filled up. I would have expected the macro parameters to open up so I can set them in a proper way before the macro is even rendered first.

See https://jira.xwiki.org/browse/XWIKI-21362

Default dialog screenshot:

Extended dialog screenshot:

displayIcon

Doc:https://extensions.xwiki.org/xwiki/bin/view/Extension/Icon%20Macro/#HFromWikiSyntax

Parameters:

name
iconSet
fallback

Quick action? ✅

Open the dialog with: Automatically on macro creation

Just inserted screenshot:

Default dialog screenshot: See above

Extended dialog screenshot:

documents

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Documents%20Macro#HDescription

Parameters:

id
count
actions
space
parent
columns
location

FIXED: Parameter documentation should be updated to use a table, more consistent and clearer especially when there's a lot of params.

Quick action? ✅ WarningThe quickaction description does not mention document at all, but names them pages. Maybe we should add an alternative macro with the `pages` name.

Open the dialog with: Double click anywhere on the macro content

Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot:

documentTree

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Document%20Tree%20Macro#HWikiMacro

Parameters:

checkboxes
compact
exclusions
filterByClass
fiulterHiddenDocuments
finder
hierarchyMode
limit
links
openTo
readOnly
root
showAttachments
showChildDocuments
showClassProperties
showDocumentTitle
showObjects
showOnlyViewable
showRoot
showSpaces
showTranslations
showWikis
showWikiPrettyName
sortDocumentsBy

24 parameters total...

FIXED: Parameter documentation should be updated to the standard table, right now we're missing values like optional and allowed values.

Quick action? ✅ WarningThe quickaction description does not mention document at all, but names them pages. Maybe we should add an alternative macro with the `pages` name.

Open the dialog with:Double click anywhere on the macro body.

Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot:

error

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Error%20Macro#HUsage

Parameters:

cssClass
title
image
width

Quick action? ✅

Open the dialog with: Double click on main body (except content box).

Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot:

example

Doc:

NAN, no doc? https://www.xwiki.org/xwiki/bin/view/Help/Code/ExampleMacro#Information

or https://extensions.xwiki.org/xwiki/bin/view/Extension/Help%20Application#HAvailableMacros

which doesn't contain any reference to it...

No backlinks on https://dev.xwiki.org/xwiki/bin/view/Help/Code/ExampleMacro#Information either.

This macro is fairly difficult to find info about so I guess noone knows about it and barely noone uses it.

Parameters:

<None>

Quick action? ✅ WarningThis macro is most probably internal given the amount of documentation we have on it. It should not be exposed to the user: https://jira.xwiki.org/browse/XWIKI-21063

Open the dialog with: Double click anywhere on the macro body but the content box.

Just inserted screenshot:

Default dialog screenshot:

There is no way to edit the content field, even though content seems to be important for this macro.

Extended dialog screenshot: NA

faq

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/FAQ%20Application#HFAQMacro

Parameters:

filter

Quick action? ✅

Open the dialog with: Click anywhere oin the macro body.

Just inserted screenshot:

This recommended extension still uses a Live Table to display a list of entries. It should use liveData

Default dialog screenshot:

Extended dialog screenshot: NA

figure

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Figure/Figure%20Macro/#HUsage

Parameters:

type

Quick action? ✅

Open the dialog with: Click on the dropdown that appears when selecting the content.

Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot: NA

figureCaption

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Figure/Figure%20Macro/#HUsage

Parameters:

<None>

Quick action? ✅

Open the dialog with: Double click on the error message

Just inserted screenshot: Nothing to see in an empty figure macro or

Default dialog screenshot:

In a figure macro-->

Outside of a figure macro-->

This macro parameter dialog is inconsistent in an unexpected way when the context changes. Here, it should be the same or have an extra warning message on the top when the context is wrong...

Extended dialog screenshot: NA

figureTypeRecognizer

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Figure/Figure%20Macro/#HFigureTypeIdentification

Looks like it should be internal

Parameters:

<None> InformationIMPROVED: Unclear documentation for a macro users can easily access and use.

Quick action? ✅ , shown as internal WarningInternal use only macros should probably not even have a quick action since they are not meant to be used directly... They don't have the proper doc and will probably be very buggy in most conditions.

Open the dialog with: Double click on the macro body.

Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot: NA

footnote

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Footnote%20Macro#HUsage

Parameters:

<None>

Quick action? ✅

Open the dialog with: Double click on the macro body.

Just inserted screenshot:

The user should be informed when adding this macro also adds a putFootnote macro at the end of the document. This modification to the content is currently unnotified and can cause confusion down the line.

Default dialog screenshot:

Extended dialog screenshot: NA

gallery

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Gallery%20Macro#HUsage

Parameters:

class
height
width

Quick action? ✅

Open the dialog with: Double click anywhere on the macro body.

Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot:

gdprSettings

Doc: https://store.xwiki.com/xwiki/bin/view/Extension/GDPRCookieConsent/#documentation

Parameters:

? undocumented, but the macro looks kinda internal

Quick action? ✅

Open the dialog with:

Just inserted screenshot:

Default dialog screenshot:

The macro documentation is inneficient to understand the use of the macro and its parameters without checking the XWikiSyntaxMacrosList page...

It makes it more difficult to use.

Extended dialog screenshot: NA

groovy

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Groovy%20Macro#HUsage

Parameters:

output

Quick action? ✅

Open the dialog with: Double click on the macro body.

Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot:

html

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/HTML%20Macro#HUsage

Parameters:

wiki
clean

Quick action? ✅

Open the dialog with: Double click on the macro body.

Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot: NA

iconPicker

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Icon%20Theme%20Application#HIconPickerMacro

Parameters:

id
class
prefix

Parameter documentation should be updated to the standard table, right now we're missing values like optional and allowed values.

Quick action? ✅

Open the dialog with: Double click on the macro body

Just inserted screenshot:

Differently to all "empty by default" macros, this one does not take the whole line. It could be an improvement in consistency to make it fill the full line.

Default dialog screenshot:

Extended dialog screenshot: NA

id

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Id%20Macro#HUsage

Parameters:

name

Quick action? ✅

Open the dialog with: Automatically when creating the macro, prompting to get the required parameter filled up.

Just inserted screenshot:

Default dialog screenshot: See above

Extended dialog screenshot: NA

include

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Include%20Macro#HUsage

Parameters:

page
reference ErrorThis macro has technically no required parameters, but in application, the `reference` parameter is required. This inconsistency should be fixed. https://jira.xwiki.org/browse/XWIKI-20944
type
section
excludeFirstHeading
author
document (deprecated)
context (deprecated)

6 non deprecated parameters

Quick action? ✅

Open the dialog with: Automatically on macro creation.

Just inserted screenshot:

Without filling anything:

The usability of this macro seems to be good and this error message is displayed at an appropriate time.

Default dialog screenshot: See above

Extended dialog screenshot:

info

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Info%20Macro#HUsage

Parameters:

Message parameters

Quick action? ✅

Open the dialog with: Double click on the macro body.

Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot:

jira

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/JIRA/JIRA%20Macro#HUsage

Parameters:

id
url
source
style
fields
fieldNames (deprecated)
parameters
maxCount

8 parameters

Quick action? ✅

Open the dialog with: Double click on the macro body.

Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot:

jwplayer

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/JW%20Player%20Macro#HUsage

Parameters:

attachment ErrorIt's not easy to figure out from the doc that this is a mandatory parameter.
autostart
height
repeat
width

5 parameters

Quick action? ✅

Open the dialog with:

Just inserted screenshot:

Default dialog screenshot: See above

Extended dialog screenshot:

liveData

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Live%20Data%20Macro/#HUsage

Parameters:

id
properties
source
sourceParameters
filters
sort
limit
offset
layouts
showPageSizeDropdown
pageSizes
description

There's a total of 12 parameters for this macro.

Documentation of parameters do not contain clear info about the mandatory aspect of these parameters.

Quick action? ✅

Open the dialog with: Double click anywhere on the macro body.

Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot:

mathjax

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/MathJax/MathJaxMacro/#HUsage

Parameters:

<None> ?

Quick action? ✅ / ❌

Open the dialog with: Double click on the macro body.

Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot: NA

mention

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Mentions%20Application/#HUsingtheSourceEditor

Parameters:

reference
style
anchor
type

Quick action? ✅ (does not create a macro block, but puts the transformation pattern)

Open the dialog with: Double click on the macro body.

Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot:

notifications

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Notifications%20Macro/#HUsage

Parameters:

count
useUserPreferences
displayOwnEvents
displayMinorEvents
displaySystemEvents
displayReadEvents
displayReadStatus
wikis
spaces
pages
users
displayWatchedUsersOnly
displayRSSLink
tags

This macro has a total of 14 parameters.

Quick action? ✅

Open the dialog with: Double click anywhere on the macro body.

Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot:

notificationsApplicationsPreferences

This macro has poor documentation and seems to be mostly for internal use of XS. This is not a priority when it comes to edition usability.

Quick action? ✅

notificationsAutoWatchPreferences

This macro has poor documentation and seems to be mostly for internal use of XS. This is not a priority when it comes to edition usability.

Quick action? ✅

notificationsCustomFiltersPreferences

This macro has poor documentation and seems to be mostly for internal use of XS. This is not a priority when it comes to edition usability.

Quick action? ✅

notificationsEmailPreferences

This macro has poor documentation and seems to be mostly for internal use of XS. This is not a priority when it comes to edition usability.

Quick action? ✅

notificationsFiltersPreferences

This macro has poor documentation and seems to be mostly for internal use of XS. This is not a priority when it comes to edition usability.

notificationsSystemFiltersPreferences

This macro has poor documentation and seems to be mostly for internal use of XS. This is not a priority when it comes to edition usability.

Quick action? ✅

office

FORGOT IT IN THE INITIAL LIST....

TODO: search for info about this macro...

pdftoc

Doc: https://github.com/xwiki/xwiki-platform/blob/769f06f65aaaa57b6614a818414629a0f35a64cf/xwiki-platform-core/xwiki-platform-export/xwiki-platform-export-pdf/xwiki-platform-export-pdf-api/src/main/java/org/xwiki/export/pdf/internal/macro/PDFTocMacro.java#L61 Internal? Not documented on https://extensions.xwiki.org/xwiki/bin/view/Extension/PDF%20Export%20Application/

Parameters:

jobid
depth

Those parameters are not documented as far as I could see. Create or move documentation (if anything is found after further investigation...)

Quick action? ✅

Open the dialog with: Automatically, ready to edit the mandatory field.

Just inserted screenshot:

Default dialog screenshot: See above

Extended dialog screenshot: NA

plantuml

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/PlantUML%20Macro#HUsage

Parameters:

server ErrorNon standard parameter documentation, add a table to make it easy to spot.
title ErrorMissing in the documentation...
type ErrorMissing in the documentation... But probably doesn't make sense on this macro, see warning below.

Quick action? ✅ (with extension installed)

Contrary to all the other Recommended macros I could find so far, this one did not have a quick action by default that would allow the admin to quickly install it. This is inconsistent with other Recommended macros and should be addressed.

Note that I doubt this rule has been documented. Need to check and make sure this requirement is written down explicitely in some doc about recommended extensions.

Open the dialog with: Double click on the macro body.

Just inserted screenshot:

This macro has mandatory content. It would be good for usability to have it editable inline.

Default dialog screenshot:

Extended dialog screenshot:

Is it really wise to let the users change the type of the macro here. Shouldn't we just have a diagram macro that supports this?

putFootnotes

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Footnote%20Macro#HUsage-1

Parameters:

<None>

Quick action? ✅

Open the dialog with: Double click on the macro body.

Just inserted screenshot:

This macro disappears instantly when trying to add it? Fails with and without a footnote, only if there's already a putFootnote. I'd have expected the macro to move the "old" one at the place the user asked it at instead of completely ignoring the user request. At least, for usability, explain the issue in a xwiki alarm.

2025-02-17 15-27-25.mp4

Default dialog screenshot:

Extended dialog screenshot: NA

python

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Python%20Macro#HUsage
Parameters: script macro parameters minus language

output
wiki
jars

Quick action? ✅
Open the dialog with: Double click on the macro body.
Just inserted screenshot:

For a couple seconds, the macro looks empty, with only `macro:python`, then the message is displayed:

ErrorThe empty macro should not create an error. By default, we should probably prefill the macro with basic python that is rendered into something okayish and maybe even informative.
Default dialog screenshot:

Extended dialog screenshot:

reference

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Numbered%20Content/Reference/Macro/#HDescription
Parameters:

id
figure (deprecated)
section (deprecated)
type (deprecated)

WarningIn the macro parameter table, the `Optional` values are set as false/true instead of yes/no like in other docs. We probably want to align this to the standard.
Quick action? ✅ (with extension installed)

Note that I doubt this rule has been documented. Need to check and make sure this requirement is written down explicitely in some doc about recommended extensions.

Open the dialog with: Double click on the macro body.
Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot:

script

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Script%20Macro#HUsage

Parameters:

language
output
wiki
jars

Quick action? ✅

Open the dialog with: Double click on the macro body.

Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot:

success

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Success%20Macro#HUsage

Parameters:

Message parameters

Quick action? ✅

Open the dialog with: Double click on the macro body (except content).

Just inserted screenshot:

Default dialog screenshot: Same as info

Extended dialog screenshot: Same as info

tableToChartJS

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Chart.js%20Integration/#HUsage-1

Parameters:

type
title
id
multipleDataSets
table
dataSetLabel
options
width
height
cssClass

This macro supports 10 parameters

Quick action? ✅

Contrary to some of the other Recommended macros I could find so far, this one did not have a quick action by default that would allow the admin to quickly install its extension. This is inconsistent with other Recommended macros and should be addressed.

Note that I doubt this rule has been documented. Need to check and make sure this requirement is written down explicitely in some doc about recommended extensions.

Open the dialog with: Automatically on macro creation

Just inserted screenshot:

Default dialog screenshot: See above

Extended dialog screenshot:

template

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Template%20Macro#HDescription

Parameters:

name
output

Quick action? ✅

Open the dialog with: Double click on the macro body.

Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot: NA

translation

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Translation%20Macro#HUsage

Parameters:

key
parameters
locale

Quick action? ✅

Open the dialog with: Automatically on macro creation.

Just inserted screenshot:

Default dialog screenshot: See above.

Extended dialog screenshot:

tree

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Tree%20Macro#HWikiMacro

Parameters:

checkboxes
class
contextMenu
dragAndDrop
edges
finder
icons
limit
links
openTo
reference
root
showRoot

The table to document these parameters does not give any info on whether they are required or not. A column should be added to align this to the standard of macro parameter documentation.

Quick action? ✅

Open the dialog with: Double click on the macro body.

Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot:

uiextension

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Extension%20Module/UI%20Extension%20Macro/#HUsage

Parameters:

Quick action? ✅

Open the dialog with: Automatically on macro creation

Just inserted screenshot:

Default dialog screenshot: See above

Extended dialog screenshot: NA

uiextensions

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Extension%20Module/UI%20Extensions%20Macro/#HUsage

Parameters:

extensionPoint

Quick action? ✅

Open the dialog with: Automatically on macro creation

Just inserted screenshot:

The description of the field contains unwanted javadoc. A translation value should be used to avoid relying on this javadoc...

Default dialog screenshot: See above

Extended dialog screenshot: NA

useravatar

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/User%20Avatar%20Macro#HUsage

Parameters:

username
width
height

Quick action? ✅

Open the dialog with: Automatically on macro creation

Just inserted screenshot:

The avatar should use a standard size by default. For any list it makes things way easier to use. In the example below, the Admin user and a random user avatars. They do not have anything close to a similar format:

Default dialog screenshot: See above.

Extended dialog screenshot: NA

velocity

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Velocity%20Macro#HUsage

Parameters:

filter
output
wiki
jars

Quick action? ✅

Open the dialog with: Double click on the macro body.

Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot:

warning

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Warning%20Macro#HUsage

Parameters:

Message parameters

Quick action? ✅

Open the dialog with: Double click on the macro body (excluding content).

Just inserted screenshot:

Default dialog screenshot: Same as info...

Extended dialog screenshot: Same as info...

wikimacrocontent

Doc: https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/WritingMacros/WikiMacroTutorial/#HContent

Parameters:

<None>?

Quick action? ✅ WarningThis should probably only appear in quick actions in places where it makes sense. For most use cases it won't be any use...

Open the dialog with: Double click on macro body.

Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot: NA

wikimacroparameter

Doc: https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/WritingMacros/WikiMacroTutorial/#HParameters

Parameters:

name
content

Documentation of those parameters is non standard and possibly confusing.

Quick action? ✅ WarningThis should probably only appear in quick actions in places where it makes sense. For most use cases it won't be any use...

Open the dialog with: Automatically on macro creation.

Just inserted screenshot:

Default dialog screenshot: See above.

Extended dialog screenshot: NA

wikis

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Wiki%20Application#H22Wikis22Macro

Parameters:

<None>

Quick action? ✅

Open the dialog with: Double click on the macro body.

Just inserted screenshot:

This macro still uses Silk icons. They are probably hard coded and should be replaced with a call to the icon provider.

Default dialog screenshot:

Extended dialog screenshot: NA

List of macros with their corresponding Jira issues

When looking for existing jira issues, I filtered on only open issues, related to the macro usability in CKEditor and in the xwiki-platform, xwiki-rendering or their extension's projects. In order to find the issues to go through, I'd either string search its id, or select its component if there's one.

Id of the macro	From project	Existing jira issues
async	XS
attachmentGalleryPicker	XS	None
attachmentSelector	XS
box	XS	?
cache	XS	None
chart	XS
chartjs	Chart.js Integration
children	XS	None
code	XS
comment	XS
container	XS
content	XS
context	XS
dashboard	XS
display	XS
displayIcon	XS
documents	XS
documentTree	XS
error	XS
example	XS
faq	FAQ Application
figure	Figure Macro
figureCaption	Figure Macro
figureTypeRecognizer	Figure Macro
footnote	XS
gallery	XS
gdprSettings	GDPR Cookie Consent
groovy	XS
html	XS
iconPicker	XS
id	XS
include	XS
info	XS
jira	JIRA Macro
jwplayer	JW Player Macro
liveData	XS
mathjax	Mathjax Macro
mention	XS
menu	XS
notifications	XS
notificationsApplicationsPreferences	XS
notificationsAutoWatchPreferences	XS
notificationsCustomFiltersPreferences	XS
notificationsEmailPreferences	XS
notificationsFiltersPreferences	XS
notificationsSystemFiltersPreferences	XS
office	XS
pdftoc	XS
plantuml	PlantUML Macro
putFootnotes	XS
python	XS
reference	Reference Macro for the Numbered Content Applications
script	XS
success	XS
tableToChartJS	Chart.js Integration
tagcloud	XS
template	XS
toc	XS
translation	XS
tree	XS
uiextension	XS
uiextensions	XS
useravatar	XS
velocity	XS
warning	XS
wikimacrocontent	XS
wikimacroparameter	XS
wikis	XS

Generic macro issues

Consistency comparison

Hints for boolean parameters
- Enable or disable : async
Control pattern for opening the edit dialog
- Double click on the macro body (excluding the content box): (default)
- Click on the dropdown appearing when focusing the macro: async
Generic style only parameters
- width: attachmentSelector, box,
- height: attachmentSelector
- cssClass: attachmentSelectorm, box,
.

Misc research

A list of research bits I gathered that ended up not being useful.

Blog macros

blogpostcreate

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Blog%20Application#HBlogPostCreateMacro

Parameters:

blog

Documentation of parameters is insufficient.

Quick action? ✅

Open the dialog with: Double click on the macro body.

Just inserted screenshot:

Default dialog screenshot:

Note that I wouldn't expect this macro to support any kind of content.

Once confirmed, remove the Content field from this edition dialog. It is not used by the macro and should not be editable. It's just confusing.

Extended dialog screenshot: NA

blogPostLayoutCards

Doc: https://extensions.xwiki.org/xwiki/bin/view/Extension/Blog%20Application#HCardspostlayout

Parameters:

reference
params

Quick action? ✅

Note that the naming pattern for the quick action of this macro is different from those of other layout macros:

Open the dialog with: Opened from the start, does not create anything unless the mandatory param is filled up.

Just inserted screenshot:

Once confirmed, remove the Content field from this edition dialog. It is not used by the macro and should not be editable. It's just confusing.

The `params` parameter should be replaced by actual parameters.

Default dialog screenshot:See above

Extended dialog screenshot: NA

Parameters:

blog ErrorThis parameter expects a document reference. It should not have a standard String picker but a document picker.
category
published
hidden
fromDateErrorThis parameter expects a date. It should not have a standard String picker but a date picker.
toDate ErrorThis parameter expects a date. It should not have a standard String picker but a date picker.
limit WarningThe input for this parameter should be checked to make sure it's a number and not just any string.
layout
layoutParamsWarningThe `params` parameter should be replaced by actual parameters.
paginated ErrorThis parameter expects a boolean. It should not have a standard String picker but a boolean picker.

10 parameters

Quick action? ✅

Open the dialog with: Double click on the whole body of the macro.

Just inserted screenshot:

Default dialog screenshot:

Since the macro cannot work without at least one of blog or category to be filled up, I'd expect its editor to open on creation (like it's done when there's at least one mandatory parameter).

Extended dialog screenshot:

blogs

Doc: NA

Parameters:

<None>

Quick action? ✅

Open the dialog with: Double click anywhere on the macro body.

Just inserted screenshot:

Default dialog screenshot:

Extended dialog screenshot: NA

Id of the macro	From project	Searching jira query	Existing jira issues
blogpostcreate	Blog Application	https://jira.xwiki.org/browse/BLOG-172?jql=project%20%3D%20BLOG%20AND%20status%20%3D%20Open%20AND%20text%20~%20%22create%22	None
blogPostLayoutCards	Blog Application	previous blog queries + https://jira.xwiki.org/browse/BLOG-144?jql=project%20%3D%20BLOG%20AND%20status%20%3D%20Open%20AND%20text%20~%20%22layout%22	https://jira.xwiki.org/browse/BLOG-121
blogPostLayoutCompact	Blog Application	previous blog queries	https://jira.xwiki.org/browse/BLOG-144 https://jira.xwiki.org/browse/BLOG-121
blogPostLayoutFull	Blog Application	previous blog queries	https://jira.xwiki.org/browse/BLOG-121
blogPostLayoutImage	Blog Application	previous blog queries	https://jira.xwiki.org/browse/BLOG-222 https://jira.xwiki.org/browse/BLOG-121
blogPostLayoutLink	Blog Application	previous blog queries	https://jira.xwiki.org/browse/BLOG-121
blogpostlist	Blog Application	previous blog queries + https://jira.xwiki.org/browse/BLOG-224?jql=project%20%3D%20BLOG%20AND%20status%20%3D%20Open%20AND%20text%20~%20%22blogpostlist%22	https://jira.xwiki.org/browse/BLOG-194 https://jira.xwiki.org/browse/BLOG-200 https://jira.xwiki.org/browse/BLOG-192 https://jira.xwiki.org/browse/BLOG-180 ??? https://jira.xwiki.org/browse/BLOG-224
blogs	Blog Application	previous blog queries	None

Full list of macros

This list was taken from an instance where I tried to install all recommended macros but the ones that are pro. As you can see, there's still quite a lot of pro and non recommended macros in this list. This list was filled up on the 10th of February.

Id of the macro	From project	Macro doc URL	Priority	Reason for priority
activity	XS - Legacy	https://extensions.xwiki.org/xwiki/bin/view/Extension/Legacy%20Notification%20Activity%20Macro/	Very low	Legacy, replaced by the Notifications macro
async	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Async%20Macro/
attachmentGalleryPicker	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Attachment/Picker/Macro/
attachmentSelector	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Attachment%20Application#HAttachmentSelector
awmkanban	Kanban macro	https://extensions.xwiki.org/xwiki/bin/view/Extension/Kanban%20Macro/#HKanbanfromAppWithinMinutes		Kanban macro itself is not recommended, but it's need for Task Manager App (Pro).
blogpostcreate	Blog Application	https://extensions.xwiki.org/xwiki/bin/view/Extension/Blog%20Application#HBlogPostCreateMacro
blogPostLayoutCards	Blog Application	https://extensions.xwiki.org/xwiki/bin/view/Extension/Blog%20Application#HCardspostlayout
blogPostLayoutCompact	Blog Application	https://extensions.xwiki.org/xwiki/bin/view/Extension/Blog%20Application#HHowtoconfigureanewblogpostlayout3F
blogPostLayoutFull	Blog Application	https://extensions.xwiki.org/xwiki/bin/view/Extension/Blog%20Application#HHowtoconfigureanewblogpostlayout3F
blogPostLayoutImage	Blog Application	https://extensions.xwiki.org/xwiki/bin/view/Extension/Blog%20Application#HHowtoconfigureanewblogpostlayout3F
blogPostLayoutLink	Blog Application	https://extensions.xwiki.org/xwiki/bin/view/Extension/Blog%20Application#HHowtoconfigureanewblogpostlayout3F
blogpostlist	Blog Application	https://extensions.xwiki.org/xwiki/bin/view/Extension/Blog%20Application#HBlogPostListMacro
blogs	Blog Application	???		No doc but with the description provided in the macro list, it's quite straightforward to use.
box	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Box%20Macro#HDescription
button	ProMacros	https://store.xwiki.com/xwiki/bin/view/Extension/ProMacros/#HButton
cache	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Cache%20Macro
calendar	Full Calendar App	https://extensions.xwiki.org/xwiki/bin/view/Extension/FullCalendar%20Application#HDescription	Zero	From the full calendar application, which is not recommended itself, but needed by the Holiday Request extension. Not recommended either...
chart	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Chart%20Macro#HUsage
chartjs	Chart.js Integration	https://extensions.xwiki.org/xwiki/bin/view/Extension/Chart.js%20Integration/#HChartJSMacro
children	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Children%20Macro/
code	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Code%20Macro/
comment	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Comment%20Macro
confluence_attachments	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_children	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_column	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_contentbylabel	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_details	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_detailssummary	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_drawio	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354Bridges are not supposed to be created or edited manually.
confluence_float	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_gallery	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_gliffy	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_htmlcomment	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_layout	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_layout-cell	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_layout-section	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_mathblock	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_mathblock-ref	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_mathinline	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_mockup	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_multimedia	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_note	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_outgoing-links	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_pagetree	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_paste-code-macro	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_section	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_time	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_tip	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_toc-zone	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
confluence_wireframe	Pro Macros - Confluence bridges		Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
container	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Container%20Macro
content	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Content%20Macro#HUsage
content-report-table	Pro Macros	https://store.xwiki.com/xwiki/bin/view/Extension/ProMacros/#HContentReportTable
context	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Context%20Macro#HUsage
contributors	Pro Macros - Confluence bridges	https://store.xwiki.com/xwiki/bin/view/Extension/ProMacros/#HContributors	Very low	Bridges are not supposed to be created or edited manually. Usability improvements on this is hardly worth anything. https://github.com/xwikisas/xwiki-pro-macros/issues/354
dashboard	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Dashboard%20Macro#HDescription
date	Task Manager Application (Pro)	https://store.xwiki.com/xwiki/bin/view/Extension/TaskApplication#HDate
diagram	Diagram App	https://extensions.xwiki.org/xwiki/bin/view/Extension/Diagram%20Application#HDescription		Only pro version of the app is recommended.
display	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Display%20Macro#HFromWikiSyntax
displayIcon	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Icon%20Macro/#HFromWikiSyntax
documents	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Documents%20Macro#HDescription
documentTree	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Document%20Tree%20Macro#HWikiMacro
error	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Error%20Macro#HUsage
example	XS	NAN, no doc? https://www.xwiki.org/xwiki/bin/view/Help/Code/ExampleMacro#Information or https://extensions.xwiki.org/xwiki/bin/view/Extension/Help%20Application#HAvailableMacros which doesn't contain any reference to it... No backlinks on https://dev.xwiki.org/xwiki/bin/view/Help/Code/ExampleMacro#Information either.	Low	This macro is fairly difficult to find info about so I guess noone knows about it and barely noone uses it.
excerpt	Pro Macros	https://store.xwiki.com/xwiki/bin/view/Extension/ProMacros/#HExcerpt
excerpt-include	Pro Macros	https://store.xwiki.com/xwiki/bin/view/Extension/ProMacros/#HExcerptInclude
expand	Pro Macros	https://store.xwiki.com/xwiki/bin/view/Extension/ProMacros/#HExpand
faq	FAQ Application	https://extensions.xwiki.org/xwiki/bin/view/Extension/FAQ%20Application#HFAQMacro
figure	Figure Macro	https://extensions.xwiki.org/xwiki/bin/view/Extension/Figure/Figure%20Macro/#HUsage
figureCaption	Figure Macro	https://extensions.xwiki.org/xwiki/bin/view/Extension/Figure/Figure%20Macro/#HUsage
figureTypeRecognizer	Figure Macro	https://extensions.xwiki.org/xwiki/bin/view/Extension/Figure/Figure%20Macro/#HFigureTypeIdentification (internal macro)
footnote	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Footnote%20Macro#HUsage
gallery	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Gallery%20Macro#HUsage
gdprSettings	GDPR Cookie Consent	https://store.xwiki.com/xwiki/bin/view/Extension/GDPRCookieConsent/#documentation		store page only but LGPL 2.1 and no licences
groovy	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Groovy%20Macro#HUsage
hide-if	Pro Macros - Confluence bridges	https://github.com/xwikisas/xwiki-pro-macros/issues/336
holidayRequests	Holiday Request	https://extensions.xwiki.org/xwiki/bin/view/Extension/Holiday%20Request		Non recommended, looks like internal macros anyways
hrcalendar	Holiday Request	https://extensions.xwiki.org/xwiki/bin/view/Extension/Holiday%20Request		Non recommended, looks like internal macros anyways
html	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/HTML%20Macro#HUsage
iconPicker	XS	https://www.xwiki.org/xwiki/bin/view/IconThemesCode/IconPickerMacro https://extensions.xwiki.org/xwiki/bin/view/Extension/Icon%20Theme%20Application#HIconPickerMacro
id	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Id%20Macro#HUsage
include	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Include%20Macro#HUsage
info	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Info%20Macro#HUsage
jira	JIRA Macro	https://extensions.xwiki.org/xwiki/bin/view/Extension/JIRA/JIRA%20Macro#HUsage		Recommended
jwplayer	JW Player Macro	https://extensions.xwiki.org/xwiki/bin/view/Extension/JW%20Player%20Macro#HUsage		Recommended
kanban	Kanban macro	https://extensions.xwiki.org/xwiki/bin/view/Extension/Kanban%20Macro/#HKanbanfromJSON		Not recommended
kanbanboard	Task Manager Application	https://extensions.xwiki.org/xwiki/bin/view/Extension/Task%20Manager%20Application#HKanbanBoard		Not recommended
liveData	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Live%20Data%20Macro/#HUsage
locationSearch	Location Search Macro	https://extensions.xwiki.org/xwiki/bin/view/Extension/Location%20Search%20Macro/#HDescription		Not recommended
mathjax	Mathjax Macro	https://extensions.xwiki.org/xwiki/bin/view/Extension/MathJax/MathJaxMacro/#HUsage		Recommended
mention	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Mentions%20Application/#HUsingtheSourceEditor
menu	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Menu%20Application#HUsage
missingLicenseMessage	Pro macros	?
msStream	Pro Macros	https://store.xwiki.com/xwiki/bin/view/Extension/ProMacros/#HMicrosoftStream
notifications	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Notifications%20Macro/#HUsage
notificationsApplicationsPreferences	XS	?		Mostly internal
notificationsAutoWatchPreferences	XS	?		Mostly internal
notificationsCustomFiltersPreferences	XS	?		Mostly internal
notificationsEmailPreferences	XS	?		Mostly internal
notificationsFiltersPreferences	XS	?		Mostly internal
notificationsSystemFiltersPreferences	XS	?		Mostly internal
office	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Office%20Macro#HUsage		Not recommended
panel	Pro Macros	https://store.xwiki.com/xwiki/bin/view/Extension/ProMacros/#HPanel
pdftoc	XS	https://github.com/xwiki/xwiki-platform/blob/769f06f65aaaa57b6614a818414629a0f35a64cf/xwiki-platform-core/xwiki-platform-export/xwiki-platform-export-pdf/xwiki-platform-export-pdf-api/src/main/java/org/xwiki/export/pdf/internal/macro/PDFTocMacro.java#L61		Internal? Not documented on https://extensions.xwiki.org/xwiki/bin/view/Extension/PDF%20Export%20Application/
pdfviewer	PDF Viewer Macro	https://extensions.xwiki.org/xwiki/bin/view/Extension/PDF%20Viewer%20Macro		Not recommended (pro version is)
plantuml	PlantUML Macro	https://extensions.xwiki.org/xwiki/bin/view/Extension/PlantUML%20Macro#HUsage		Recommended
profile-picture	Pro Macros	https://store.xwiki.com/xwiki/bin/view/Extension/ProMacros/#HProfilePicture
putFootnotes	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Footnote%20Macro#HUsage-1
python	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Python%20Macro#HUsage
recently-updated	Pro Macros	https://store.xwiki.com/xwiki/bin/view/Extension/ProMacros/#HRecentlyUpdated
reference	Reference Macro for the Numbered Content Applications	https://extensions.xwiki.org/xwiki/bin/view/Extension/Numbered%20Content/Reference/Macro/#HDescription		Recommended (clashes with other macro definition from https://extensions.xwiki.org/xwiki/bin/view/Extension/References#HUsage )
script	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Script%20Macro#HUsage
show-if	Pro Macros - Confluence bridges	https://github.com/xwikisas/xwiki-pro-macros/issues/336
status	Pro Macros	https://store.xwiki.com/xwiki/bin/view/Extension/ProMacros/#HStatus
success	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Success%20Macro#HUsage
tab	Pro Macros	https://github.com/xwikisas/xwiki-pro-macros/pull/353		Confluence bridge? Looks a bit like it
tab-group	Pro macros	https://github.com/xwikisas/xwiki-pro-macros/pull/353		Confluence bridge? Looks a bit like it
tableToChartJS	Chart.js Integration	https://extensions.xwiki.org/xwiki/bin/view/Extension/Chart.js%20Integration/#HUsage-1		Recommended
tagcloud	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Tag%20Cloud%20Macro#HUsage
tagList	Pro Macros	https://store.xwiki.com/xwiki/bin/view/Extension/ProMacros/#HTaglist
task	Task Manager Application (Pro)	https://store.xwiki.com/xwiki/bin/view/Extension/TaskApplication#HTaskmacro
task-report	Task Manager Application (Pro)	https://store.xwiki.com/xwiki/bin/view/Extension/TaskApplication#HTaskReportmacro
taskcard	Task Manager Application (Pro)	https://store.xwiki.com/xwiki/bin/view/Extension/TaskApplication#HTaskcard
taskgantt	Task Manager Application (Pro)	None, maybe internal? Can see it in the source: https://github.com/search?q=repo%3Axwikisas%2Fapplication-task%20taskgantt&type=code
tasks	Task Manager Application (Pro)	https://store.xwiki.com/xwiki/bin/view/Extension/TaskApplication#HTasksmacro28list29
tasks-report-macro	Pro Macros - Confluence bridges	https://github.com/xwikisas/application-task/blob/5f5717d4b0d74baa59cdb9297a160415039bfe3a/application-task-ui/src/main/resources/TaskManager/ConfluenceTasksReportMacroBridge.xml#L346
team	Pro Macros	https://store.xwiki.com/xwiki/bin/view/Extension/ProMacros/#HTeam
template	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Template%20Macro#HDescription
toc	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/TOC%20Macro#HFromWikiSyntax
translation	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Translation%20Macro#HUsage
tree	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Tree%20Macro#HWikiMacro
uiextension	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Extension%20Module/UI%20Extension%20Macro/#HUsage
uiextensions	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Extension%20Module/UI%20Extensions%20Macro/#HUsage
useravatar	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/User%20Avatar%20Macro#HUsage
userList	Pro Macros	https://store.xwiki.com/xwiki/bin/view/Extension/ProMacros/#HUserList
userProfile	Pro Macros	https://store.xwiki.com/xwiki/bin/view/Extension/ProMacros/#HUserProfile
velocity	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Velocity%20Macro#HUsage
view-file	Pro Macros	https://store.xwiki.com/xwiki/bin/view/Extension/ProMacros/#HViewFile
warning	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Warning%20Macro#HUsage
wikimacrocontent	XS	https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/WritingMacros/WikiMacroTutorial/#HContent
wikimacroparameter	XS	https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/WritingMacros/WikiMacroTutorial/#HParameters
wikis	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Wiki%20Application#H22Wikis22Macro
workspaces	XS	https://extensions.xwiki.org/xwiki/bin/view/Extension/Workspace%20Application#HDescription ?	Zero	deprecated macro for a long time...

WYSIWYG Usability of XWiki macros

Description

List of XS + recommended (non pro) macros

Per macro analysis

async

attachmentGalleryPicker

attachmentSelector

box

cache

chart

chartjs

children

code

comment

container

content

context

dashboard

display

displayIcon

documents

documentTree

error

example

faq

figure

figureCaption

figureTypeRecognizer

footnote

gallery

gdprSettings

groovy

html

iconPicker

id

include

info

jira

jwplayer

liveData

mathjax

mention

menu

notifications

notificationsApplicationsPreferences

notificationsAutoWatchPreferences

notificationsCustomFiltersPreferences

notificationsEmailPreferences

notificationsFiltersPreferences

notificationsSystemFiltersPreferences

office

pdftoc

plantuml

putFootnotes

python

reference

script

success

tableToChartJS

tagcloud

template

toc

translation

tree

uiextension

uiextensions

useravatar

velocity

warning

wikimacrocontent

wikimacroparameter

wikis

List of macros with their corresponding Jira issues

Generic macro issues

Consistency comparison

Misc research

Blog macros

blogpostcreate

blogPostLayoutCards

blogPostLayoutCompact