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 add-on. You will need some coding skills though.  

You'll need System Administrator permissions to create and manage user macros. 

On this page:

Related Pages:

Creating a User Macro

To add a new user macro:

  1. Go to  > General Configuration > User Macros.
  2. Choose Create a User Macro.
  3. Enter the macro details (see table below)
  4. Click Add.
Macro details field Description
Macro name This is the name of the macro, as it appears in the code.

This controls who can see this macro in the macro browser or auto-complete. Options are:

  • Visible to all users
  • Visible only to system administrators

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 $body variable.

Options for processing the macro body include:

  • No macro body
    Select this option if your macro does not have a body.
  • Escaped
    Confluence will add escape characters to the HTML markup in the macro body. Use this if you want to show actual HTML markup in the rendered page. For example, if the body is <b>Hello World</b> it will render as  <b>Hello World</b>.
  • Unrendered
    HTML in the body will be processed within the template before being output. Ensure that HTML is ultimately output by the template.
  • Rendered
    Confluence will recognise HTML in the macro body, and render it appropriately. For example, if the body is <b>Hello World</b> it will render as Hello World.

This is where you write the code that determines what the macro should do.

  • Use HTML and Confluence-specific XML elements in the macro template. Details of Confluence's storage format are in Confluence Storage Format.
  • You can use the Velocity templating language. Here is more information on the Velocity project.
  • If your macro has a body, your template can refer to the macro body text by specifying '$body'.
  • Each parameter variable you use must have a matching metadata definition. Use @param to define metadata for your macro parameters.
  • When using the information passed using parameters, refer to your parameters as $paramXXX where 'XXX' is the parameter name that you specifed in the @param metadata definition.
  • Use @noparams if your macro does not accept parameters.

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.

Editing a user macro

To edit a user macro:

  1. Go to  > General Configuration > User Macros.
  2. Click Edit next to the relevant macro.
  3. Update the macro details as explained in the guide to writing user macros.
  4. Click Save.

Deleting a user macro

To delete a user macro:

  1. Go to  > General Configuration > User Macros.
  2. The currently configured user macros will appear.
  3. Click 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
## 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)

## Check for valid number of threads, otherwise use default of 5
#if (!$numthreads)
  #set ($numthreads=5)

## Check for valid excerpt size, otherwise use default of 35
#if (!$numchars)
  #set ($numchars=35)

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport