Writing User Macros
User macros are useful if you want to create your own custom macros. These can be to perform specific actions, apply custom formatting and much more.
User macros are created and managed within Confluence itself, you do not need to develop an app (plugin). You will need some coding skills though.
You'll need System Administrator permissions to create and manage user macros.
Create a User Macro
To add a new user macro:
- Go to Administration
> General Configuration > User Macros. - Select Create a User Macro.
- Enter the macro details (see table below).
- Select Add.
| Macro details field | Description |
|---|---|
| Macro name | This is the name of the macro, as it appears in the code. |
Visibility | This controls who can see this macro in the macro browser or auto-complete. Options are:
Note that if you select Visible only to system administrators, users will still see the output of the macro on a page, and the macro placeholder will still be visible when a user edits a page. It is only hidden in the macro browser and autocomplete. All macro information is discoverable, including the macro title, description, parameter names and other metadata. Do not include confidential data anywhere in the definition of a user macro, even if it is marked as visible only to system administrators. |
| Macro Title | This is the title that will appear in the macro browser and auto-complete. |
| Description | This is the description that will appear in the macro browser. The macro browser's search will pick up matches in both the title and description. |
| Categories | Select one or more macro browser categories for your macro to appear in. |
| Icon URL | Enter an absolute URL (for example http://mysite.com/mypath/status.png) or path relative to the Confluence base URL (for example /images/icons/macrobrowser/status.png) if you want the macro browser to display an icon for your macro. |
| Documentation URL | If you have documentation for your macro, enter the URL here. |
| Macro Body Processing | Specify how Confluence should process the body before passing it to your macro. The macro body is the content that is displayed on a Confluence page. If your macro has a body, any body content that the user enters will be available to the macro in the Options for processing the macro body include:
|
Template | This is where you write the code that determines what the macro should do.
See User Macro Template Syntax for more information and examples. |
Do you need a plugin instead?
If you want to distribute your user macro as a plugin, please refer to the developer's guide to the User Macro plugin module. If you want to create more complex, programmatic macros in Confluence, you may need to write a Macro plugin.
Edit a user macro
To edit a user macro:
- Go to Administration > General Configuration > User Macros.
- Select Edit next to the relevant macro.
- Update the macro details.
- Select Save.
Delete a user macro
To delete a user macro:
- Go to Administration > General Configuration > User Macros.
- The currently configured user macros will appear.
- Select Delete next to the relevant macro.
Before deleting a user macro, you should search for all occurrences of the macro in pages and blog posts. Users will see an 'unknown macro' error if you delete a user macro that is still in use on a page.
Best practices
This section contains tips and suggestions for best practices when creating your own user macros.
Add a descriptive header to your macro template
We recommend that you include a short description as a comment at the top of the Template field as shown below.
## Macro title: My macro name
## Macro has a body: Y or N
## Body processing: Selected body processing option
## Output: Selected output option
##
## Developed by: My Name
## Date created: dd/mm/yyyy
## Confluence version: Version it was developed for
## Installed by: My Name
## Short description of what the macro does
Expose your parameters in the macro browser
The macro browser is the easiest way for users to configure your macro. You can specify the macro category, link to an icon, define the parameters that the macro browser will use to prompt the user for information, and more.
Supply default values for macro parameters
As you can't guarantee that a user has supplied parameters, one of the first things to do in the macro is check that you have received some value if you expect to rely on it later on in the macro code.
In the example below, the macro expects three parameters, and substitutes sensible defaults if they are not supplied.
#set($spacekey= $paramspacekey)
#set($numthreads= $paramnumthreads)
#set($numchars= $paramnumchars)
## Check for valid space key, otherwise use current
#if (!$spacekey)
#set ($spacekey=$space.key)
#end
## Check for valid number of threads, otherwise use default of 5
#if (!$numthreads)
#set ($numthreads=5)
#end
## Check for valid excerpt size, otherwise use default of 35
#if (!$numchars)
#set ($numchars=35)
#endConsider security implications
We recommend thoroughly testing your user macro with a number of permission scenarios, such as restricted pages and space permissions to avoid inadvertently displaying content that a user has no permission to see. See User Macro Template Syntax for more information.
Example user macros
This example demonstrates how to create a user macro that displays the text 'Hello World!' and any text that the user places in the body of the macro.
| Field | Value |
|---|---|
| Macro name | helloworld |
| Visibility | Visible to all users in the Macro Browser |
| Macro Title | Hello World |
| Description | Displays "Hello World" and the macro body. |
| Categories | Confluence Content |
| Icon URL | You can leave this field blank |
| Documentation URL | You can leave this field blank |
| Macro body processing | Rendered |
| Template | Enter the code below in the template field - this example will print the text straight onto the page. If you wanted the text to appear in a panel you could include the relevant AUI message class as shown here. |
Using the 'Hello World' macro on a page
Now you can add the macro to your Confluence page using the Macro Browser, or by typing {hello in the editor and selecting the macro from the list of suggestions.
The result is:
This example demonstrates how to create a user macro that can contain text that is visible when viewing a page, but does not print.
| Field | Value |
|---|---|
| Macro name | noprint |
| Visibility | Visible to all users in the Macro Browser |
| Macro Title | No Print |
| Description | Hides text from printed output. |
| Categories | Confluence Content |
| Icon URL | You can leave this field blank |
| Documentation URL | You can leave this field blank |
| Macro body processing | Rendered |
| Template | Enter the code below in the template field. |
Using the “NoPrint” Macro on a page
Now you can add the macro to your Confluence page using the Macro Browser. Text entered into the body of the macro placeholder will not be printed, but will appear when the page is viewed online.
Making the PDF export recognize the NoPrint macro
See Advanced PDF Export Customizations.
Context variables
By default, User macros have access only to the following Velocity context variables:
$generalUtil$htmlUtil
To grant User macros access to additional variables in the default Velocity context, use the system property macro.required.velocity.context.keys and specify the variables in a comma-separated format. Check out the list of available variables in the default Velocity context
For example, to grant access to $authenticatedUser and $action, you can define the following VM option: -Dmacro.required.velocity.context.keys=authenticatedUser,action.
Discover how to configure system properties
Method allowlist
Starting with Confluence 9.0, a new security feature called the Velocity method allowlist requires that all method invocations within a Velocity template, including User macros, be explicitly allowlisted.
Atlassian has already generated and approved a list of common and known safe methods. However, you may still need to manually allowlist additional methods in your User Macros based on the log warning output generated when previewing your User Macro.
After defining and saving your User Macro, try adding it to a new page. If you see log warnings like the ones below, you'll need to manually allowlist these methods (scroll right to see the full example):
16:21:05,888 WARN [http-nio-8080-exec-6] [velocity] log Invocation blocked as method is not allowlisted: com.atlassian.confluence.setup.settings.DarkFeatures#isDarkFeatureEnabled(java.lang.String)This list of methods collected from the logs can then be allowlisted by a system administrator using the atlassian.velocity.method.allowlist.extra system property.
As an example, you may allowlist two sample methods using the following VM option (scroll right to see the full example):
"-Datlassian.velocity.method.allowlist.extra=com.atlassian.confluence.setup.settings.DarkFeatures#isDarkFeatureEnabled(java.lang.String),com.atlassian.confluence.extra.dynamictasklist2.NameRenderer#render(java.lang.String boolean)"If the value is configured incorrectly or can't be parsed, Confluence will log warnings during startup to indicate the issue.
Do more with Confluence
Not keen to write your own macro? There are a ton of free and paid macros available in the Atlassian Marketplace. Here are some of our most popular:
- Numbered Headings: Automatically number headings for easy navigation and documentation
- HideElements for Confluence: Hide several Confluence page elements - e.g. title, comments, buttons - with just one click
- Composition Tabs & Page Layout: Bring your content to life - tabs, highlights, instant focus, menus and expandable sections
Next Steps
Explore the power of user macros further by reading our Writing Advanced User Macros guide.