Confluence Macros Guide

Macros are built-in widgets you drop into any page to add dynamic, interactive, or structured content. A macro does the work for you — it pulls live data, formats information automatically, or creates navigation elements without writing a single line of code.

What a Macro Is

Think of a macro as a smart component you snap into your page. A regular paragraph just displays text. A macro connects to data, auto-updates, or formats content in ways plain text cannot. Every macro produces a live output that can change without you editing the page again.

Plain Text vs Macro

PLAIN TEXT:
"See child pages: Leave Policy, Remote Work Policy, Travel Policy"
— You update this list manually every time a new page is added.

CHILDREN DISPLAY MACRO:
[Macro pulls live list of child pages]
→ Leave Policy
→ Remote Work Policy
→ Travel Policy
→ Expense Policy        ← added automatically when new page is created

How to Insert a Macro

Type a forward slash / in the editor and start typing the macro name. Click the macro in the dropdown to insert it. A configuration panel opens where you set the macro's options.

Macro Insertion Steps

STEP 1  →  Open the page in edit mode
STEP 2  →  Click where you want the macro
STEP 3  →  Type  /  (forward slash)
STEP 4  →  Type the macro name, e.g.  /table of contents
STEP 5  →  Click the macro in the dropdown
STEP 6  →  Set options in the configuration panel
STEP 7  →  Click Insert

The Most Useful Macros

Table of Contents Macro

PURPOSE:  Auto-generates a clickable contents list from your headings
BEST FOR: Long pages with multiple sections

EXAMPLE OUTPUT:
─────────────────────────────
Contents
1. Introduction
2. Requirements
3. Installation Steps
4. Troubleshooting
─────────────────────────────
Updates automatically when you add or rename headings.

Children Display Macro

PURPOSE:  Lists all child pages of the current page automatically
BEST FOR: Container pages, section indexes, meeting note archives

EXAMPLE:
─────────────────────────────
📄 Meeting Notes (this page)
  → Jan 2025 Notes
  → Feb 2025 Notes
  → Mar 2025 Notes       ← updates automatically
─────────────────────────────

Info / Warning / Note Panel Macro

PURPOSE:  Adds a coloured callout box to highlight key information
BEST FOR: Warnings, tips, important notices

ℹ INFO:  "This guide applies to cloud accounts only."
⚠ WARN:  "Deleting a space is permanent and cannot be undone."
💡 TIP:   "Use keyboard shortcut E to open edit mode instantly."

Code Block Macro

PURPOSE:  Displays code with syntax highlighting
BEST FOR: Developer documentation, commands, scripts

EXAMPLE:
┌──────────────────────────────────────┐
│ python                               │
│ def greet(name):                     │
│     return f"Hello, {name}!"         │
└──────────────────────────────────────┘
Supports: Python, JavaScript, SQL, Bash, Java, and 30+ languages.

Status Macro

PURPOSE:  Adds a coloured status badge inline in your text
BEST FOR: Project status, task tracking, document stage

COLOURS AND MEANINGS:
[  IN PROGRESS  ]  Blue     Work is ongoing
[  DONE         ]  Green    Completed
[  BLOCKED      ]  Red      Waiting on something
[  TODO         ]  Grey     Not started yet

Expand Macro

PURPOSE:  Hides content behind a clickable label
BEST FOR: FAQs, optional detail, archive content

EXAMPLE:
▶ Click to see troubleshooting steps
  └── (hidden content appears only when clicked)

Keeps long pages short by collapsing content readers may not need.

Jira Issues Macro

PURPOSE:  Embeds live Jira issue data inside a Confluence page
BEST FOR: Linking documentation to related tasks and bugs

EXAMPLE OUTPUT:
──────────────────────────────────────────────────────
KEY         SUMMARY                 STATUS    ASSIGNEE
──────────────────────────────────────────────────────
ENG-142     Fix login timeout       In Review Priya S.
ENG-143     Update API docs         Done      Raj M.
──────────────────────────────────────────────────────
Updates live — no manual refresh needed.

Macro Parameters

Most macros have parameters — settings that change how the macro behaves. For example, the Table of Contents macro has a parameter to control the maximum heading depth it includes.

Example: Table of Contents Parameters

PARAMETER           VALUE               EFFECT
────────────────────────────────────────────────────────────────────
Minimum Heading     H2                  Starts the list at H2
Maximum Heading     H3                  Stops at H3 (ignores H4+)
Style               None/Disc/Decimal   Changes bullet style
Indent              5px                 Adds indent between levels

Third-Party Macros

Atlassian's Marketplace offers hundreds of additional macros built by third-party developers. These extend Confluence with features like interactive diagrams, project timelines, and advanced reporting. Your space admin installs marketplace apps from Settings → Find new apps.

Popular Marketplace Macro Apps

APP                 ADDS CAPABILITY
────────────────────────────────────────────────────────
draw.io             Drag-and-drop diagram editor
Gliffy              Flowcharts and wireframes
Zephyr Scale        Test management inside Confluence
PocketQuery         Pull live data from SQL databases

Macros transform Confluence from a static document tool into a live, connected workspace. Start with the five built-in macros in this topic and add more as your team's needs grow.