Working with Macros

Using a macro, you can add extra functionality or include dynamic content in a page. For example, the Attachments macro will list a page's attachments in the page itself, so that readers do not have to visit the Attachments tab.

On this page:

Including a Macro in your Page

There are two ways to include a macro in your page. You can add macros using the visual Macro Browser, or by manually typing a macro command into the editor.

Including Macros with the Macro Browser

To insert a macro into a page using the Macro Browser,

For a complete description of the macro browser, see Working with the Macro Browser.

Including Macros with the Confluence Editor

In the Confluence editor, a macro is simply a command wrapped inside curly braces {...}.

For instance, the Attachments Macro is written as:

{attachments}

Macro Parameters

Many macros allow you to include optional parameters to control the macro's output.

With the Attachments Macro, for instance, you have two optional parameters:

• To specify the file formats of the attachments displayed.
• To choose whether or not you want old versions of the attachments displayed.

These optional parameters are included within the curly braces, following a colon, like this:

{attachments:patterns=.*jpg}

When specifying more than one parameter within the same macro, use the pipe symbol ('|') to separate one from the other, like this:

{attachments:old=true|patterns=.*jpg}

Case Sensitivity in Macro Parameters

Macro parameters are case sensitive. In most cases, the macro will expect its parameters to be in lower case. Make sure you follow the documentation for the specific macro and match the expected case, otherwise the parameter may be ignored.

For example, this code correctly has the parameter 'patterns' with a lower case 'p' as expected by the Attachments Macro:

{attachments:patterns=.*jpg}

This code will not work, because the parameter 'Patterns' has an upper case 'p', which the Attachments Macro will not recognise:
Invalid macro code:

{attachments:Patterns=.*jpg}

Macros Shipped with your Confluence Installation

When you download your Confluence installation file, many macros are shipped with the download. Below is a list of the macros currently shipped with Confluence. Click a macro name for details of the usage, including optional parameters and examples.

Information about Other Macros

Macros Provided by Plugins or User Macros

Other macros are available as plugins or as user macros, and can be installed by your Confluence administrator.

Customers using Adaptavist macros or plugins might be interested in the Adaptavist's Confluence user guide.

Some examples are:

• {sp-list} macro, provided by the Confluence SharePoint Connector – full documentation in the SharePoint Connector space.
• {float} macro and others, provided by the Composition plugin – full documentation by CustomWare.
• {status} macro, a user macro that your administrator can add to your site. It displays a coloured lozenge, useful for reporting project status. See our documentation.
• {expand} macro, a user macro that your administrator can add to your site. It displays an expandable/collapsible section of text. See our documentation.

Macros that Do Not Work

Some macros were never intended for external use, and we have always recommended that you do not add them to a wiki page. Nevertheless, it is possible that some Confluence sites have these macros on some pages. Please note that these macros no longer work in Confluence 3.4 onwards. They were part of the Plugin Repository, which we have now replaced with a new plugin manager.

These macros no longer work:

• {repository-plugin}
• {recentlyupdated-plugins}
• {popular-plugins}
• {download-stat}
• {confluence-status}
• {plugin-status}
• {plugin-repository}
• {plugins-supported}

Writing your own Macros

To learn how to write your own macro, take a look at the following documentation:

• User macros are simple template-like macros that allow you to create simple formatting macros using the Confluence web interface. Read more about Writing User Macros.
• The Confluence Plugin Guide tells you how to develop a plugin for Confluence.

RELATED TOPICS

Working with the Macro Browser
Confluence Notation Guide Overview
Atlassian Plugin Exchange
Installing Plugins and Macros

Take me back to the Confluence User's Guide.