How to Use Basic Confluence
Macros in an Advanced Way

Atlassian Confluence is your home for product requirements, product plans, blog posts, release notes, and just about anything you need to document. Confluence software allows you to reference and reuse content seamlessly while keeping it dynamic and engaging.

Wait. “Dynamic”, “engaging product requirements”, “plans” and “release notes”? How?!?

Macros.

Not just any macros, the kind that take your content to the next level.

If you’re new to Atlassian Confluence or if you’ve been using it for some time, read on to discover basic strategies of using advanced macros in Confluence. We’ll show you how to use basic Confluence macros in an advanced way and introduce more advanced functions Confluence macros can offer. Ultimately helping you get the most value out of your Confluence instance.

Explore Confluence Features Through Macros

If you’re reading this, you probably own a Confluence instance and are starting to use it. If you are a Confluence Administrator, go to “General configuration” > “macro usage” to see some potentially eye-opening statistics.

Confluence macros admin view

From this view, you can see which macros are not getting used, which macros are the most popular in your instance, and more importantly – where in your instance advanced macros are being used and adopted.

It’s highly likely that your users are looking past macros while using Confluence. Here are some advanced ways to use basic Confluence macros.

Links and Anchors

Links aren’t exactly macros, but they allow you to create singular content across your instance. You can link to other pages or even sections of other pages (more on this later).

The anchor macro provides similar functionality in two steps. First, place the anchor anywhere in your instance and give it a name. Next, provide a link to it so the content doesn’t need to be reproduced. Use the below # formulas to get the correct anchor location.

Confluence anchor macros

Anchors have a distinct advantage over links because they allow your content to change, and as long as the name stays the same, the content changes as well.

For example, there may be times that you want a link to a specific heading on your page. If that heading name changes, using a normal link won’t work. However, if you use the anchor macro, the heading information can change as often as you want without an issue.

Attachments Macro

Attaching content to your Confluence instance is as common as creating pages themselves. Everyone has documents outside of Confluence that should be in Confluence. The attachments macro lets you easily edit these documents and keep the versions up to date without having to upload and re-upload new types. This saves an enormous amount of time and keeps things nicely organized.

You can insert the attachments macro using the keyboard shortcut “{“.  Taking the attachments macro to the next level is in the parameters. By using the filename patterns section and inserting regular expressions, you can filter the file list by attachment type.

Confluence attachment macro

To take this macro one step further, you can send the attachment to a specific page by editing the attachment properties. Simply write the name of the page you would like to send it to and you’re done.

Confluence macro attachment property

Confluence Wiki Markup

As you peruse through the list of macros available out-of-the-box in Confluence, you may notice that many of them have a section about the wiki markup. According to Atlassian documentation, the wiki markup allows you to do the following:

  • Type wiki markup directly into the editor. Confluence will convert it to the rich text editor format as you type.
  • Create links using the Advanced tab of the Links Browser.
  • Add custom content to the sidebarheader or footer of a space.
  • Insert a block of wiki markup (or markdown) into the Confluence editor. (Choose Insert > Markup.)

In this blog post, we will focus on adding custom content into the sidebar, header, or footer of a space. This is useful if you want users to have quick access to a macro and its contents in your space.

To do this, choose your space settings, look and feel, then sidebar, header, and footer.  You can insert any wiki markup text from your desired macro and place it in the three different places in your space.  This is extremely useful if you want to have a file list, page tree, or any other macro appear in any of those three places for users to access.  Adjusting the parameters in the wiki markup will determine your macro output.

Note: The feature to add custom content in the sidebar is available for Confluence server or data center.

Navigation Map Macro

One of the more advanced macros that come out-of-the-box with Confluence is the NavMap Macro.  When configured, this macro displays a navigable map of pages tagged with a specific label. It is particularly useful when you are using labels on your pages and want a visual representation of how they are related.  

To insert this macro you can either select it from the macro drop-down list or use the keyboard shortcut. Once you have it inserted you can edit the following parameters: Label, map title, number of cells per row, cell width in pixels, cell height in pixels, and map theme.

The end result (without a theme) should look something similar to this:

Confluence Navigation map macro

This Macro is one that can be used in the wiki markup example that was mentioned above.  

If you’re using a server version of Confluence, there is an advanced way to take this macro to the next level – add your own theme.  You can do this by adding a customized navmap macro theme file to <InstallDir>/confluence/WEB-INF/classes/com/atlassian/confluence/plugins/macros/advanced directory.  In doing so, you can customize the NavMap to match your preferences.

Recently Updated Macro

The recently updated macro is perhaps one of the most popular Confluence macros.  It displays a list of the most recently changed content in Confluence. This is another macro that can be used with the wiki markup example.  The parameters include: Author(s) by username, space(s), label(s), width of table, include these content types only, maximum number of results, theme, show user profile pictures, and hide title.

The most commonly used parameters such as author(s), space(s), and label(s) allow you to limit who, from where, and what type of content you would like the macro to display.  Adding this macro to the homepage space might help users who use that space monitor frequent updates, so you could limit the content displayed to that of the particular space.

To utilize this popular macro as an advanced function, there is the possibility of editing the text within the recently updated macro. You can do this by editing the ConfluenceActionSupport.properties from your Confluence install directory.  Read more about the specific steps to do this here.

Macros Don’t Have to Be Basic

Tableau for Confluence Macro

Lastly, I would like to mention two of our own Confluence macros built by Atlas Authority, Tableau for Confluence – Pro and Markdown Macro for Confluence. (Please note, these are only available for Confluence server).

Tableau for Confluence helps you take your Tableau view and put it on a Confluence page. All you need to do is enter the workbook, view and you’re done! This macro gives you privacy controls, allowing you to choose which users are able to see the displayed Tableau data. Since the data is embedded as an image, it restricts the user from editing and allows for caching of the data. By ticking the interactive checkbox, it allows the user to interact with the data.

Markdown Macro

Using Atlas Authority’s Markdown Macro makes converting Markdown to HTML possible. It can be accessed from the macro browser, via tags, or the SOAP API.

You can learn more about the Markdown Macro using this link.

More to Come

Atlassian Confluence is an incredibly robust application and properly using out-of-the-box macros in addition to other useful macros will help you get the most value out of your instance.

Didn’t see something specific that you need? There are many more macros available in Confluence, you can discover them in the Atlassian Marketplace or stay tuned for a follow-up blog post! In the meantime, feel free to contact us and let us know if there are any specific Confluence macros you’d like to learn about – we’ll make sure to feature them.