Content by Label Macro

The Content by Label macro is used to display lists of pages, blog posts or attachments that have particular labels.  It's great for collecting related pages together and filtering out content that you don't want to see.

For example, you could use this macro to display a list of all pages that have the label 'feature-shipped' and include the word 'Blueprint', or to list any pages with the label 'meeting-notes' that you've been mentioned in.

Here's how the macro looks on your page:

And here's how you would set it up in the macro browser:

Using the Content by Label Macro

To add the Content by Label macro to a page:

  1. In the Confluence editor, choose Insert > Other Macros
  2. Find and select the required macro

Speeding up macro entry with autocomplete: Type { and the beginning of the macro name, to see a list of suggested macros. Details are in Autocomplete for links, files, macros and mentions.

To edit an existing macro: Click the macro placeholder and choose Edit. A macro dialog window will open, where you can edit the parameters of the macro.

CQL fields

CQL (Confluence Query Language) is a query language developed for Confluence, which you can use in some macros and the Confluence search. Confluence search and CQL-powered macros allow you to add fields to build up a search query, adding as many fields as you need to narrow down the search results.
  Here are some tips...
  • Use the Add Field link to add additional filters to your query. Add as many fields as you need.
  • For an OR search, specify multiple values in the same field.
    So to show pages with 'label-a', 'label-b' or both you'd put 'label-a' and 'label-b' in the same Label field, like this:
  • For an AND search, add more than one field and specify a single value in each.
    To show only pages with label-a and label-b you'd put 'label-a' in one label field, then add a second Label field to the macro, and put 'label-b' in the second one, like this:

    Put simply, OR values are entered in the same field, AND values are entered in different fields. 
    Only some fields support AND.  If the field does not support the AND operator, you won't be able to add that field more than once.  
  • For a NOT search, enter a minus sign (-) before the label. This will exclude everything with that label.

You can use the following CQL fields to build your query:

Field Required Description Operators
Label Yes

Include pages, blog posts or attachments with these labels.

OR (multiple values in the same field)

AND (multiple Label fields)

With ancestor No

Include pages that are children of this page.

This allows you to restrict the macro to a single page tree.

OR (multiple values in the same field)
Contributor* No

Include pages or blog posts that were created or edited by these people.

OR (multiple values in the same field)
Creator No

Include items created by these people.

OR (multiple values in the same field)
Mentioning user No

Include pages and blog posts that @mention these people.

OR (multiple values in the same field)
With parent No Include only direct children of this page (further sub-pages won't be included) EQUALS (one page only)
In space No Include items from these spaces. OR (multiple values in the same field)
Including text* No Include items that contain this text. CONTAINS (single word or phrase)
With title No Include items that contain this text in the title. CONTAINS (single word or phrase)
Of type* No Include only pages, blogs or attachments. OR (multiple values in the same field)

* You can add these fields in CQL-powered macros, but not in search. You can still filter using the same information in search, but they're managed by equivalent search filters so don't appear in the Add a filter menu.

Macro display options

These options control how the macro appears on your page.

Parameter Default Description
Sort by Modified

Sort the list by title, the date it was created, or the date it was last modified. If you don't select an option, CQL default ordering by relevancy is used.

Reverse sort False Sort the list descending instead of ascending (Z - A, earliest - latest)
Maximum number of pages 15 Limit the number of items to include in the list.
List title Blank Include an optional heading for the macro
Show labels for each page True Show or hide the labels applied to each item
Show space name for each page True Show or hide the space name for each item
Display excerpts False Show an excerpt from the page or blog post (the page or blog post needs an excerpt macro to be able to show an excerpt).

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport