The Insert Confluence List Macro: what it is, what’s tricky right now, and how to get good results.

[#1]

This morning I saw a question about the Insert Confluence List Macro and had to try it myself. It wasn’t behaving the way most of us would expect, and I couldn’t find any documentation. So, I’ve captured a concise guide of what it does today, its current limits, and practical ways to get consistent results. If the Documentation doesn't exist, Create it!

TL;DR: The Insert Confluence List Macro is helpful in spirit, but today its search doesn’t respect CQL and its filters are limited—often returning far more than you wanted. Until it improves, you can use Search with filters → Smart Link (steps below).

What the macro is (today)

The Insert Confluence List Macro adds a live list of content to a page for quick “show some pages” use cases.

Why folks want this macro

• Instant table with helpful columns out of the box:

  • Type | Title | Space | Description | Owner | Last updated

• Clean, lightweight, and fast to add.

What’s tricky right now

• No CQL field (text = keywords, not precise filters).

• Too few filters (can’t reliably do space + label + type).

• Over-inclusive results (often pulls content from across the site).

• Docs gap (little/no official documentation yet).

---

A reliable workaround: Search with filters → Smart Link

This uses Confluence’s built-in search filters (the sliders icon) and then surfaces that exact result set on your page.

Steps

1. Click the Search bar.

2. Click the sliders icon (hover text: “Open a full page search with more filter options”). This opens the filter panel/dropdown.

3. Apply filters (examples):

   • Space

   • Type: Pages & live docs (or your preferred type)

   • Labels

   • Last updated / Owner / Contributor / Status / Relevance, etc.

4. Press Enter or click View all results (if shown) to open the full results view.

5. Copy the URL from your browser’s address bar.

   • Pattern example:
     https://yourinstance.atlassian.net/wiki/search?product=confluence&spaces=URKB&labels=LABEL1

6. Paste that URL on your page if it doesn’t default to list you can change it to display as a list.

Why this works: The Smart Link preserves the exact filters you set, so the list people see matches your intent.

---

Constructive feedback for the product team

In the spirit of turning a good idea into a great tool:

1. Add a true “Advanced (CQL) field.”

2. Match Search filters (Space, Type, Labels, Owner/Contributor, Status, “Only verified,” “Show archived,” etc.) for parity and predictability.

3. Publish lightweight docs with capabilities, limits, and examples.

---

Closing

The Insert Confluence List Macro has real potential to speed up content curation. Until the macro supports more precise filtering, the Search with filters → Smart Link pattern is the most dependable way to share a focused, living list—without surprise results.

If you’ve found other reliable setups (or niche cases where the macro shines), please share—let’s build a mini playbook for everyone.

[Harrison Ponce]

Here's a related JAC suggestion open about this if you want to vote on it:

• CONFCLOUD-79626: Ability to filter Insert Confluence List macro with space

[Lars Maehlmann]

Great article, @Brandi Guess!  

I followed your instructions, and it worked well. However, I added a specific creator and only one user to the query, yet I received a list of different creators. I was also surprised to find that after reviewing a few pages, they displayed a different owner/creator.  

https://yourinstance.atlassian.net/wiki/search?product=confluence&spaces=URKB&labels=LABEL1%creator=accountId

Has anyone else had this issue? I'm also surprised that I can't sort the content by column.

Cheers,

Lars

[Brandi Guess]

@Lars Maehlmann I am so happy I was able to help. I am unsure about the way it is listing but I will test it out and play around and see what I can find.