Content by Label Macro
Screenshot: The Content by Label macro showing all pages that contain the label "printer".
For general information about using labels in Confluence, see Add, Remove and Search for Labels.
Add this macro to your page
To add the Content by Label macro to a page:
- From the editor toolbar, choose Insert
> Other Macros. - Choose Content by Label from the Confluence content category.
- Enter the labels you want to use as the basis for your query.
- Add additional filters to further narrow your query. These filters use CQL.
- Choose Show to change the macro parameters. These are optional.
- Choose Insert.
You can then publish your page to see the macro in action.
Screenshot: Using CQL to search for content with a particular label in two spaces in the Content by Label macro
CQL filters
Use the Add a filter link to add more filters to your query.
- 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.
You can use the following CQL filters to build your query:
| Filter | Description | Operators |
|---|---|---|
| Label* | Include pages, blog posts or attachments with these labels. | OR (multiple values in the same filter) AND (multiple Label filters) |
| With ancestor | 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 filter) |
| Contributor** | Include pages or blog posts that were created or edited by these people. | OR (multiple values in the same filter) |
| Creator | Include items created by these people. | OR (multiple values in the same filter) |
| Mentioning user | Include pages and blog posts that @mention these people. | OR (multiple values in the same filter) |
| With parent | Include only direct children of this page (further sub-pages won't be included) | EQUALS (one page only) |
| In space** | Include items from these spaces. | OR (multiple values in the same filter) |
| Including text** | Include items that contain this text. | CONTAINS (single word or phrase) |
| With title | Include items that contain this text in the title. | CONTAINS (single word or phrase) |
| Of type** | Include only pages, blogs or attachments. | OR (multiple values in the same filter) |
* 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.
Change the macro parameters
Macro parameters are used to change the behaviour of a macro.
To change the macro parameters:
- In the editor, click the macro placeholder and choose Edit.
- Update the parameters as required then choose Insert.
Here's a list of the parameters available in this macro.
| 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:
|
| Exclude current page | False | Allows you to exclude the page the macro appears on from the list. This is useful when the current page contains the same labels as the pages you want to include in the list. |
Where the parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro browser, it will be listed below in brackets (example).
Other ways to add this macro
Add this macro as you type
Add this macro using wiki markup
You can't use wiki markup to add this macro.