This content applies to the legacy editor and the new editor.
Labels are key words that you can add to pages and attachments to make them easier to group and find. For example, you could assign the label accounting to all accounts-related pages on your site. You can then browse all pages with that label in a single space or across the site, display a list of pages with that label, or search based on the label.
You can also use labels to categorize spaces. Head over to the page to learn more about using space labels to keep Confluence neat and organized.
Label a page
Any user with permission to edit a page can add labels to it. Any existing labels appear at the bottom-right of the page, below the page content.
To add a label to a page:
- While viewing a page or blog, choose the edit icon
You can also do this while creating or editing a page, by choosing the label icon at the top of the page. next to the list of labels or press L on your keyboard.
- Enter a new label (existing labels are suggested as you type), then click Add.
Label an attachment
- Do either of the following:
- On the page that contains the attachment: Go to > Attachments
- Click on the space name in the navigation. Click Space Settings (, > Content tools tab > Attachments )
- Choose the edit icon beside the list of labels and type in a new label (existing labels are suggested as you type), then click Add.
You can also add labels in a list of attachments displayed by the Attachments macro, by choosing the edit icon beside each label.
Labels do not accept spaces, and are lower case only. This means that you can type in multiple labels at once just by adding spaces between each label, and that any capitals will be automatically converted to lower case. If you want to use a label that has more than one word, try using an underscore or hyphen, like so: this_is_a_label or this-is-a-label.
View all content with a specific label in a space or site
When viewing a page or post that has labels, or that displays the Attachments macro, choose any label to go to the Labeled content page for that space. This displays a list of all the pages in that space, with that label. To see all content on the site with that label, choose the cog icon > See content from all spaces.
View all labels in a space or site
From the labeled content page, click on the cog icon > all labels to see all the labels in that space.
Alternatively, use the following URL. Make sure you use your own site address, and replace SPACEKEY with the actual space key of a space.
At the top of the page, there'll also be an option to see all labels across the site.
View popular labels in a space or site
From the other views, you can click on the cog icon and select Popular Labels. This displays a word cloud, where the bigger a label is displayed, the more popular it is. There's also an option to see popular content across whole site.
Screenshot: The Labeled content page
Search by label
You can use the
labelText: prefix to search for content that has a specific label. For example, if you're looking for pages with the label chocolate, type
labelText:chocolate into the search field in the Confluence header. For more examples of searching by label, see Confluence Search Syntax.
Search for labeled pages using a URL
In your browser's address bar, enter the following URL and press enter: http://<your.Confluence.site>/label/jon+snow
The Labeled content page will load, displaying all pages that have both of the labels jon and snow. Replace jon and snow with the label(s) you want to search for, and separate multiple labels with a
When viewing page, blog post, or attachment labels, an x appears alongside each label. Choose the x to remove the label. To delete a whole category of labels, you'll need to remove that label from everywhere it appears.
If you have deleted pages that contain a label, you may need to purge the deleted pages from the space's trash to ensure that the label disappears too.
Use macros to categorize or display labels
Using labels and macros, you can categorize pages, blogs, and attachments, and display them in Confluence in a number of ways.
As an example, you could label all pages relevant to the marketing team with marketing, and then add more specific labels like online, mobile, and physical to different pages where required.
You could then use the Content by Label macro to display different combinations of pages with the marketing label. Some combinations you could use would be:
- All pages with the label marketing.
- Pages which have all of the following labels: marketing, mobile, and online.
- Pages with either the mobile or online labels, in the Marketing space.
Alternatively, if you're working on a project across multiple teams, you can label everything to do with the project with that project name, and use a label to display all that content in one space.
Below you'll find a list of macros that use labels in different ways. See which ones work best for you.
Content by Label macro
The Content by Label macro displays a list of content marked with specified labels.
Content Report Table macro
The Content Report Table macro displays a set of pages and blog posts in tabular format, based on the specified labels.
Labels List macro
The Labels List macro lists all labels of a space, grouped alphabetically.
Navigation Map macro
The Navigation Map macro renders the list of pages associated with a specified label as a navigation map.
Popular Labels macro
The Popular Labels macro displays popular labels in a word cloud.
Recently Used Labels macro
The Recently Used Labels macro lists labels most recently used in a specified scope - global (site), space, or personal.
Related Labels macro
The Related Labels macro lists labels commonly associated with the current page's labels.