This documentation relates to Confluence 3.1.x
If you are using an earlier version, please view the previous versions of the Confluence documentation and select the relevant version.

Working with Macros

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

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,

  1. Open your desired Confluence page or blog post, then click the 'Edit' button. The page or blog post opens in edit mode.
  2. Click the Macro Browser icon on the toolbar. The macro browser window opens in the middle of the screen in 'macro selection' mode.
  3. Scroll through the list of macros. Alternatively, start typing part of the name of your desired macro into the search box at the top right of the macro browser window. Macros with a matching name will appear in the main pane.
  4. Click on the desired macro to access its parameters and preview parameter changes ('preview mode').
  5. Set the macro parameters to your requirements. If desired, you can preview these changes by clicking 'Refresh'.
  6. Click 'Insert' to put the macro into the page.

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.

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.
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.
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:

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.
RELATED TOPICS

Confluence Notation Guide Overview
Confluence Plugin Guide
Plugin Index
User Macros

Take me back to the Confluence User's Guide.

Labels

confluence confluence Delete
macro macro Delete
list list Delete
all all Delete
summary summary Delete
index index Delete
documentation documentation Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Comments (18)

 

  1. Jun 08, 2007

    Olivier Oswald says:

    sometimes, macros have a regexp parameter and confluence messes up the pipe char...

    sometimes, macros have a regexp parameter and confluence messes up the pipe character of a regexp. how to handle this properly?

    1. Oct 08, 2007

      Matt Ryall (Atlassian) says:

      In order to keep the wiki syntax simple, and macros understandable, we don't cur...

      In order to keep the wiki syntax simple, and macros understandable, we don't currently support escaping the pipe character. For advanced functionality involving complex regular expressions, you should consider writing your own macro for Confluence.

  2. Oct 08, 2007

    Kelly Riley says:

    Is there a macro to increase the font size? I know there is one to decrease the ...

    Is there a macro to increase the font size? I know there is one to decrease the size {smalltext}, but I am getting several requests in make the fonts larger.

    1. Oct 08, 2007

      Matt Ryall (Atlassian) says:

      There's no built-in macro to do this, but you could easily do it with a User Mac...

      There's no built-in macro to do this, but you could easily do it with a User Macro. Create a macro called 'big', which converts its body to HTML and outputs HTML, with the following contents:

      <span style="font-size: 110%">$body</span>

      You can then use {big}Important{big} to create big text. Nesting macros isn't currently supported, so to make it extra-big, you'd need to add more macros, or make the font-size a parameter:

      <span style="font-size: $param0">$body</span>

      You could use this macro like this: {big:250%}Really important!{big}.

      We also have an outstanding feature request to add font-size to the wiki markup which you can vote for: CONF-5309.

  3. Sep 29, 2008

    Anonymous says:

    Is there a macro that allows us to publish an Excel spreadsheet as a Page instea...

    Is there a macro that allows us to publish an Excel spreadsheet as a Page instead of an attachment or instead of recreating the spreadsheet as a table in the Wiki?

    1. Oct 10, 2008

      Azwandi Mohd Aris [Atlassian] says:

      Hi there, As far as I am concerned, there is no macro that can exactly fulfil t...

      Hi there,

      As far as I am concerned, there is no macro that can exactly fulfil this requirement at this moment. However, you might be interested in an existing feature request at http://jira.atlassian.com/browse/CONF-10685. Hope that helps.

      Cheers,
      Azwandi

    2. Oct 16, 2008

      Anonymous says:

      Yes there is one.  Use this set of Macos: ////////////"; Cloak.openHTML = ...

      Yes there is one.  Use this set of Macos:

  4. Mar 25, 2009

    Jacqueline Snyder says:

    Is there a macro that allows you to collapse a table?

    Is there a macro that allows you to collapse a table?

    1. Mar 25, 2009

      Anonymous says:

      I use the [expand|http://confluence.atlassian.com/display/CONFEXT/Expand+Te...

      I use the [expand|http://confluence.atlassian.com/display/CONFEXT/Expand+Text+User+Macro] macro a lot to hide all sorts of stuff, tables included, if thats your intention.

  5. May 18, 2009

    Anonymous says:

    Why do most of the the examples on this page contain this oddity:patterns=.jpgIs...

    Why do most of the the examples on this page contain this oddity:patterns=.jpgIs this intended to be:patterns=.jpg... or is "=." some special syntax, or what?

    1. May 18, 2009

      Anonymous says:

      So of course that comment got mangled due to asterisk having special meaning in ...

      So of course that comment got mangled due to asterisk having special meaning in comments, and automated wrapping.... arrrrrrg.  OK, try again.

      Many of the examples show:  pattern equals dot asterisk jpg

      Probably this is supposed to be   pattern equals asterisk dot jpg

      ... but it might indicate some special syntax. Could someone clarify?

      1. Jul 01, 2009

        Anonymous says:

        That's a regex. Dot is a single character wildcard in a regex and the asterisk a...

        That's a regex. Dot is a single character wildcard in a regex and the asterisk annotation means "any number of the preceding". In your example case it means "any number of wildcard characters followed by the string 'jpg'"

  6. May 25, 2009

    Tom Kalikajaros says:

    Notation Guide in Confluence makes mention of {table-data] macro but nothing to ...

    Notation Guide in Confluence makes mention of {table-data] macro but nothing to be found here or in Working with Tables.

    Trying to find out if it possible to call tables created using

    Unknown macro: {table-data}

    macro onto other pages within same space? At same time I am keen to display only certain columns of the table data and not allow editing.

    1. May 27, 2009

      Azwandi Mohd Aris [Atlassian] says:

      Hi Tom, The {table-data} macro is provided by the third-party Scaffolding Plugi...

      Hi Tom,

      The {table-data} macro is provided by the third-party Scaffolding Plugin. You can learn more about the plugin and the macro from these pages:

      Hope that helps,
      Azwandi

  7. Nov 05

    Anonymous says:

    I need to use strings like Unknown macro: {somethinginhere} in my wiki page. ...

    I need to use strings like

    Unknown macro: {somethinginhere}

    in my wiki page. I keep getting the error 'Unknown Macro'. How to let wiki ignore these curly braces?. Any help is appreciated.

    Thanks

    Abdul

    1. Nov 05

      Tim Eddelbuettel says:

      You can add a backslash before the curly braces. window.SyntaxHighlighter.con...

      You can add a backslash before the curly braces.

      \{somethinginhere}

      {somethinginhere}

      Regards

  8. Nov 19

    Anonymous says:

    Thanks to tell me in which language are the macros written or where I can find a...

    Thanks to tell me in which language are the macros written or where I can find a user manual of this language (instructions beginning with #)

    1. Nov 20

      Zed Yap [Atlassian] says:

      Hi Thanks to tell me in which language are the macros written or where I can f...

      Hi

      Thanks to tell me in which language are the macros written or where I can find a user manual of this language (instructions beginning with #)

      I believe the language is called Velocity. To learn more on Velocity language please refer to this documentation:

      Hope that helps.
      Best rgds,
      Zed

Add Comment