Confluence tips and tricks: Intro and Table of Contents macro

by | Mar 28, 2017

One of my jobs at OptimalBI is to document the behind the scenes stuff which keeps the company running. Things like how to get broken office chairs fixed, the appropriate quantity of emergency scroggin and beer to keep under the sink in case of an earthquake, and the publishing process for blogs like this one.
There’s a certain way that we do things, and I make sure that all these processes are documented thoroughly just in case I get hit by a bus.
All this documentation, along with our development guides, health and safety stuff, and the colour-key to identify the decaf container in the OptimalHQ kitchen, lives in Confluence.


We use Confluence to organise all our internal information. It’s an Atlassian product, along with BitBucketHipChat and Trello. I like this platform; it’s a bit different from anything I’ve used before.
In the past, I’ve always used document stores which relied on files. Anyone who’s ever tried to manage a shared file system with broad-spectrum permissions will tell you this is a bad idea; duplication runs rampant and versioning problems become a recurring headache. The genius of Confluence as a system for sharing material is that it’s based on web pages in a wiki structure, like Wikipedia, which anyone in the office wth the right permissions can edit.
You can find a great introduction to Confluence here.
This is the very short version.

  • What is Confluence? An online application built to help teams organize, discuss, and do their work
  • Where do I put my stuff? Everything in Confluence is organized in spaces, which are a collection of related pages
  • How are spaces organized? Spaces are made up of pages. Pages are the documents in which your team will create, edit, and discuss work.

One of the best parts of Confluence is the thorough documentation, where you can find more on Spaces and Pages. You can get the full guide to Confluence here.
Confluence has a whole lot of tricks to help make your life better. My favourite of these tricks is macros.


Macros are little bits of code that add to the capability of your Confluence pages. As described in Atlassian’s Confluence macro documentation, you can use the Attachments macro to list files attached to a page, or use the Widget Connector macro to include things like a YouTube video or Twitter feed’. My favourite is the Table of Contents macro.

When you write text in a Confluence page using headings, this macro builds your headings into a handy table of contents to help your readers skip straight to the information they’re looking for. The macro is very useful when you have a large page with lots of information, but your reader just wants to make sure they aren’t wasting their time with decaf at 6am.

I particularly like that fact that the macro organises the table of contents to reflect the headings you use. This means the macro nests the Heading 2 headings under the Heading 1 and so forth as you see above. This is such a useful macro.
You can find the full Confluence Cloud Documentation here. So, what’s your favourite tip or trick for Confluence?
Success is preparation meets opportunity – Jack
Jack blogs about community, social media and how all this data stuff impacts the rest of us.
Want to read more? Try… LinkedIn Views, how they are counted and 4 tips for you or more from Jack.
We run regular business intelligence courses in both Wellington and Auckland.

Submit a Comment

Your email address will not be published. Required fields are marked *