When creating content in Confluence, walls of text are your worst enemy. Upon landing, your readers won’t have any direction and won’t be able to distinguish between sections and which ones matter the most. Obviously this makes navigation challenging and leads to low engagement rates. To fix this there is one really simple yet effective feature that comes natively in Confluence: Headings.
We’ve all used them before, be it in Confluence or elsewhere. In this article we’ll check why headings matter, how to implement them, and of course, how to make the most out of them.
Why Headings are the pillar of your Confluence pages
Guide readers through content
When we access a Confluence page (especially long and complex ones), we often scan and look for specific sections, then decide to go through the content or not. Think of a documentation page where you’re only interested in the “best practices” section. With no clear headings, you’ll have to go through the entire content in some cases to find what you’re looking for. And this is when headings come into play. They properly structure your content and guide readers through.
Provide quick access to content
In Confluence, headings automatically act as anchors. This allows you to copy the link of a certain section and paste it anywhere within other Confluence pages. For example, instead of adding a link to an entire documentation within your knowledge base homepage, you can only link to the section most useful to your readers.
How to insert headings with your Confluence pages
Manually inset headings
Adding headings within your Confluence pages is pretty much straightforward.
You can either start by selecting the heading of your choice and then from the toolbar or type Ctrl + Alt + H… or highlight your text and select the appropriate header.
While you can’t turn headings into bullet points or numbered lists, you can indent or outdent them to visually nest subsections under higher-levels, helping to organize content and show relationships between sections.
Leverage AI to properly structure your sections
Every easy or repetitive process can and should be delegated to AI. If your pages are quite long or you’re not quite sure whether to use headings or simple bulletpoints, our very own Morph:AI-Powered Content Formatting for Confluence can help you out.
The latest release comes with an out-of-the-box Rovo agent that scans your text and applies the right structure. In this example, we have a documentation page with little to no formatting. We started by asking the agent on the best way to organize some sections: The agent inquired about our goal which in our case is to add a general structure to our text. And its answer was we should apply headings. Then, the next step was to simply ask the agent to perform the action. And voilà!
Which Confluence macros work best with headings?
Confluence comes with a large array of interconnected macros all designed to enhance navigation, improve structure, and enhance the overall user experience. When it comes to headings, using them is one thing, but if you want to take things to the next level, you’ve got to integrate them with other macros. and one obvious macro comes to mind:
Table of contents
Structuring content with headings is a great first step as it facilitates the first scanning. If you stop there though, you’re only halfway through as readers will still have to scroll. The next logical step (especially if the content is long) is to group everything within a comprehensive table of contents. The macro acts as a summary of your content with all of your headings or only a selected few by level.
Excerpt & excerpt include
Simply put, the excerpt macro helps you mark a part of your text to reuse within other pages. and it aligns closely with sections defined with headings. For example, within your product documentation, you might have the same sections repeated across pages. You can insert the excerpt macro within the source page including the headings. Then navigate to all of your other pages and only include the excerpt name via the excerpt include macro.
Best practices to work with headings in Confluence
Use descriptive titles
This one is obvious. Your headings should be descriptive enough for readers to immediately understand what each section is about without needing to read the whole section. Also, try to avoid vague and especially long titles that won’t display properly within the table of contents macro.
Establish a clear and simple hierarchy
Confluence allows you to include up to six levels for your headings. But realistically, you would want to avoid going beyond the third or fourth levels as this will hinder the reading experience. H1 in Confluence is still quite confusing to me as you already have a title for your page but in theory H1s are often used as the main titles. H2, H3, and so on are used for subheadings. Each one is more important than the one below it.
Use responsibly
It’s tempting to dive into H5 or H6 to structure small lists or minimal content but this can clutter your page and confuse readers. You can simply use other formatting options like numbered or bullet lists. This keeps the page structure clean, ensures the Table of Contents remains useful, and helps readers scan and navigate content efficiently.
Headings in Confluence are more than just text formatting. They are the backbone of any well-organized Confluence page guiding readers through content, make navigation effortless, and serve as anchors for linking and referencing key sections.
