When you open a Confluence page and the first thing you see is a table of contents, you’re in for an adventure, but at least a guided one. A guided one if the headings are clear, the table is well structured and placed.
The table of contents macro might be perceived as straightforward, which is tbh. But as is the case with any macro, it’s not about how to use it but rather how to EFFECTIVELY use it. So in this article we’ll be moving from the obvious to the less obvious, starting with use the table of contents macro, how to insert it, the best practices to follow, and some common questions you might have.
Why You Need a Table of Contents
In three simple words: Navigation, scanning, and search
For long Confluence pages, a table of contents is a must. It acts as a map that gives readers a host of shortcuts to easily navigate and access the parts they’re most interested in.
For a marketer like myself, I often have to navigate through some highly technical documents. I don’t need every detail, I just want to find release dates or product changes quickly. A well-structured TOC lets me do that in seconds. Engineers, on the other hand, might use it to jump to specs, while project managers might look straight for timelines.
Sometimes we don’t have a general idea of what the content is all about, a TOC helps you quickly scan the content. You’ll have a snapshot of the structure and key sections letting you quickly judge whether the page has the information you need.
Finally, a TOC makes content easier to search and reference. By clearly organizing headings, it helps both humans and Confluence’s search function find specific sections faster, saving time and reducing frustration.
How to Create a Table of Contents Macro in Confluence
The macro is both simple and quite rich in terms of customization options:
- First navigate to your Confluence page or live doc.
- Type /Table of contents. The table will appear along with a drawer containing a host of customization options
- You’ll find two tabs: Basic & Advanced.
- Within Basic settings, you can adjust the layout to be either horizontal or vertical, the style, and depth
- When it comes to Advanced customization options, you can include or exclude headings including certain keywords, and even adjust how subheadings are indented in the TOC by entering a valid CSS value.
Best practices to use the Table of Contents Macro
Put in Place a Clear Hierarchy
The table of contents is a roadmap or more like a mirror of your own content. So the first step isn’t tied to its implementation but rather how you structure your page.
Make sure to establish clear, distinct, and concise sections using headings and subheadings only. Other formatting options or regular links won’t show up. The key here is to follow a clear logical structure, don’t be tempted to include levels just for the sake of it, and NEVER skip a level. Meaning if you start with an H1, then H2, don’t jump to H4.
Don’t Include Everything
Sometimes the table of contents is so long that you feel it needs its own. Here you’ve just guaranteed a painful experience to your readers. Instead of including everything from H1 all the way through to H6, try to limit the depth. Show only two to three levels, and make sure the headings reflect what’s inside them. This way the table stays short and especially easy to scan.
Know When to Use the Table of Contents Macro
This one is obvious but not all people follow it. Your Confluence content might indeed include say three levels, but that doesn’t mean you have to include a table of contents. On short pages, readers can scroll and scan just fine. Having a Toc in there is more of a distraction or may even convey that doc is longer or more complex while it isn’t. And for people like me? That’s a signal to run away 😀. Save the TOC for longer pages, where it actually improves the experience.
Horizontal or vertical layout?
The Content Design Glossary template includes those little macros with letters arranged horizontally. At first I thought that was some sort of fancy navigation macro. Well, it turned out it was the very own Toc macro. And there as a product marketer, I kind of have to ask myself: when should you go horizontal, and when vertical?
A horizontal layout works best when you don’t have many sections and little to no depth within your content, exactly like the glossary template. This doesn’t necessarily mean that content is short, but rather it’s simply structured.
Vertical, on the other hand, is better for long or detailed pages. It can display multiple levels clearly and acts more like a proper navigation sidebar, which readers rely on heavily when moving through lots of sections.
Frequently Asked Questions: Table of Contents Macro
Q1: Can the macro retrieve headings included within other macros such as expands, tabs, or tables?
In most cases, yes. If you have headings embedded within tabs, expands, table, or panels, they will show up within your ToC.
Q2: Can I customize the table of contents macro?
If you didin’t jump directly to this section you’d have known, and the answer is yes. You can customize pretty much everything about the macro including display, style, number of icnluded headings, and much more.
Q3: Can I create a table of contents for specific sections only?
Yes you can. Here, you’ll be using the table of content zone macro. Simply put, you insert the macro, add your content within it. A dedicated ToC will be generated automatically for only the content embedded within the macro.
Q4: Will the content included using the zone macro be visible if I included the ToC macro at the top of my page?
Yes. The content will be visible. And this is why in most cases -at least based on my experience- the zone macro is often included as a horizontal navigation item within the content body.
And there you have it! The table of Contents macro is a great way to enhance navigation and provide a smooth experience for your readers. For more articles like this, make sure to check out our blog, and our YouTube Channel.
