Display Pages with Label Macros

Add, Remove and Search for Labels

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

Using labels and macros, you can categorize pages and then 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 with all of the following labels: 'marketing', 'mobile', and 'online'.
  • Pages with either the 'mobile' or 'online' labels, in the Marketing space.

There are a lot of ways you can filter the content, making it easier for you to find content that's relevant to you.

Other label macros

Here are some other macros that use labels, and can help you categorize and display your content.

Navigation Map macro

The Navigation Map macro renders the list of pages associated with a specified label as a navigation map.

Related Labels macro

The Related Labels macro lists labels commonly associated with the current page's labels.

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.

Recently Used Labels macro

The Recently Used Labels macro lists labels most recently used in a specified scope - global (site), space, or personal.

Popular Labels macro

The Popular Labels macro displays popular labels in a list or in a heatmap (also called a cloud).

Increase label processing limits in macros

You can configure the Number of Labels to Display field for the Label List, Recently Used Labels, and Popular Labels macros. The default limit depends on the macro.

When searching for labels to display in a macro, Confluence processes 1,000,000 labels by default. Admins can increase or decrease this limit by adding the system property to the configuration file.

For the Labels List macro:

confluence.macros.advanced.listlabels.labels.max.to.process

For the Recently Used Labels macro:

confluence.macros.advanced.recently.used.labels.max.to.process

For the Popular Labels macro:

confluence.macros.advanced.popular.labels.max.to.process

Increasing the system limit of labels to process is helpful when your Confluence instance has a lot of labels, and searching for them doesn’t return all possible results. However, this may slow down performance.

Last modified on Aug 5, 2025

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.