Working with Macros

Unknown macro: {float}

Differences in Confluence Team Hosted

If you are using Confluence Team Hosted, the plugins and macros are installed for you. Refer to the list of [macros on Confluence Team Hosted FAQ].

Macros perform programmatic functions within a page and can be used to generate complex content structures or dynamic content.

Macros allow you to 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
- Optional Parameters in Macros
- Case Sensitivity in Macro Parameters
Macros Shipped with your Confluence Installation
Information about Other Macros
Writing your own Macros

Including a Macro in your Page

Generally speaking, a macro is simply a command wrapped inside curly braces {...}.

For instance, the Attachments Macro is written as:

{attachments}

Optional Parameters in Macros

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.

Attachments Macro	Displays a list of attachments belonging to the current page.
Blog Posts Macro	Lists the most recent news items in the space.
Bookmarks Macro	Includes a list of bookmarks on a Confluence page.
Change-History Macro	Displays a history of updates made to a page.
Chart Macro	Displays a chart based on tabular data.
Cheese Macro	Displays the words "I like cheese!"
Children Display Macro	Displays the children and descendants of the current page.
Code Block Macro	Displays code in your document with the appropriate syntax highlighting.
Color Text Macro	Changes the colour of a block of text.
Column Macro	Used with the Section Macro. Defines columns within the page.
Content by Label Macro	Renders a list of content associated with specific labels.
Create Space Button Macro	Renders a create space button linked to the create space page.
Tasklist Macro	Displays a dynamic task list which can be modified in 'view' mode.
Edit in Word Link Macro	Displays an 'Edit in Word' icon on your page.
Excerpt Macro	Allows you to define a part of the page as the page's 'excerpt' which is then used by other macros to summarise a page's content.
Excerpt Include Macro	Allows you to display an excerpt from another page within the current page.
Favourite Pages Macro	Displays a list of your favourite pages.
Excerpt Include Macro	Includes one page's excerpt in another.
Gallery Macro	Forms a thumbnail gallery of all images attached to a page.
Global Reports Macro	Renders a list of links to global reports within a table.
HTML Macro	Renders your specified HTML code within the current page.
HTML Include Macro	Includes the content of an external HTML file into a Confluence page.
IM Presence Macro	Displays graphically when a contact is online.
Include Page Macro	Inserts the contents of the specified page into the current one.
Info Macro	Displays a block of text in a blue highlight box.
JIRA Issues Macro	Displays a list of JIRA issues in a page.
JIRA Portlet Macro	Displays a JIRA dashboard portlet in Confluence.
JUnit Report Macro	Display a summary of JUnit test results.
Livesearch Macro	Add a dynamic search box to a wiki page.
Loremipsum Macro	Display a few paragraphs of pseudo-Latin text.
Navmap Macro	Renders the list of pages associated with a specified label as a navigable map.
Noformat Macro	Displays a block of text in monospace font.
Nolink and nl Macros	Prevents the browser from automatically hyperlinking a URL.
Note Macro	Displays a block of text in a yellow highlight box.
Panel Macro	Displays a block of text within a fully customisable panel.
Pagetree Macro	Displays a dynamic, hierarchical list of pages starting from a specified parent (root) page.
Pagetree Search Macro	Adds a search box to your Confluence page and searches a hierarchy of pages starting from a specified parent (root) page.
Recently Updated Macro	Displays a list of recently changed content (pages, news items, comments, etc).
Recently Used Labels Macro	Lists labels most recently used in a specified scope (Global, Space, or Personal)
Related Labels Macro	Lists labels frequently appearing on the same pages as the current page's labels.
RSS Feed Macro	Displays the contents of an RSS feed.
Search Macro	Searches Confluence, and includes the results in the page.
Section Macro	Used with the Column Macro to define columns within the page.
Space Details Macro	Includes the summary of a Confluence space in the page.
Spaces List Macro	Displays a list of all spaces visible to the user.
Tip Macro	Displays a block of text in a green highlight box.
Thumbnail Macro	Creates a thumbnail of an inline image.
Userlister Macro	Displays a list of Confluence users, from an optional group.
View File Macro	Embeds an Office document into your Confluence page.
Warning Macro	Displays a block of text in a red highlight box.
Web-Widget Macro	Same as the Widget macro.
Welcome Message macro	Includes the Confluence site welcome message.
Widget Macro	Displays videos, slide shows, twitter chats, documents and more, sourced from other web sites and displayed on your Confluence page.

Information about Other 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:

{toc} macro, provided by the [Table of Contents Plugin] - full documentation by CustomWare.
{float} macro and others, provided by the [Composition plugin] - full documentation by CustomWare.

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 User Macros.
The Confluence Plugin Guide tells you how to develop a plugin for Confluence.

Page tree