The List by Label macro is used to display lists of pages, blog posts or attachments that have particular labels. Note that this macro’s name was recently changed from “Content by Label”.
When would you use List by Label macro?
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:
Where is this used in our instance?
Many articles include the List by Label macro to drive users to related content. Our configuration ranges from displaying all content with a selected label to displaying only 5 articles with a link to additional related content. You can see it in action on Graduation & Commencement, and this macro can be used on any page where it makes sense to provide additional related content.
Use the List by Label macro
To add the List by Label macro:
When editing, select Insert from the toolbar
Find the macro by name and select it
Configure it as needed
You can also type / on the page to bring up the same list you'd see by selecting from the toolbar. Continue typing the name of the macro to filter the list.
To edit the List by Label macro:
Select the macro placeholder.
Select the Editicon to open the configuration panel.
Configure the parameters. Your changes are saved as you go.
Resume editing the page, and the panel closes.
You can also select the centered , medium-width , and full-width icons to adjust the width of some macros. Select the trashcan iconto remove the macro.
CQL filters
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 filters to build up a search query, adding as many filters as you need to narrow down the search results. To add a filter to your query, select the Add a filter link.
Filter
Description
Operators
Filter
Description
Operators
Label*
Returns pages, blog posts or attachments with these labels.
OR (multiple values in the same filter)
AND (multiple Label filters)
With ancestor
Returns pages that live under this page in the page tree.
This allows you to restrict the macro to a single page tree.
OR (multiple values in the same filter)
Contributor**
Returns pages or blog posts that were created or edited by these people.
OR (multiple values in the same filter)
Creator
Returns items created by these people.
OR (multiple values in the same filter)
Mentioning user
Returns pages and blog posts that @mention these people.
OR (multiple values in the same filter)
With parent
Returns only direct children of this page (further sub-pages won't be included)
EQUALS (one page only)
In space**
Returns items from these spaces.
OR (multiple values in the same filter)
Including text**
Returns items that contain this text.
CONTAINS (single word or phrase)
With title
Returns items that contain this text in the title.
CONTAINS (single word or phrase)
Of type**
Returns only pages, blogs or attachments.
OR (multiple values in the same filter)
AND, OR, and NOT operators
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 filter 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 filter, AND values are entered in different filter. Only some filters support AND. If the filter doesn't support the AND operator, you won't be able to add that filter more than once.
For a NOT search, enter a minus sign (-) before the label. This'll exclude everything with that label.
This field is required in CQL-powered macros.
** You can add these filters in CQL-powered macros but in search they're part of the standard search filters, so they don't appear in the Add a filter menu.
Macro display options
Parameter
Default
Description
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. This can be any value up to 500 pages.
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
Allows you to include a short excerpt under each page in the list. Choose between:
None - no excerpt will be displayed.
Simple - displays the first line of text contained in an Excerpt macro any of the returned pages. If there is not an Excerpt macro on the page, nothing will be shown.
Rich content - displays the contents of an Excerpt macro, or if there is not an Excerpt macro on the page, the first part of the page content, as formatted text, including images and some macros.
