User Macro Module


Confluence 2.3 and later

You can create user macros without writing a plugin, by defining the user macro in the Confluence Administration Console. See Writing User Macros.

Adding a user macro plugin

User Macros are a kind of Confluence plugin module.

User macro plugin modules are available in Confluence 2.3 or later

In order to upload your plugin via the Universal Plugin Manager (the default plugin manager in Confluence 3.4 and later) you will need to set the atlassian-plugin attribute pluginsVersion='2' as shown in the example bellow.

User Macro Plugin Modules

User macro plugin modules allow plugin developers to define simple macros directly in the atlassian-plugin.xml file, without writing any additional Java code. User macro plugin modules are functionally identical to Writing User Macros configured through the administrative console, except that they can be packaged and distributed in the same way as normal plugins.

User macros installed by plugin modules do not appear in the user macro section of the administrative console, and are not editable from within the user interface. They appear just as normal plugin modules in the plugin interface.

Configuring a Macro Plugin Module

Macro plugin modules are configured entirely inside the atlassian-plugin.xml file, as follows:

<atlassian-plugin name='Hello World Macro' key='confluence.extra.helloworld' pluginsVersion='2'>
        <description>Example user macro</description>
        <vendor name="Atlassian Software Systems" url=""/>

    <user-macro name='helloworld' key='helloworld' hasBody='true' bodyType='raw' outputType='html'>
        <description>Hello, user macro</description>
        <template><![CDATA[Hello, $body!]]></template>

    <!-- more macros... -->
  • The <template> section is required, and defines the velocity template that will be used to render the macro
  • All the velocity variables available in Writing User Macros are available in user macro plugin modules
  • The name and key of the macro must be specified the same as Macro Module
  • No class attribute is required
  • The attributes of the <user-macro> element match the corresponding configuration for user macros:

Available Attributes



Default Value

Allowed Values




  • true – the macro expects a body (i.e. {hello}World{hello})
  • false – the macro does not expect a body (i.e. Hello, {name})




  • raw – the body will not be processed before being given to the template
  • escapehtml – HTML tags will be escaped before being given to the template
  • rendered – the body will be rendered as wiki text before being given to the template




  • html – the template produces HTML that should be inserted directly into the page
  • wiki – the template produces Wiki text that should be rendered to HTML before being inserted into the page
Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport