What is User Macro in Confluence?

Users Macros in Confluence are custom macros that are meant to improve user experience and enhance productivity without having to build a separate full-fledged app.

💡 Use cases for user macros include, but are not limited to, the following:

• Rendering text content that can be styled

• Gathering and rendering Confluence content information about pages, spaces, labels, users, etc.

• Finding and displaying specific filtered content

• Pulling and displaying data from Jira & other third-party APIs

• Showing or hiding content based on user access rights and permissions

User Macros in Confluence Server and Data Center:

How to Create User Macros in Confluence Server and Data Center:

Here are the steps to create user macros in Confluence Server and Data Center:

1. Go to the Administration menu, then General Configuration > User Macros.

2. Click Create a User Macro.

3. Fill in the macro details, including macro name, visibility, macro title, description, etc.

4. Click Save.

Example of Confluence Server / Data Center User Macro:

• Let's say you want to create a simple user macro that will output a custom message. Something like this could be the template of the macro:

## Macro title: Custom Message
## Macro has a body: N
##
## @param Message:title=Message|type=string|required=true|desc=The message to display

<p>$paramMessage</p>

• Once saved, the macro will be available in the Confluence Administration panel where you can manage it (edit or delete):

• Now that you are done with the previous steps, you can add the user macro to a page via / or the editor toolbar where you need to select Insert, then Other Macros, and find your user macro:

• After that, enter any required parameters, click Update, and see the user macro rendered on the page:

More details and examples for basic macros are available in the Confluence official documentation.

Also, advanced user macros using multiple parameters and conditional content can be created to extend the base functionality of Confluence.

More details and examples for advanced macros are available in the Confluence official documentation.

User Macros in Confluence Cloud:

Confluence Cloud does not support user macros in the traditional way as seen in Server and Data Center platforms.

However, you can use a marketplace app — User Macro for Confluence Cloud — to create and manage custom user macros.

The following page gives an overview of the differences between Data Center and Cloud approaches. Please follow this page to migrate user macros from the on-premise to the Cloud. Detailed information on how to create user macros in Confluence Cloud is available at Step-by-Step: User macro creation.