Skip to main content

Expand Macro for Confluence: Collapsible Sections Compared (Native vs Styled)

· 4 min read
NGPilot

Long pages die from scroll fatigue. Onboarding checklists, troubleshooting trees, API reference details, legal disclaimers — content that only some readers need some of the time is the canonical use case for collapsible sections. Confluence ships a native expand macro for exactly this, and for many pages it's enough.

This guide covers how the native expand works, where teams typically outgrow it, and what a styled accordion macro adds — so you can pick per page, not per vendor.

The native expand macro: how it works​

The built-in macro is one slash command away:

  1. Edit a page, type /expand
  2. Enter a title — this becomes the clickable toggle text
  3. Put any content inside: text, tables, images, even other macros
  4. Publish — viewers click the title to expand or collapse

What it does well:

  • Zero setup — works in every Confluence Cloud instance
  • Nested content support — anything you can put on a page can go inside
  • Predictable, accessible toggle behavior
  • Indexes normally in Confluence search

Where teams outgrow it:

  • One section per macro. A FAQ with twelve questions means twelve separate macros to create, align, and reorder — each with its own styling drift.
  • No accordion mode. All native expands can be open simultaneously; there's no "close others when one opens" behavior.
  • Plain styling. The title renders as plain text — no accent color, no icon, no visual hierarchy between sections.
  • Collapsed-by-default exports. PDF export of a page full of collapsed expands exports the hidden content in an inconsistent way, which bites print/compliance workflows.

When you need an accordion: the styled Expand macro​

When a page has repeated collapsible sections — FAQs, multi-step guides, release notes grouped by version — what you actually want is one macro holding many sections, with consistent styling and accordion behavior. That's the shape of the Expand macro in Content Formatting Macros & Page Builder for Confluence:

  • Multiple sections in one macro — add as many as you need, drag to reorder, rich text in each
  • True accordion mode — "Allow Multiple Open" off means opening one section closes the others
  • Per-section control — title, per-section emoji or character icon, and an "Initially Open" toggle per section (useful for exports: print the sections that matter)
  • Five design styles — Simple, Bordered, Shadowed, Gradient, or Minimal, with an accent color picker and content padding control
  • Animation — smooth expand/collapse (100–1000ms) instead of an instant jump

The mental model: native expand is a single toggle; a styled accordion is a content structure. Pages with 2–3 toggles rarely need more than native. Pages with 8+ sections benefit from treating the set as one editable unit.

Which should you use, per page type​

Page typeRecommendation
Hiding one long table or code sampleNative expand — nothing to gain from more structure
FAQ with many Q&AsStyled accordion (or a dedicated FAQ macro)
Troubleshooting decision treeStyled accordion with "one open at a time" so readers follow one path
Meeting notes with optional detailNative expand
Release notes grouped by versionStyled accordion — drag-reorder as versions change
Onboarding checklistStyled accordion with icons per phase

Common questions from teams​

"Does collapsed content hurt SEO?" Content inside collapsible sections is indexed by Google and by Confluence search — collapsing is a presentation choice, not a content hiding mechanism. (That said, critical keywords your page should rank for belong in the open parts of the page, not only inside toggles.)

"Can I nest expand inside expand?" Yes, in both the native macro and the styled accordion's rich-text sections. Nested accordions two levels deep are usually a sign the content wants to be separate pages, though.

"How does this interact with page exports?" Native: collapsed sections may export inconsistently depending on export path. Styled accordion: the "Initially Open" toggle decides, which gives you deterministic print output.

Related guides