Why the Expand Macro Works to List Small FAQs… but Fails at Scale (and What to Use Instead)

[#1]

Frequently Asked Questions are a vital part of your Confluence knowledge base, onboarding spaces, product documentation, you name it. Many teams lean on a combination of FAQ templates and the Expand macro to display questions and answers.

Expands are a viable option, but are they the only one? Are they good enough? And are there any other better alternatives? In this post, we will answer these questions and then some.

Let's start with the pros of using the Expand macro for FAQs:

If so many teams rely on the Expand macro to list FAQs, they better have their reasons. And they do. These reasons can be summarized into two simple words: Convenience and ease of use.

 If your aim is to embed and list FAQs within any given Confluence page without the hassle and without Marketplace apps, you just can't find a better alternative than the Expand macro. All you have to do is type /Expand, include the question as the title, and the answer as the content body. Repeat the process for as many FAQs as you have. That's it really. 

But here’s the catch: when something is too easy to set up and work with, there’s usually a tradeoff. This leads us to the cons…

Cons of using Expand macro for FAQs 

Limited filtering & dynamic options: 

Adding FAQs within your expands is a manual process. You don't dynamically pull questions and answers from a centralized FAQ hub, you just type or copy paste them.

Additionally, with expands, you can only add the question and answer without any categorization or metadata. For small FAQs, that's completely fine. For more rich and advanced ones, this can easily become an issue as teams navigating embedded FAQs will struggle with context.

Limited reuse

FAQs are all about reusability. One might argue that you can simply wrap your expands within an Excerpt and reuse it across your different pages with the Insert Excerpt macro. Unfortunately, you can’t do this in Confluence Cloud as it doesn’t allow nested macros inside Excerpts. If you try, the Expand ends up outside the Excerpt, breaking your layout and defeating the purpose of centralized reuse. 

But still, even if you can as is the case in Confluence Data Center. This solves one issue, the pulling of data, but filtering limitations still remain. You still can't dynamically filter FAQs by category, contributors, or other metadata. As a result, the FAQ content remains largely static and difficult to scale.

A practical workaround to reuse your FAQs is to create a dedicated FAQ page where each question is an Expand. Then, on other pages, you can pull the entire source page using the Include Page macro.

The limitation here is that Include Page works at the page level. You can’t reuse individual questions (only the entire FAQ block). And once included, the content can’t be edited from the target page, only from the source. While this technically enables reuse, it’s not always the most flexible or elegant solution.

Scalability challenges:

Expand macros work well when you only have a handful of questions. But when your FAQ library grows, managing them manually across multiple pages becomes difficult. Adding new questions, attaching metadata, and keeping everything consistent quickly turns into a full-time effort.

So are there any alternative macros to expand that can solve these issues? Of course there are. You simply need a dedicated solution that is specifically designed for FAQ management.

Introducing the FAQ Listing macro (part of FAQ for Confluence Cloud)

I know what you're thinking! Another app to fill yet another gap. But bear with me. If you’ve ever struggled with manually maintaining Expand macros, or tried reusing them through workaround, you know that a dedicated solution can save a lot of time. In this section, we'll check why you need the FAQ Listing macro, and how you can easily set it up.

Pull your FAQs from one centralized hub: 

Unlike the Expand macro, the FAQ Listing macro is tied directly to your FAQ hub. That means you only add your questions and answers once in a central location, and they can be displayed across multiple pages dynamically, without copy-pasting or repeated updates.

Dynamic filtering:

When embedding your FAQs with Expand, you can only add the question and the answer. The FAQ Listing macro allows you to add more context and relevance with advanced filtering options. 

You can filter FAQs by space, container, and category. This makes it easy to show different FAQ lists in different contexts. On one page, show only FAQs from a certain category. On another, show a completely different set, all pulled dynamically from the same hub.

Designed to scale

Whether you have ten questions or hundreds, the FAQ Listing macro handles them with ease. Unlike Expand, which becomes tedious and error-prone as the number of questions grows, the macro is built to scale. Large, complex FAQs are easy to manage, update, and display, with minimal repetitive updates.

Comparing both options side-by-side

Now that we’ve discussed each option to list your FAQs, let’s compare them side by side based on a variety of criteria:

Criteria/macro	Expand macro	FAQ Listing macro
Ease of setup	Very easy with a minimal learning curve. Type /Expand, add the question and answer.	Easy. Type /FAQ Listing and specify your filters.
Filtering & dynamic display	None. FAQs must be added manually with no filtering options.	Full dynamic filtering. You can filter by space, container, and category.
Centralized management	None. Each expand lives within its page. Use Excerpt macros on Data Center or Include Page macro on Cloud to have an FAQ within a source page.	Centralized FAQ hub. FAQs are pulled directly from there.
Maintenance effort	High and error prone. Every change requires manual updates on every page.	Low. Maintain FAQs once in the central hub and all embedded lists update automatically.
Scalability	Poor. Managing large FAQs becomes challenging.	Designed for large and metadata-rich FAQs.
Best for	Small, static FAQ lists embedded in a page.	Full-featured, scalable FAQ management across spaces and pages.

And there you have it. The Expand macro is a suitable solution when listing FAQs. It’s convenient and easy to set up. When it comes to advanced management and display,  you’re going to have to rely on dedicated solutions designed for FAQ management. The FAQ Listing macro is an alternative that you might want to consider if your FAQs grow, you want more filtering options, and less manual effort.

The macro is available on FAQ for Confluence Cloud. Make sure to give it a try.