To categorize, identify, or bookmark content in Confluence we can use labels. Labels are keywords or tags that can be added to pages, blog posts, attachments, and spaces as metadata. Labels are user-defined so any word that identifies your content can be used.
For example, you can assign the label "requirement" to all pages with project requirements. It is then possible to browse, or list, all pages with that label in a single space or even across Confluence. It is also possible to search content based on that label.
The advantages of using labels are as follows:
- Labels are user-defined, so you can decide what information is relevant and how you want to label them, using words you and your users understand
- With labels you can group pages and spaces without having to restructure your site
- You can add as many labels as you like
- Labels are easily added without affecting the content to which you assign a label
Confluence doesn't support multiword labels. Which means that, to label a page with "needs review", the space has to be replaced with another character such as a dash or underscore.
Any user with the permission to edit a page or blog post can also manage labels.
In order to add a label, you will have to perform the following steps:
- Go to the page you want to label. At the bottom of the page, just below the content, there will be a list with labels (provided the page already has labels, otherwise, No labels will be displayed).
- Click on the edit icon next to the list, or press L on your keyboard. This will display the labels dialog.
- Type in a new label. Labels that are frequently used throughout your Confluence instance are suggested as you type.
- Click on Add as shown in the following screenshot:
In order to remove a label, you will have to perform the following steps:
Attachments can also have labels, making it easier to find or filter them. Labels can be added or removed by any user who is allowed to edit the page that holds the attachment.
To add a label to an attachment, perform the following steps:
- Go to the page that contains the attachment.
- Choose Tools | Attachments to go to the attachment view.
- On the attachment view you will see a list of attachments. If an attachment already has labels, these will be shown in the Labels column.
- Click the edit icon to open the label dialog.
- Type a new label; existing labels will be suggested as you type.
- Click on Add as shown in the following screenshot:
Labels are deleted the same way as with pages. Click on the X mark next to a label to remove it from the attachment.
A space category is a special label that Confluence uses to group spaces in the space directory and in the recent activity area on the Dashboard. Let's assume that you have one or more spaces that contain information about the same project, Project42. We can categorize all those spaces as "Project42" to group them.
Grouping spaces with categories will reflect in the space browser and you can see the updated content in those spaces by choosing the Project42 category under the Space Categories tab on your dashboard as shown in the following screenshot:
To add a category to a space, perform the following steps:
- Go to the space and choose Space tools on the left sidebar.
- Select Overview to navigate to the space details page.
- Click on Edit, next to Space Categories.
- Use the text field to add new categories to a space.
- Click on Done.
Categories are removed the same way as labels. Click on the X mark next to the category to remove it.
When you click on a label on a page, blog post, or attachment, you will be forwarded to the labels view. Alternatively, if you are using the documentation theme, go to any page in a space and choose Browse | Labels.
The labels view in a space offers the following features:
- Popular Labels: Use this view to see a list of the most frequently used labels in that space. From this view you can also view the global popular labels. The bigger the label, the more popular it is.
- All Labels: This view will show all the labels in the space. Click on a label to see the associated content in that space. It will also display related labels if they exist. Related labels are labels that often appear on pages together.
- See content from all spaces: From both views it is easy to expand the list to include all labels content across your Confluence site.
Labels are very powerful when used in conjunction with macros to dynamically display content. Confluence comes with the following set of macros for labels:
- Content by Label: This lists pages tagged with one or more specific labels
- Labels List: This lists all labels of a space, grouped alphabetically
- Navigation Map: This creates a map of pages associated with a specified label
- Popular Labels: This generates a list or heat map of the most popular labels
- Recently Used Labels: This lists the most recently used labels in a predefined scope of spaces
- Related Labels: This lists labels used on other pages that have labels in common with the current page.
We will discuss the Content by Label macro as this is probably the most used macro of the set.
The Content by Label macro will find and display a list of all pages, blog posts, and attachments in a space tagged with the specified labels. Imagine yourself with a space full of projects and customer information; with this macro you can easily create an overview of all customers provided you labeled them.
To add the Content by Label macro to a page, perform the following steps:
- Open a page in the edit mode and place the cursor at the location where you want to add the macro.
- Choose Insert | Other Macros.
- Find and select the Content by Label macro.
- Fill in the properties on the right-hand side of the screen; the label is required.
- Click on Insert as shown in the following screenshot:
The following properties are available for the Content By Label macro:
|
Properties |
Default |
Description |
|---|---|---|
|
The macro will only display content tagged with the labels specified here. You can specify multiple labels separated by a comma. Labels can be excluded by putting a minus ( | ||
|
This will filter by creator or last updated by. | ||
|
All |
Set the content type to display. The default will show page, blogpost, and attachments but you can specify one or more content types. | |
|
Yes |
This shows or hides the labels in the results. | |
|
Yes |
This shows or hides the spaces in the results. | |
|
15 |
This limits the maximum number of results to display. Note that the results are sorted first then limited. | |
|
No |
Display the page excerpt (added by the excerpt macro). | |
|
@all |
The macro will only display content in the specified spaces. You can specify multiple spaces separated by a comma. To exclude a space add a minus ( The special values include:
| |
|
OR |
This is the operator to apply when matching content against the specified labels:
Labels prefix with a minus are not affected by this setting. | |
|
Modified | ||
|
no |
Select Reverse Sort to change the sort from descending to ascending order. Use this parameter in conjunction with the Sort By parameter. Reverse Sort is ignored if Sort By is not specified. |