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.