Using Labels in Confluence – Order Is Half the Battle

4 min read / watch Watch Watch /

Confluence labels are a simple but powerful feature to categorize your content. Here are some reasons why we at K15t love working with labels:

  • To group pages that belong together, but exist in different spaces or hierarchies.
  • Labels are easy to add and remove without changing any content on the page.
  • There's no limit to labels, you can add them to pages, attachments or spaces.
  • Labels are user-defined and can be aligned to a use case, user group or other category. 

Start With a Label System 

Labels can be added to pages, attachments and even spaces to structure your content. Before you start using them, develop a label system with a clear set of rules. This helps everyone in the team to comply. Here are our recommendations:

Use naming conventions

Naming conventions help keep your labels clean and consistent. 

  • Use abbreviations and prefixes: Define if and how you will use abbreviations and prefixes, such as 'kb' for knowledge base articles or 'how-to' for step-by-step guides. 
  • Stick with singular: We recommend naming labels in singular form only. Otherwise you end up with 'project' and 'projects' and you won't know which is the correct one.
  • Keep it simple: Don't pack too much information into a label. Stick to single or short multi-word phrases, such as 'admin' or 'knowledge-base'.
  • Separate your words: Make it clear how to separate words. A hyphen or underscore are the most common separators.

For your naming system, it's helpful to use commonly used search terms. Take a look at your Confluence analytics – if you work with Confluence Cloud Premium or Cloud Enterprise – to find out what other users are searching for. You'll find a list of search terms and can decide whether your existing label names suit what your users search for.

Or take a look at Google Analytics to find what keywords your customers use. This can also help improve how you name your labels.

Define a label manager

Appoint a person to regularly monitor the system to ensure that all defined rules are being followed. Have you already designated a Wiki Gardener for your Confluence spaces? Then perhaps this person can take on this task too.

Here are some tips that help a label manager to keep track of how labels are being used.


Create an alphabetical list of your labels

Use the Label List macro to receive a list of all your macros in an alphabetical order to spot typos and other irregularities easier.

  1. Go to edit mode, click on .
  2. Filter for Label list.
  3. Define a space key or exclude particular labels, if needed.

You also see this overview if you type https://your-domain/labels/listlabels-alphaview.action.


Create a heatmap

See which labels are most frequently used within a particular Confluence space by creating a heatmap.

  1. Go to edit mode, click on .
  2. Filter for Popular Labels.
  3. Define a space key and a number of labels that should be displayed.

Use Cases for Labels

If you use Confluence and page labels, you have access to different macros that improve the usability of your documentation.

Better search results

With the Livesearch macro, you can add a search field to your documentation. You can narrow down the search results that are output via this macro to specific labels beforehand, so that your users only get the information they really need.

  1. Go to edit mode, click on .
  2. Filter for Livesearch macro.
  3. Fill out parameters such as space key, restrict to labels or content types or add a placeholder text.


Group a specific set of content

Your Confluence pages are probably clearly structured within one or more spaces. However, in some cases, pages cannot be clearly assigned and fit into multiple topics. For this case you can use the Content by Label macro. Enter one or more labels and the macro will automatically create a list of pages where these labels are used.

We use this macro to show related articles on our help center to list knowledge base articles that are actually not part of the documentation page tree, but that still provide useful information for the reader about specific topics.

Filter for attachments 

Using Confluence pages is more than just writing plain text content. You can also add attachments such as images, proposals, contracts or other documents as pdf, image file, Word file or other document file formats. Therefore it makes sense to label relevant attachments as well.

  1. Go to the page that contains the attachment and click Attachments
  2. Select the attachment, click on the label sign  and add your label.

The quick search bar in the top right corner of a Confluence page allows you to quickly find specific attachments using the combination of Content Type attachment and the corresponding Label.

If you manage many attachments and need a better overview of them, you can create a list using the Content by Label macro.

Tell Us Your Use Case

There are so many great ways to use labels for your documentation in Confluence. What is your favorite? Drop us an email and let us know how your team works with labels.