Macros in Confluence are powerful features that you can use to take the functionality and design of Confluence content to the next level. Probably the most useful and unfortunately often underestimated macros are "Page Properties" and "Page Properties Report". They allow you to transform static Confluence pages into dynamic overview pages.
Learn the best practices for creating them here!
Updated August 2026: Atlassian has renamed both macros in Confluence Cloud. They are now the Content Properties macro and the Content Properties Report macro. What they do has not changed, and in Confluence Data Center they are still called Page Properties. This guide covers both names.
The Page Properties macro and the Page Properties Report macro are the perfect team for turning static Confluence pages into dynamic overviews. This guide walks through setting both of them up, the limits worth knowing before you build on them, and when a Confluence database is the better tool.
The Page Properties macro in Confluence allows you to add metadata to a Confluence page in table format. This metadata can then be displayed on a parent page using the Page Properties Report macro. This way, you transform static pages into automatically updated overviews that make project management much easier. These two macros only develop their full strength together.
If you search for the macros with / in Confluence Cloud, you will now find them as Content Properties and Content Properties Report. Atlassian changed the name because the macros no longer work only on classic pages, but also on live docs, blog posts and attachments.
| Former name, still used in Data Center | Name in Confluence Cloud |
|---|---|
| Page Properties macro | Content Properties macro |
| Page Properties Report macro | Content Properties Report macro |
| Works on pages | Works on pages, live docs, blog posts and attachments |
Nothing else changes for you. Existing macros on your pages keep working, the parameters are the same, and Confluence Data Center still calls both of them Page Properties. So search for the new name in the Cloud editor if the old one does not come up.
As soon as you have stored a lot of common information on one or more pages in Confluence and want to display it compactly and dynamically in one place, the Page Properties macro is the right one for you.
The interaction of both macros could look like this, for example:
Page Properties macro on a child page:
Page Properties Report macro on the overview page:
Here comes the best practice guide on how to get this result.
Keep in mind that you need two steps to integrate the dynamic report on your Confluence page. First, you need to add the Page Properties macro to one or more pages, and second, retrieve the information using the Page Properties Report macro.
1. First, create a Confluence page with a table. In the left column of the table, add the headings that will later be seen on the index page. What is organized vertically here will later be displayed horizontally in the Page Properties Report. We will start with the use case of project management and add status, stakeholder, owner, start date and deadline of a project.
Make sure that the Header column table option is selected. Otherwise, there will be problems with the display in the Page Properties Report later. One thing to watch: the table can have a header row or a header column, but not both. The report macro reads only one of the two per macro.
2. Thereafter, create the Page Properties macro and insert your table here. To achieve this, type “/” on the Confluence page, start typing the name “Page Property” (in Cloud: “Content Properties”) and select the appropriate macro to insert the table.
3. Optionally, you can assign an ID to this macro at this point. This is always useful if you have multiple Page Properties on a page. Use the same ID consistently on every page that should end up in the same report, because the report macro accepts exactly one ID.
4. To easily find your page and your page properties afterward and implement them in the index page, add a label to your page. In edit mode, select the three-dot menu … (More actions) in the top right and choose Add labels. Type the label name, select it from the suggestions, then publish the page. The screenshot still shows the earlier menu, which was called Options at this point.
Alternatively, you can add a label in view mode by selecting Add label at the bottom of the page, or through the Details icon in the floating action bar at the bottom right and then + next to Labels.
Now that the preparation is done, you can easily embed your table on a new page using the Page Properties Report macro.
In principle, you can display any number of Page Properties macros on a single page. Based on assigned labels and IDs, you choose what exactly should appear in the report.
The resulting dynamic table looks like this:
3. Next, you can optimize the macro according to your requirements. Among other things, you can choose which columns are displayed in your report:
This screenshot shows the older configuration dialog, where every setting was visible at once. In Confluence Cloud the same options now sit behind More options; what the column selection and the count do has not changed. Confluence Data Center still looks like this.
You can also display the sorting or the number of comments or likes in a table. Discover all the possibilities in Atlassian’s guide.
The report automatically has a link to the Confluence page where we included the Page Properties macro. The great advantage is that as soon as something changes in the table on the Page Properties page, the changes are automatically updated in the report. This way, static tables become dynamic management helpers, and you never miss it when the status of a project changes.
For better visualization of your content, you can include macros like status, date or mentions in your list, but only in the right column. After all, the left column is used as the column header in the report.
The result in the report will look like this:
Be careful not to include too many macros in your table, though. Otherwise, the Page Properties Report will become cluttered.
In the editor the macro is now listed as Content properties report (Page properties report), so Atlassian carries both names side by side. Its configuration panel is deliberately short: Add label(s) is the only required field, and below it Space comes preset with a Current space chip. Everything else sits behind Add filter(s), and the column and count settings behind More options.
The macro configuration panel in Confluence Cloud. The Space field is preset to Current space, which is why a report stays inside the current space unless you change it.
These filters are available under Add filter(s):
| Filter | What it returns |
|---|---|
| Label (required) | Pages, live docs, blog posts or attachments carrying these labels. Several values are combined with OR. |
| In space | Only content from the spaces you name. |
| With ancestor | Everything that sits below a given item in the content tree. |
| With parent | Only the direct children of an item. |
| Creator / Contributor | Created by, or created or edited by, specific people. |
| Mentioning user | Content that @mentions specific people. |
| With title / Including text | Matches in the title, or anywhere in the content. |
| Of type | Restricts the report to pages, live docs, blogs or attachments. |
With ancestor lets you hang a report off the content tree instead of a label. That saves maintaining labels at all when the source pages already sit under a common parent.
As mentioned before, you can visualize different Confluence pages at the same time in a Page Properties report. This is optimal if you are a project manager managing multiple projects and want to get a quick overview in a simple way.
From this:
To this:
Most of the time teams lose with these macros goes on behaviour that is documented, but only in places you reach after you have already hit the problem. These are the ones that matter.
| Behaviour | What it means for you |
|---|---|
| A header row or a header column | Not both in the same table. The report macro reads only one direction per macro. |
| Exactly one ID per report | Several labels can be combined with OR. Several IDs cannot. |
| No macros in the header column | The left column supplies the column headings and has to stay plain text. |
| 30 results per page | 30 is both the default and the maximum of “Max results per page”; anything beyond it goes into pagination. Data Center adds a ceiling of 3,000 pages. |
| A new property means touching every page | An extra row has to be added to each source table. Past a few dozen pages this becomes real work. |
An empty report almost always has one of four causes. Check them in this order:
When the macro finds nothing at all it simply prints No content found. If rows do appear but the columns are empty or shifted, the cause is the table structure: a header row and a header column both active, or a macro sitting in the left column.
Since Confluence Cloud gained databases, this question comes up with every new use case. Both solve similar problems, but not the same one.
| Page Properties | Databases | |
|---|---|---|
| Where the data lives | Spread across the individual pages | Centrally, in one object |
| Adding a new property | On every source page separately | Once, as a column |
| Field types | Free text plus macros | Real types: text, number, date, tags, user, link, plus a Jira field that pulls in work items dynamically |
| Strength | Every page stays a document with its own context | Sorting, filtering and maintenance in one place |
| Good for | Meeting notes, project one-pagers, decision logs | Inventories, asset lists, structured registers |
A rule of thumb: if the page is the point and the metadata is supporting detail, stay with Page Properties. If the data is the point and the page is just where it gets displayed, use a database. There is no need to rebuild what you already have: Atlassian is still developing the macro, as the rename and the support for live docs show.
Using the two macros Page Properties and Page Properties Report allows you to display important information clearly and dynamically, which saves resources and can generally improve your project management. Furthermore, the two macros help you with
If you work with tables in Confluence a lot anyway, it is worth looking at filtering Confluence tables and sorting them. For page structures you repeat often, templates save a lot of time, because the Page Properties macro is then already in the right place.
Is the macro called Page Properties or Content Properties now? Content Properties in Confluence Cloud, still Page Properties in Confluence Data Center. It is the same macro and existing pages need no changes.
Can one report show pages from several spaces? Yes. The Space field takes several spaces and combines them with OR. Out of the box it holds only Current space.
Why is a column missing from my report? Either it is not selected under “Columns to show”, or the row is missing from the source table on that one page. The report only shows what the source tables actually contain.
Does the macro work on blog posts? Yes, and in Confluence Cloud it now also works on live docs and attachments, as long as they carry the right label.
How many pages can a report show? 30 per page, which is also the maximum the “Max results per page” setting accepts. Everything past that goes into pagination. Data Center adds a ceiling of 3,000 pages that a system administrator can change through pagePropertiesReportContentRetrieverMaxResult.
Our best practices have shown you how to efficiently integrate, configure and use Page Properties macros in Confluence. If you regularly work with a large amount of structured data, these macros are optimal tools to increase your efficiency.
However, each use case is individual and requires individual support. If you would like to walk through your Confluence structure with us, just contact us. The first conversation is non-binding and guaranteed free of charge, and together we will find the most economical way to your success.
Contact us to talk to our experts and have all your questions answered.
Request