Skip to end of metadata
Go to start of metadata

The Macro Browser helps users to browse and insert macros while adding or editing content. If you are a plugin author, you need to include metadata in your macro so that works correctly and makes use of the new Macro Browser framework.

(info) As of Confluence 4.0, all macros must contain metadata in order to function correctly in Confluence.

Including Macro Browser Information in your Macro

You need to include information in your macro so that it appears and behaves correctly in the macro browser and displays the correct parameter input fields. This will require simple additions to your macro definition in the atlassian-plugin.xml file.

Macro Descriptor Attributes

The following macro attributes contain information specifically for the macro browser.





The absolute URL pointing to the macro's documentation.



The relative URL to the application for the macro icon. To display well in the macro browser, the image should be 80 pixels by 80 pixels, with no transparency.
Note: if you have your icon defined as a downloadable resource, you can refer to this by specifying "/download/resources/PLUGIN_KEY/RESOURCE_NAME" as the icon attribute.



This attribute is available for macros that falsely declare that they have body (most likely cause they extend BaseMacro) when they don't.
For example the Gallery macro. This attribute helps hide the body text field in the macro browser. 



If set to true, the macro is not visible in the macro browser for selection. Plugin authors may want to hide macros that are for their plugin's internal use and shouldn't really be used by users.


Macro Elements

The following macro elements contain information specifically for the macro browser. They should be placed inside your <macro> element.






The category the macro should appear in. Valid categories are listed below.



Defines an alias for the macro. This means that the macro browser will open for the defined aliases as if it were this macro.
For example if dynamictasklist is an alias of tasklist, editing an existing dynamictasklist macro will open it as a tasklist macro.



Defines a group of parameter elements. See example below.



This defines a single macro parameter. It must be an element of the parameters element. Its contents are described below.

Macro Categories

The following categories for macros have been defined (see A macro with no category will show up in the default 'All' category.

  • formatting
  • confluence-content
  • media
  • visuals
  • navigation
  • external-content
  • communication
  • reporting
  • admin
  • development

Parameter Options

Each <parameter> element must have the following attributes:

  • name - A unique name of the parameter, or "" for the default (unnamed) parameter.
  • type- The type of parameter. Currently the following parameter types are supported in the macro browser's UI:
    • boolean - displays a check box.
    • enum - displays a select field.
    • string - displays an input field (this is the default if unknown type).
    • spacekey - displays an autocomplete field for search on space names.
    • attachment - displays an autocomplete field for search on attachment filenames.
    • username - displays an autocomplete field for search on username and full name.
    • confluence-content - displays an autocomplete field for search on page and blog titles.

These are optional:

  • required - whether it is a required parameter, defaults to 'false'.
  • multiple - whether it takes multiple values, defaults to 'false'.
  • default - the default value for the parameter.

It can also have the following optional child elements:

  • <alias name="xxx"/> - alias for the macro parameter.
  • <value name="xxx"/> - describes a single 'enum' value - only applicable for enum typed parameters.
Hidden Parameter

It is possible to define a hidden parameter, to send information along with your form, invisible for users to see. Take a look at the examples below how to define this.

Within the atlassian-plugin.xml define a string parameter.

Inside the js/hidden-parameter-field.js


Autocompletion on the parameter types may show up that hidden is also a supported type. Keep in mind that choosing this type will not make the field hidden.


The following is an example of the Recently Updated Macro defined:

(warning) Note that this example contains parameter types which aren't all supported in the macro browser UI, but may be in future releases. (question)

Macro Icon Example

To provide an icon for your macro -
1) Create a resource for icons/images if you don't already have one. e.g.

<resource key="icons" name="icons/" type="download" location="myplugin/images/icons"/>

This must be a top level resource in your atlassian-plugin.xml and must be defined before the macro.

2) Ensure your plugin should contain the resource directory myplugin/images/icons

3) Set the icon attribute on the macro e.g.


i18n Conventions

Instead of having to define i18n keys for each element in the macro definition, the following convention is used to lookup i18n keys for the macro browser.




Macro label/display name


Macro description


Macro parameter label


Macro parameter description


Macro body label (defaults to 'Body Text' if not provided)


Macro body description

You will need to place the keys in a .properties file with a resource of type i18n in your plugin.


  1. does not work. still can see the macro in the browser.

    1. You still need the parameters element in your macro as it is a required field.

  2. The example lists several 'types' that the body doesn't mention...

    1. We currently don't have the UI for all the types in the example but we hope to add support for them incremently in future releases. Even if you use them, it will default to a string input field.

  3. Hi,

    I'm updating my macro (new code macro) to support the MacroBrowser, however one of the parameters I'm using (language) may change dynamically in the future by allowing users to upload support for new language or installing language plugins (like the code macro). I'd like this parameter to be an enum, so the user is able to select one instead of remembering the present aliases. Is there a way to dynamically (at runtime) extend the allowed options?

    1. Hi Jeroen,

      We had an initial implementation of dynamic parameter support for plugins to provide, however it wasn't an elegant solution and needs more work before we release it as an API to plugin developers. We have plans to revisit this, but it has currently fallen off the 3.1 roadmap (sad) So the short answer is 'no'... for now...

      1. Hi Agnes,

        Some more feature requests/questions:

        • For enums: allow a label besides a value. Probably more user friendly
        • For booleans: it seems that selecting a boolean value results in paramname=true, although deselecting it doesn't result in paramname=false?
        1. Hi Agnes,

          Nevermind question 2: already found the solution (default="true")

      2. Anonymous

        What is the current status of dynamic property.
        I'm doing a project where I would like to parse a enum with data from a rest return to a macro parameter, but can't seem to find a way of doing it anywhere.

  4. Is there a way to have the User Macros show up in the Macro Browser?

    1. Currently user macros are not supported in the macro browser. We have considered it for 3.1, but unfortunately it has fallen off the roadmap.

      1. It's a little confusing to have the ability to create User Macros, but no way to offer those Macros to all users.  How do you suggest showing users the User Macros when only Admins can access them?  It really does make sense to have the User Macros in the Macro Browser, maybe under a User Category.  Do you have the Jira task number so I can vote for this enhancement?



        1. Please remember that before 3.0, there was no such thing as a macro browser (smile)

          I have created an issue for this: CONF-16655

        2. Anonymous

          We have resorted to using a page for this purpose which is less than ideal.

          We tried converting the user macros to a user macro plugin thinking that we could then specify help in the notation guide like a standard java based macro. We later learned that the user macro plugin doesn't support this functionality.

          It would appear from Marco Carturan's comment below that a user macro plugin does appear in the Macro Browser, his issue is that he can't hide it. If it appears this may resolve our biggest concern and may allow us not to rush out and convert all of our user macros into java equivalents.

          1. Unfortunately the user macros are displayed in the macro browser by accident with the default macro display documented above (parameter information will not be displayed even if it defined).

            Please vote for CONF-16655@JIRA

  5. Is there an example of a non-atlassian Macro that has the icon working in the macro? I don't seem to be able to get an icon in the Macro browser. I have this:

    <macro ... icon="icon.png">

    <resource type="download" name="icon.png" location="images/icon.png">
    <param name="content-type" value="image/png"/>

    Any ideas?

    1. I don't think you need to specify a resource for it. Just set 'icon=/images/icon.png'.

      1. I've tried just that, but it doesn't work:

        the icon is in the project:

        and it will end up in the plugin/macro jar file in /images/icon.png:

        no error in the console log or whatsoever.

        1. Hmm. Not sure, I'm afraid. Any ideas Agnes?

          1. Anonymous

            Nobody knows about a 3.0 compatible macro that is working in the macro browser including the icon?

            All the Atlassian macro's cheat because they use icons from confluence icon directory.

            1. The Gliffy plugin has a customized icon.


          2. You can refer to an icon in your plugin if the icon is defined as a resource in your plugin.

            For example, if you have <resource type="download" name="icon.png" location="images/icon.png"> defined in your plugin xml, then you can refer to this downloadable resource by CONFLUENCE_BASE_URL/download/resources/PLUGIN_KEY/icon.png. Since the icon attribute only requires a relative url, you can simply specify /download/resources/PLUGIN_KEY/icon.png.

            The attachments macro is an example of an Atlassian plugin that refers to an icon in the plugin and not from the confluence icon directory.

            I will update the docs to make this a little clearer.

            1. Anonymous

              Ok, I got it working. The reason it took me a bit, is that the resource must be defined before the macro. Apparently the macro definition grabs or validates the image at load time.

              The required order might be something to stress in the documentation.

              Anyways, thanks Agnes, for the explanation. Thanks Tim for pointing at the Gliffy plugin (from the looks of it, they have been struggling with it as well and worked around it with a ../../../../../etc, but they were smarter then me and got it working before).

              1. And sorry for not logging in before posting...

                To round up, this works:

                1. Ah yes, you can't define resources inside the macro element! Sorry I didn't pick up on that in your code above.

                  Anyway, glad to hear you got it working!

                  1. I didn't have it inside, but after the macro definition. And it clearly needs to be defined before.

                    1. I got stuck on the image as well. The reference to the attachments plugin is what really helped me figure out what goes where.

                      1. From an installed version of Confluence, go to the bundled-plugins directory in the confluence-home directory
                      2. Unjar/unzip the confluence-attachments-plugin-x.jar file

                      The directory structure is there (in the plugin it'll be under resources) as well as the atlassian-plugin.xml example.

    2. Anonymous

      It works like described above. Without one exception. The PNG you use must be in indexed color mode (256 Colors).

      I tried nearly everything to get it work. But the icon was never displayed. After changing the color mode of the icon to indexed mode the icon appeared in the marco browser.

  6. Hi to all,
    I write a user macro inside a plugin and I want to hidden this macro in Macro browser.

    I have specified hidden attribute and <parameters> tag but if I search this macro in macro browser I find it.

    Any Ideas?

    Tanks a lot, regards

    Marco Carturan

    1. That's actually a bug. User macros shouldn't be shown at all in the macro browser, but it seems like it is going through as a macro without its parameter information defined.

  7. I'm having trouble with the macro name that appears in the Macro Browser. I can get the description from the i18n file easily (see the description node below), but the name seems to come from either the name or key attribute:

    An attribute value of googleanalytics displays as Googleanalytics in the macro Browser.
    An attribute value of google-analytics displays as Google analytics in the macro Browser.

    What's the best way to get it to display Google Analytics (i.e. title case) in the Macro Browser?
    Can this be read from the i18n file?

    1. You should specify a key of {pluginKey}.{macroName}.label in your i18n file. If this key is not specified, it defaults to capitalising the first letter of the macro name which is why you get Googleanalytics.

  8. I can't get the parameters to work. This is what the macro xml looks like:

    When I install the plugin (using the "pi" command in the atlas-cli) and then try it out the description and documentation url works just fine, but no parameters are displayed.

    Can anyone tell me what I am doing wrong? The log file doesn't say anything. I use Confluence 3.0.1 using the Atlassian SDK Plugin framework.

    1. Try adding a type attribute to the parameter element.

  9. What is multiple="true" suppose to do? On a enum type it doesn't even show the enum values nor does it restrict what is input. For a string type it doesn't seem to add any value. What was the intention?

  10. Must be doing some thing silly, read all the threads but can't get icon to show up

    I can access the file through browser and it is 80x80 but just doesn't show up in macro browser (sad)


    The resource is defined before the macro. How else can I trouble shoot this?


    1. I guess I lied when I said I read the entire thread.  I was missing the "so called" required parameters node. This works...

  11. Hello,

    is it possible to add values as droplist to a macro parameter after uploading the plugin jar file?

    Because I wanna add values to macro parameter after processing the page content, where the macro is used. Is it possible to add <value name="" /> after uploading the jar????

    Thx a lot.



  12. When using a parameter of type confluence-content you get a nice dropdown-list with your parameters. When you pick a page or blog from the searchbox, the macrobrowser only inserts their title in the parameter field, as described above. However, for a macro that uses that parameter there is no way to know if the title points to a page or a blogpost. Within the same space you can have a page with the same title as a blogpost, and even have multiple blogposts with identical titles as long as they are on different dates.

    It would be far more useful if the macrobrowser would include the date-path of a blogpost picked from the dropdown-list in the inserted title. That way a macro can easily distinguish between a page (no date-path, just a title) or a blogpost (date-path pointing to the exact blogpost).

    1. Arian, what version of Confluence are you using?

      A parameter of type confluence-content in 3.5 currently gives you a page in the format SPACEKEY:PAGE_TITLE while a blog will give you a format of SPACEKEY:POSTING_DATE:TITLE. You can test this out on this instance with a macro such as the include page macro.

      1. Agnes, my comment was related to version 3.4.6. I re-tested it right here like you suggested, and I'm happy to see that this is indeed working nicely now in 3.5.

  13. Is there a way to get the url of the  Confluence instance in the atlassian-plugin.xml? I have created a Space with the documentation for the theme plugin I have developed and the macros in my theme plugin. If I use "confluence/display/DEVdz3collaborators/Pop-Menu+Macro", for the documentation-url  "http://atlassian" is added to it. I need the full url to whatever instance of Confluence the theme plugin is installed on.

    1. Unfortunately we do not have this kind support for the documentation-url parameter. You could just put a link to that relative url in the macro description, as it will render the html provided by the description.

      1. I have tried putting the relative link in the description.

        This is what I have

        The link does not show in the insert macro screen.

        1. You will have to put the description in a i18n properties file. You should already have one if you have put labels and descriptions for your macro parameters. For the macro description it needs to be a key in the format {pluginKey}.{macroName}.desc as described above.

          1. Thanks Agnes,

            Putting the description for all oft the macros in my theme plugin worked.

  14. Anonymous

    I'm trying to create a parameter that can have multiple selections. has anyone figured out the purpose and how to use the attribute multiple=true? Or is there a way where I can create a parameter with multiple options (such as checkbox selections?). using this option with enum and string does not work for me.

  15. Anonymous

    For enum-typed parameters, how do you define a label for an option in your localization file ? 

  16. Anonymous

    I triedto name the parameter values but it fails:

    Naming the parameter is working ...

    <...>.param.jira.label=Jira Installation

    ... but naming the value not







  17. We can use as bellow to hide an parameter