We all love Confluence macros. They’re the difference between structured, easy to navigate pages or a confusing mess. But with the variety of both built-in and third party macros, we’re often prone to misuse some of them resulting in an overall bad experience and, of course, low engagement rates.
In this article, we will talk about the common mistakes when using Confluence macros, and of course, how to fix them.
Hiding Important Information Behind Clicks
You always want to give your readers control over what to show or hide within a page. But this control should depend on the type of content you’re displaying. A common mistake we see Confluence users make is hiding IMPORTANT information behind a tab or a collapsible section. Sure both macro, and similar ones, are tempting: They’re handy when it comes to organizing large chunks of text, and they’re visually appealing (with the right customization options). But using them comes with a serious downside: content that’s hidden can be easily missed.
If something is critical such as onboarding content, project updates, or process steps, it shouldn’t be hidden behind a click. Many users won’t expand every section or open each tab, especially if there’s no clear indication that they should.
So what should I use instead? There are a variety of macros in Confluence designed to help you highlight content. I personally use panels a lot. Their overall design coupled with advanced displaying options helps in drawing attention. Another way (the old fashioned way) is to leverage the native text editor in Confluence. It’s quite rich in terms of formatting options and easy to master.
The rule of thumb: never hide content people need in order to act, understand, or decide. Use visibility to support flow, not obscure it.
Using The Wrong Combinations When Nesting Macros
A panel inside an expander inside a tab. Reading this is quite painful, just imagine navigating this maze. Although we kind of have the ability to nest macros, it doesn’t mean we should.
We often do this with good intentions though but the outcome often renders poorly, confuses users, and makes content frustrating to edit later.
So what should we do instead? To answer this question, we should understand why we nest macros in the first place. Simply put, we nest macros to create structured layouts and provide context to readers. We want our content to be properly organized, convenient to access and navigate through. With this said… which macros or features can fit the bill? And which nesting combination should you avoid?
The first thing you should consider is layout columns. They come natively in Confluence, they’re quite clean, and act as your first layer. Once in place, limit yourself to one structural macro: Think expanders, content lists, and maybe even tabs (ideally when you have two columns otherwise they might look off).
A simple rule of thumb is to avoid nesting more than one structural macro inside another. Instead try adding a contextual macro within a structural one. That means if you’re using something like an expand, don’t tuck tabs or additional panels inside it. Likewise, if you’ve already organized your content with tabs, don’t try to nest collapsible sections inside every tab.
Clean, Functional Nesting Examples
- Expand inside a column layout: Each column holds a different FAQ category for example. Inside each column you will list your questions using collapsible sections.
- Button inside a tab: Buttons add context rather than structure which makes them ideal to be nested.
- Info macro inside a panel: A nice way to highlight sub-notes within a callout area — especially if the panel is used for section-level guidance.
These combinations work because they’re simple, predictable, and each macro has a clear role: layout, structure, or emphasis.
Nesting to Avoid
- Tabs inside expanders (vice-versa): Nesting two structural macros simply doesn’t work. This often creates a frustrating experience where users have to click to reveal, then click again to explore.
- Expanders inside panels: Panels are ideal to draw attention. Expanders are designed for supplementary information. That’s two macros serving two opposite purposes.
- Tabs inside tabs: This one might get you fired. There’s rarely a good reason to do this. It’s disorienting and usually a sign that your content structure needs rethinking.
Leaving Confluence Macros & Layouts Unexplained
My Marketing professor always told us: Do not make assumptions. And this holds true when creating good and well-structured content.
You may know exactly how your macros are supposed to work. Your readers probably don’t. And that’s why you need to guide them. Some might think if I have to explain how the macro works, then there’s a UX flaw. But that’s only partly true. Even great designs benefit from a signpost.
A layout with five columns, tabs across the top, and a bunch of embedded reports and dashboards may make perfect sense to you because you built it. But for a new hire or an external user, it’s just a busy page with no obvious flow and point to start from.
If you ever came across a basic Confluence template, then you probably have noticed the remarks and placeholders telling you how to use each macro. That same principle shouldn’t stop at the template level, it should carry through into the content itself. If guidance is helpful while building, it’s just as essential for the people consuming what you built.
So give your users a quick tour. A one-sentence explainer at the top goes a long way:
“Use the tabs below to view the onboarding path”
Or above a collapsible section:
“Click each step to reveal detailed instructions.”
And if you’re thinking this is just over-explaining—remember that clarity isn’t hand-holding. It’s respect for your reader’s time.
Cramming Too Much Into a Single Page
Just because Confluence allows endless vertical space doesn’t mean you should use it. Pages with too much text, too many sections, or overloaded dashboards feel overwhelming and quickly get abandoned. But how long is too long? 2 Mb Confluence pages according to Atlassian support. This is when the page renders slowly and macros tend to break occasionally.
So how to deal with this?
First, scan your page to look for ways to group large chunks of text. You can use tabs for related sections, collapsible sections for supplementary information, etc.
Still long? Then it’s time to break it up. Divide content into smaller, clearly labeled child pages. Let a parent page act as the overview or entry point, with links guiding readers deeper as needed.
A smaller page is faster to load, easier to maintain, and far more user-friendly.
Blindly Copy-Pasting Macros Without Updating Them
I am guilty of this one. When working on multiple macros, we’re talking 100s over a long page. It’s tempting to copy an existing macro and reuse it. But many users forget to update the macro’s configuration and even content.
Whenever you duplicate a macro, review everything inside it. Did you update the labels? The target of the links? The field names in Page Properties? If not, you’re creating future confusion.
Better yet, create a reusable Confluence template that prompts users to fill in key fields. Add instructional text inside macros (you can use inline comments or panel hints) to remind people what to update.
Copy-pasting without checking is fast but not sustainable.
Can I leverage AI to Avoid All of These Mistakes?
Yes you can! If you’re knee deep into chaotic Confluene pages and you want a fast and efficient way to clean everything up, then AI is the answer (to use responsibly, of course). Morph is an AI-Powered content formatting app designed to help you instantly transform raw or unstrcutured content into polished one. Here’s how it works:
Full page transformation: Got an old knowledge base article or project doc that’s basically a giant scroll? Morph can break it into logical sections and apply the right macros (like tabs, expands, or panels).
Selective enhancements: Highlight a specific section and let Morph optimize just that part. It might clean up a list, convert instructions into expanders, or highlight a key note using panels all while respecting macro hygiene principles.
The Takeaway: Keep It Simple, Keep It Clear
Confluence macros should help readers not distract or confuse them. Good macro hygiene means making intentional design choices that make life way easier for everybody involved: the reader, and content editor. Use visibility wisely. Avoid excessive nesting. Make sure dynamic content is scoped and explained.
Above all, remember that your goal isn’t to show off your macro skills. It’s to make your information useful, usable, and easy to engage with. Your teammates will thank you. And so will your future self.
For more tips on how to properly format your Confluence pages, make sure to check out the blog and detailed YouTube tutorials. And to explore more macros in Confluence, give Content Formatting Toolkit a try.
