Step-by-Step: User macro creation
To register new macros, users can copy ready-to-use macro templates from the Library, Import them, or create custom macros from scratch.
In this guide, we will learn how to write your own macro in confluence.
Prerequirements
First of all the process requires Confluence Cloud 
. Even the free tier is ok.
Secondly, installed User Macro for Confluence Cloud. For this (and further) steps Admin permission will be needed.
Note that the app is free for 10 or less users. For those who have more users, the app proposes a trial period.
Create and configure User Macro
Create a User Macro
Go to the Apps → Manage apps
From there you can click on
Settings → Data Management → User Macros
Apps → Manage apps → Take me there (to Administration) → Get Started (three-dot button)
This way, you’ll be redirected to the administration page with the format:
https://{yourDomain}.atlassian.net/wiki/plugins/servlet/ac/user-macro-confluence-cloud/main
Click on Create Macro
Configure Macro
On the Settings tab, you can choose the following properties:
Name* (required) — this is how users will see and search your macro.
Key (required and autogenerated) — would be a unique identifier for your Confluence macro.
Categories (multiple select) — categories used to group entries in the macro browser.
Documentation* (required and predefined) — will be shown to users on the edit macro panel. Creating a dedicated page on how to use this exact macro is recommended.
Description* (required) — a short descriptive message that will be shown in the macro browser.
Color (one of six predefined) — macro icon will be generated from the first letter of the name with the chosen background color.
Macro type (default: dynamic) — dynamic works in iFrames, loads slower, and gives you more possibilities. Static macros have more limitations but load faster. See more in static vs dynamic macro and choose wisely.
Body type (default: none) — Rich text is allowed for both static and dynamic macros. Gives access to the macro body (
{"timestamp":1792798088579,"msg":"A unknown Exception Occurred","errorMsg":"The provided AtlassianHostUser did not specify a user to act as.","code":"500"}$body) and allows nested macros rendering. See more in none vs rich text macro.Output type (default: block) — See more in block vs inline macro.
Hidden (default: false) — if the macro is hidden it will keep working, however not shown in the macro browser. See more in macro visibility.
For the first fast try, only the Name and Description fields are needed.
Write Macro
After configuration go to the Template tab. This is where macro code will be written.
The Template field includes velocity template macro code. Let’s leave it as it is with the following placeholder:
<b>Hello $user.publicName</b>
It will be rendered as a bold greeting of the current user.
To write advanced user macros please take a look at velocity-related pages or take a look into one of our macro from the library.
There you will also find Variables block (context parameters and /wiki/spaces/UM/pages/322961409), and embedded documentation of different helpers.
Click on the Create button (ctrl+s or cmd+s also will work).
View Macro in action
Open any confluence page and add your macro from the Macro Browser.
Or directly from the page using / shortcut
{"timestamp":1792798088595,"msg":"A unknown Exception Occurred","errorMsg":"The provided AtlassianHostUser did not specify a user to act as.","code":"500"}Edit page view:
Save the page and you will see the rendered greeting:
Edit User Macro
To edit your macro please go back to the User Macros page, and click on the macro name.
You will see the Template tab and can make changes to it, after saving changes will be shown on the page.
You can also select the Settings tab and change some of the fields.
Please note that Key, Macro Type, Body Type, and Output type are not changeable because Confluence does not provide stable behavior on changing such properties.
