If you’ve ever tried to organize a fast-growing Confluence knowledge base, you know the challenges: pages get long, navigation can become messy, and important information easily ends up buried. 

That’s where macros fit in. They’re one of the most powerful — and often underused — tools for making your content more dynamic, searchable, and customized.

At Refined, we build tools that integrate deeply with Confluence and we work with hundreds of teams that manage Confluence sites daily. Over time, we’ve learned where built-in macros shine, where they fall short, and how you can combine them strategically for better workflows. 

In this guide, we’ll break down what Confluence macros are and why they matter, explore best practices, look at which built-in macros you might want to consider, and then show you how to take macros further with specialized tools.

What are Confluence macros?

In Confluence, macros are reusable, customizable components which enhance your pages with functionality beyond basic text and images. You could think of macros as building blocks that let you display dynamic content, automate reporting, integrate external data, or create better navigation for your users.

Here are a few examples of what you can do with macros:

• Create automatic tables of contents
• Embed task reports that pull live data from across your wiki
• Highlight important information using status labels
• Display dynamic page trees for better navigation

Macros can be simple, like showing an excerpt of a page, or advanced, like automating workflows by integrating with Jira, Slack, or third-party tools.

In any case, they are an incredibly useful way to incorporate lots of customization into your Confluence pages.

How Confluence macros can improve your documentation

Macros aren’t flashy add-ons to make your pages look nicer. They fundamentally improve the user experience of your spaces and pages. 

Here are four ways that macros make your Confluence pages more effective:

1. Better user experience & readability

Macros can help you organize content so users find what they need faster. For longer documentation, macros can let you structure pages into scannable sections, making information easier to read through and digest.

2. Improved collaboration & efficiency

Macros do a great job at making team collaboration smoother and work flow faster. You can automatically surface tasks, deadlines, and ownership without manual updates. This stops teams from needing to copy and paste the same content across multiple pages. On top of that, macros help ensure consistent information across pages and spaces, and that info can be more efficiently shared and processed by different collaborators.

3. Empowering Confluence users to help themselves

Combinations of macros can provide users with quick access to the right resources. This improves knowledge accessibility, cutting down on time and energy users spend searching for information or pinging support teams.

4. Support for skimmers and power users

Some readers want every detail while others just need quick answers. Macros let you design for both. You can create structured, scannable layouts where important highlights stand out while still providing deeper context when needed.

Getting started with Confluence macros

Let’s take a look at how to actually start using macros in your Confluence pages.

How to add macros to a Confluence page

1. Edit the page where you want the macro.
   
2. Click the “+” icon in the editor toolbar, or type the slash command (/).
   
3. Choose “View More” to open the macro browser.
   

Select the macro you want, configure its settings, and insert it.

Popular built-in Confluence macros you should know

Naturally, some macros are more widely used than others. Here are three macros we see most teams using regularly:

1. Table of Contents macro

This macro automatically generates a clickable table of contents based on your page’s headings. It’s ideal for long-form documentation.

• Best for: Long documentation pages with structured headings.
• Why we like it: Helps users navigate content faster.
• Pro tip: Keep your heading structure clean. If your TOC is longer than your content, it’s a sign you need to simplify.

2. Expand macro

With this macro, you can hide detailed information under an expandable section to keep your pages clean while still providing depth for those who need it. Users can choose how much they want to see at once by expanding and collapsing the macro.

• Best for: Reducing clutter on policy pages, onboarding docs, FAQs, or any page where not every detail needs to be visible at first glance.
• Why we like it: Keeps pages skimmable while still making full details available for those who need them. This balances readability with completeness.‍
• Pro tip: Don’t hide critical information behind Expand. If it’s something every reader needs to know (like a deadline), keep it visible.

3. Content Tree macro

Previously known as Page Tree, this macro displays a hierarchical menu of child pages. It’s an especially powerful navigation tool in Confluence — use it to create custom knowledge hubs or documentation portals where users can easily browse related content.

• Best for: Creating custom navigation menus for documentation portals, knowledge hubs, and onboarding guides where users need to browse related content without jumping back to the space sidebar.
• Why we like it: It gives structure to sprawling spaces by letting you define a clear entry point and hierarchy. ‍
• Pro tip: Large content trees can overwhelm users, especially if you expose every sub-page. Scope your tree to a well-organized parent page and avoid making readers scroll through dozens of nested items.

Best practices for using Confluence macros

Well-chosen macros reduce friction. Instead of scrolling, searching, or emailing someone for updates, users see the most relevant information where they need it.

But there’s a time and a place for using a macro — and implementing them thoughtfully is what separates a clear, effective page from one that feels cluttered.

When to use Confluence macros

One of the easiest mistakes to make with Confluence is treating macros like decorations. Once you learn how to use them, it’s tempting to drop them everywhere because they’re available in the editor. However, macros are most effective when they serve a clear purpose. A good rule of thumb: use a macro to solve a problem in a consistent and standardized way, not just to make a page look busier. This way, your Confluence users will grow accustomed to the purpose each macro serves — and can adapt them for similar uses.

On the flip side, overusing macros can overwhelm readers and make pages harder to maintain. 

Before adding a macro, ask yourself: Does this macro make the page clearer, faster, or more useful? If the answer is yes, it’s worth including. If not, leave it out. In the long run, intentional use of macros leads to cleaner pages and a much better Confluence experience.

How to customize Confluence macros for maximum impact

Most built-in macros let you tweak settings so they fit the context of your page rather than dumping in raw data. A little upfront configuration can make the difference between a cluttered dashboard and one that delivers instant clarity.

For example:

• Control what’s displayed — Many macros allow you to define how much content to show. For example, limiting a Task Report to the top 20 results instead of listing every open item across your site. This keeps pages scannable and prevents performance slowdowns.
  
  
• Filter by space, label, or owner — Filtering is one of the most important customization tools. A Content Properties Report scoped to a label like “Project-Alpha” will stay fast and relevant, while an unfiltered one may balloon into a massive table.
  
  
• Adjust formatting and layout — Some macros let you choose between list, table, or card-style views. Picking the right display makes a huge difference in readability. Some Marketplace macros, like those in Refined Macro Toolkit, go even further with styling options that align reports and navigation blocks with your site’s design.

Advanced Confluence macros for power users

Once you’ve mastered the basics, Confluence macros become more than formatting helpers. They turn into a set of tools for automation, navigation, and reporting at scale. 

Let’s take a closer look at how to start using advanced macros and get the most out of them.

Getting started with advanced macros

Advanced macros — like Content Properties Reports and Content by Label — let you pull in dynamic data from across spaces, create dashboards that update themselves, and give structure to sprawling wikis.

For admins and power users, the trick is knowing how to configure and combine macros so they solve specific problems without overwhelming your users.

Best practices for using advanced macros

Note that while Advanced macros are powerful, they can also make pages harder to maintain at scale. We recommend you test them with a smaller audience first before rolling them out broadly.

3. Start with scoped, low-risk implementations

When introducing advanced macros, begin with a narrowly-scoped page or a single-team use case (e.g. a project status page) rather than rolling them out across an entire space.  

• Why it matters: You’ll reduce the blast radius if something breaks, you get cleaner feedback, and you build confidence before deploying more complex reporting. 

2. Standardize labels and metadata

Advanced macros can often rely on consistent labels and property names to work properly. Define a labeling convention (e.g., project-alpha, release-q1, policy-HR) and document it in your team’s Confluence playbook.

• Why it matters: Without consistency, reports will miss pages or pull in irrelevant ones, which undermines trust in your dashboards.

3. Use templates with preconfigured macros

Instead of having each team configure advanced macros themselves, bake them into page templates. Create a “Project Status” template with a Content Properties table and pre-filtered Task Report.

• Why it matters: This ensures consistency across projects and reduces setup time for content creators.

Automating Confluence workflows with macros

If you’ve ever spent time consolidating updates from multiple spaces or copying task lists into a status report, you know how much time disappears into repetitive work. One of the biggest advantages of macros is that they can automate much of this.

Let’s take a look at how to do that.

Combining macros to automate repetitive tasks

Using several macros in combination is an effective way to scale your workflows. Here’s a few you can try:

Recently Updated + Task Report

This combination of macros allows you to show recent changes in a space alongside open tasks. The Recently Updated macro surfaces the latest activity on a Confluence page or across an entire space — edits, new pages, and comments. The Task Report macro pulls in tasks assigned to users. On their own, both are helpful. But when you place them together on a single dashboard page, they create a self-updating view of both progress and work still pending.

• Automation benefit: Eliminates the need to manually notify teams of progress — they can see what’s been updated and what’s still outstanding, all on one page.
• Use case: Helpful for internal project status dashboards or weekly stand-up pages.

Excerpt + Insert Excerpt

With this pairing of macros, you can define a piece of important content once and reuse it in multiple places. Use the Excerpt macro to define a single source of truth (for example a key process, compliance statement, or support policy). Then use Insert Excerpt to display that content on multiple pages. 

• Automation benefit: Update the original once, and it’s automatically updated everywhere it’s included. No need for repetitive edits across spaces.
• Use case: For example, an onboarding checklist can live on a single source page, and any changes there will automatically flow to every page that includes it.

Streamlining documentation and reporting

One of the biggest headaches for admins and project leads is keeping documentation and reports current. Confluence macros can handle a lot of that legwork automatically, so you don’t have to chase down updates or rebuild dashboards every week.

With the right macros, you can:

• Aggregate content into dashboards — By combining macros like Content Properties Report and Task Report, you can build self-updating dashboards that track multiple projects or initiatives. Instead of exporting data into spreadsheets, you centralize it in Confluence, where it always reflects the latest information.
• Surface recent changes — The Recently Updated macro is a simple but powerful way to give visibility into what’s happening across a space. Pair it with labels to highlight specific types of content, like policy updates or meeting notes, so stakeholders know exactly what’s changed without needing an email blast.

Integrating macros with Jira

Macros aren’t only about organizing Confluence content. They also serve as a bridge between Confluence and the rest of your toolset. This is where automation can really reduce context switching and manual reporting.

The Jira Issues macro is one of the most valuable for project teams. You can embed live issue lists, sprint boards, or release progress directly into a Confluence page. A sprint retrospective page, for example, can automatically display completed issues, unresolved blockers, and story points delivered — no screenshots or exports required.

Tip: Want to surface JSM request types directly inside documentation pages and knowledge base articles? Take a look at Refined SItes for Confluence and seamlessly incorporate JSM request types directly into page designs.

Macros from the Marketplace: Refined Macro Toolkit for Confluence

Confluence Cloud ships with plenty of built-in macros — but sometimes you need more flexibility, richer layouts, or functionality that goes beyond Atlassian’s defaults. 

That’s where the Refined Macro Toolkit for Confluence Cloud comes in.

Transform the way you organize and share info 

The Refined Macro Toolkit is a set of easy-to-use content formatting macros designed to help admins and content creators improve layout, navigation, and user engagement in Confluence. 

With the toolkit, you can:

• Create pages that are intuitively structured and easier to browse.
• Highlight important information like events, announcements, or key resources.
• Build polished, branded experiences without needing custom code.

It’s particularly useful for teams building intranets, knowledge bases, or documentation sites, where content organization and presentation directly affect adoption.

Unlock a suite of content formatting macros — and go beyond default Confluence functionality and to create more engaging, branded experiences.

Start building smarter Confluence pages

Macros aren’t simply a “nice-to-have” in Confluence. They’re a way to improve navigation, automate work, scale your site as information grows, and craft better user experiences. Combining built-in macros with advanced customization — and tools like Refined Macro Toolkit — you can turn your Confluence site into a truly dynamic knowledge hub.

Try Macro Toolkit free for 30 days on the Atlassian Marketplace.