Confluence Headers

Creating good content for a knowledge base or similar system is challenging. You have to determine what your audience needs, find experts who know those topics and ensure content is regularly maintained. There is, however, a very simple thing that can be done to improve almost every page in Confluence (and in many other similar systems) - use headers.

Headers are essentially just bigger text on a page, but despite their seemingly simple design they serve a number of important functions in Confluence.

Visually breaking up space

Before you keep reading, scroll to the bottom of this post, I’ve copied all the content, but left out the headers…. It’s a bit hard to read, no?

The first, and arguable most important feature, or a header is to visually break up space on a page. I’ve lost track of the number of times I find really good content, but find it hard to read because it’s all just one gigantic wall of text. Paragraphs can (and do!) help with this, however, when all the text is the same size it makes it very hard to browse and find information.

To get around missing headers I frequently find myself using a find command (CMD+F) to locate specific words or phrases. This can help, however, sometimes I have to guess at the keyword or topic I”m looking for - and it’s not always there.

This is where headers are useful. They give the writer a way to clearly signal where specific content lives on a page, or, if they use multiple sizes of headers, how various pieces of content could relate to others. They’re a bit similar to Confluence’s page tree - they let creators structure pieces of your content, both for themselves as a creator, but also for folks consuming that content.

As the example below shows, without headers pages quickly turn into word soup.

Anchors (links)

Another important feature of headers - and one that more people need to know about - is their ability to act as “Anchors”. Anchors are just another way of saying “hyperlinkable text”, and while you can add an anchor anywhere on a page you like (and link to it), headers are, by default, anchors themselves.

This means every header on your page has its own unique hyperlink. While it’s not immediately obvious, this means that you can link anyone directly to a specific header on a page. This greatly reduces the need for someone to scroll or CMD+F for content since you can send them directly to what they need instead of the top of the page.

Personally I find myself using this feature quite a bit - especially if I’m using Confluence to host a FAQ (I tend to make each question its own size 5 header, this makes it look like regular text, but function as an anchor). It’s also a great trick for bigger pages, or for ones with lots of headers.

Macros (Specifically Table of Contents)

The third major reason I like headers is because they interact with various macros - specifically “Table of Contents”. This macros automagically created a hyperlinked, nested, table of contents wherever you want. The macro uses the header size to build a nested list of headers, and does it in real-time as you’re editing so you can easily see what it looks like.

It also has some options that allow you to specify which levels of header should be used - for example you could exclude header level 1 if you wanted, which would allow you to use that for things like “background” or “table of contents”, while leaving the table of contents a bit more organized.

While you can get the same effect by manually typing out a table of contents and linking things, this is incredibly time-consuming and requires you to go and change it as the page is updated. I’ve been including this in all of my templates (and most of my pages!) as it helps with navigation (even with shorter pages). Setting the expectation that it will be at the top also helps my team more easily use content as they’ll know there’s always links to follow.

The Wrap Up

Headers are a great, simple, way to greatly improve the look, usefulness and ability of your pages. At the very least they’ll help you break up your content so it’s easier for readers to digest it, but they also offer some great additional features.  Even better, they’re incredibly simple and easy to add!

Same text - without headers

Creating good content for a knowledge base or similar system is challenging. You have to determine what your audience needs, find experts who know those topics and ensure content is regularly maintained. There is, however, a very simple thing that can be done to improve almost every page in Confluence (and in many other similar systems) - use headers.

Headers are essentially just bigger text on a page, but despite their seemingly simple design they serve a number of important functions in Confluence.

Before you keep reading, scroll to the bottom of this post, I’ve copied all the content, but left out the headers…. It’s a bit hard to read, no?

The first, and arguable most important feature, or a header is to visually break up space on a page. I’ve lost track of the number of times I find really good content, but find it hard to read because it’s all just one gigantic wall of text. Paragraphs can (and do!) help with this, however, when all the text is the same size it makes it very hard to browse and find information.

To get around missing headers I frequently find myself using a find command (CMD+F) to locate specific words or phrases. This can help, however, sometimes I have to guess at the keyword or topic I”m looking for - and it’s not always there.

This is where headers are useful. They give the writer a way to clearly signal where specific content lives on a page, or, if they use multiple sizes of headers, how various pieces of content could relate to others. They’re a bit similar to Confluence’s page tree - they let creators structure pieces of your content, both for themselves as a creator, but also for folks consuming that content.

As the example below shows, without headers pages quickly turn into word soup.

Another important feature of headers - and one that more people need to know about - is their ability to act as “Anchors”. Anchors are just another way of saying “hyperlinkable text”, and while you can add an anchor anywhere on a page you like (and link to it), headers are, by default, anchors themselves.

This means every header on your page has its own unique hyperlink. While it’s not immediately obvious, this means that you can link anyone directly to a specific header on a page. This greatly reduces the need for someone to scroll or CMD+F for content since you can send them directly to what they need instead of the top of the page.

Personally I find myself using this feature quite a bit - especially if I’m using Confluence to host a FAQ (I tend to make each question its own size 5 header, this makes it look like regular text, but function as an anchor). It’s also a great trick for bigger pages, or for ones with lots of headers.

The third major reason I like headers is because they interact with various macros - specifically “Table of Contents”. This macros automagically created a hyperlinked, nested, table of contents wherever you want. The macro uses the header size to build a nested list of headers, and does it in real-time as you’re editing so you can easily see what it looks like.

It also has some options that allow you to specify which levels of header should be used - for example you could exclude header level 1 if you wanted, which would allow you to use that for things like “background” or “table of contents”, while leaving the table of contents a bit more organized.

While you can get the same effect by manually typing out a table of contents and linking things, this is incredibly time-consuming and requires you to go and change it as the page is updated. I’ve been including this in all of my templates (and most of my pages!) as it helps with navigation (even with shorter pages). Setting the expectation that it will be at the top also helps my team more easily use content as they’ll know there’s always links to follow.

Headers are a great, simple, way to greatly improve the look, usefulness and ability of your pages. At the very least they’ll help you break up your content so it’s easier for readers to digest it, but they also offer some great additional features.  Even better, they’re incredibly simple and easy to add!