Confluence Macros
Confluence pages go beyond just letting you put text on a page. While having text on a page is a very important aspect of the system, if that was all you could do, you would be very limited in your capabilities. Fortunately, the nice people at Atlassian have put in a number of widgets called Macros that help you extend the functionality of pages and save you a bunch of headache.
Macros are by no means necessary when using Confluence, however, they do make a number of things much easier. For example they can:
Automatically create a table of contents that updates based on headers on the page.
Pull in excerpts from pages with specific labels
Add a search box scoped to a specific part of the page hierarchy
Insert Jira tickets based on specific JQL
And a lot more
I find myself using macros on almost every page (and template) that I use, so let’s take a look at some of my favorites, as well as how you can find, and use macros.
Where are they found?
Macros are found on Pages and Blogs in Confluence. You can either click on the “+” menu in the toolbar, or use the “/” (forward slash) command to bring up a list of macros when you’re on a page or a blog.
From here, you can either scroll through the list, or search for the macro you want to use. I always encourage folks to take a look at the list of macros just to see what’s available. You should also note that different marketplace apps will add new macros. This means the list you see at one organization may not match that from anothers (this is a common source of confusion as folks think the same macros exist across all of Confluence).
Who can use macros?
Anyone who can edit a page or a blog can access macros. They’ll have full access to every macro that is installed, so there’s no additional management needed to provision or control them.
Individuals who have view access to a page or blog will see the macros, although unless they have edit access they won’t be able to edit them. It is important to remember that macros can pull in information from other pages - including ones a viewer doesn’t have access to. In this case the macro will display an error message to individuals who don’t have sufficient access. This is a common source of frustration as folks assume “Confluence is broken”. Here, a little bit of education can go a long way! (e.g. reach out for help instead of assuming something broke).
My Favorite Macros
Below are some of my favorite macros. This is by no means a definitive list of the “best” macros, just a list of ones that I find myself using on a regular basis.
Table of Contents
This macros automatically inserts a linked table of contents onto your page or blog. It bases the options based on headers in the document, and will automatically nest them so higher number headers appear under lower number ones.
This is a favorite of mine since it saves a ton of time having to manually insert a table of contents, and as long as I keep the headers updated it will update itself. It does have a few features that make it even more useful:
Include or exclude specific headers - You can choose to exclude headers below a certain size (e.g. only show headers 2 and higher), or even use regex to exclude headers that match a specific pattern. I commonly use this to exclude a “table of contents” header (one I frequently have on the page) as it doesn’t make sense to include that in the actual table of contents.
Horizontal orientation - The default layout for a table of contents is vertical, but you can also make it horizontal. I find this useful when I have a table of contents near the top of a page and think it looks better to have it go right to left.
There is a related macro called Table of Contents zone. This creates a table of contents based on a specific area of the page or blog. This is useful for creating “sub”-tables of contents, or providing more structure within a bigger piece of content.
Create from Template
This macros adds a button to your content that lets you create a new page from a selected macro with a single click. I find this incredibly useful for quickly creating pages for things I do frequently. Examples of this include things like meeting notes, team updates and the like. This is also a great feature to add for folks that infrequently use Confluence - instead of having to find the Templates menu they can just click a single button.
There aren’t many settings on this macro - basically you just select the template to use, and set a default page name. Despite being simple, however, it is an incredibly useful macro as it speeds up content creation and reduces the distance from “I want to create something” to “here’s my page”.
Panel Macros
Confluence doesn’t offer much in the way of visual formatting (at least without add ons!), so I frequently find myself using the “panel” macro to get some color on the page. This macros inserts a coloured box that can optionally include an emoji. I generally use this to draw attention to specific parts of a page (e.g. a “danger!”, “caution” or “Did you know?” box).
This is a very simple, but effective, macro, and only really offers a few options:
Color - The color you want to make the box
Emoji - Which emoji - if any - you want to include
This macro is another example of “simple doesn’t mean not useful”. Adding panels in appropriate spots (e.g. to call attention to specific pieces of information or warn about possible dangers) greatly improves the usability of pages and blogs.
Excerpt
Excerpt defines an area of the screen that can be pulled in by another macro. Excerpt by itself doesn’t do too much - just put a box on the screen - but when used in conjunction with other macros, like Excerpt Include, or Filter by Label - it’s very useful. I’ve found this useful in a number of different ways:
High level step-by-step - For longer process guides I commonly put an excerpt containing a brief overview of the steps. This excerpt is then pulled onto other pages, giving my team an idea of what the page is without having to open it.
Overview - Similar to #1 I’ll add an overview to pages in an Excerpt. This allows me to pull in the overviews across other pages, letting folks know what’s in store for them on the page.
Critical information - For longer pages I’ll put critical bits of information in excerpts. This lets me easily pull that information onto other pages, without having to maintain it in multiple spots.
Conclusion
There are a lot of different macros available out of the box, and many, many more available via marketplace add ons. Take time to explore the ones you have as many of them will make your life a lot easier.
