claude-skills-reference/project-management/confluence-expert/references/macro-cheat-sheet.md

Confluence Macro Cheat Sheet

Overview

Quick reference for the most commonly used Confluence macros. Each entry includes the macro name, storage format syntax, primary use case, and practical tips.

Navigation & Structure Macros

Table of Contents

• Purpose: Auto-generate a linked table of contents from page headings
• Syntax: <ac:structured-macro ac:name="toc" />
• Parameters: maxLevel (1-6), minLevel (1-6), style (disc, circle, square, none), type (list, flat)
• Use case: Long documentation pages, meeting notes, specifications
• Tip: Set maxLevel="3" to avoid overly deep TOC entries

Children Display

• Purpose: List child pages of the current page
• Syntax: <ac:structured-macro ac:name="children" />
• Parameters: depth (1-999), sort (title, creation, modified), style (h2-h6), all (true/false)
• Use case: Parent hub pages, project homepages, documentation indexes
• Tip: Use depth="1" for clean navigation, all="true" for deep hierarchies

Include Page

• Purpose: Embed content from another page inline
• Syntax: <ac:structured-macro ac:name="include"><ac:parameter ac:name=""><ac:link><ri:page ri:content-title="Page Name" /></ac:link></ac:parameter></ac:structured-macro>
• Use case: Reusable content blocks (headers, footers, disclaimers)
• Tip: Changes to the source page are reflected everywhere it is included

Page Properties

• Purpose: Define structured metadata on a page (key-value pairs)
• Syntax: <ac:structured-macro ac:name="details"> with table inside
• Use case: Project metadata, status tracking, structured page data
• Tip: Combine with Page Properties Report macro to create dashboards

Page Properties Report

• Purpose: Display a table of Page Properties from child pages
• Syntax: <ac:structured-macro ac:name="detailssummary" />
• Parameters: cql (CQL filter), labels (filter by label)
• Use case: Project dashboards, status rollups, portfolio views
• Tip: Use labels to scope the report to relevant pages only

Visual & Formatting Macros

Info Panel

• Purpose: Blue information callout box
• Syntax: <ac:structured-macro ac:name="info"><ac:rich-text-body>Content</ac:rich-text-body></ac:structured-macro>
• Use case: Helpful notes, additional context, best practices

Warning Panel

• Purpose: Yellow warning callout box
• Syntax: <ac:structured-macro ac:name="warning"><ac:rich-text-body>Content</ac:rich-text-body></ac:structured-macro>
• Use case: Important caveats, deprecation notices, breaking changes

Note Panel

• Purpose: Yellow note callout box
• Syntax: <ac:structured-macro ac:name="note"><ac:rich-text-body>Content</ac:rich-text-body></ac:structured-macro>
• Use case: Reminders, action items, things to watch

Tip Panel

• Purpose: Green tip callout box
• Syntax: <ac:structured-macro ac:name="tip"><ac:rich-text-body>Content</ac:rich-text-body></ac:structured-macro>
• Use case: Pro tips, shortcuts, recommended approaches

Expand

• Purpose: Collapsible content section (click to expand)
• Syntax: <ac:structured-macro ac:name="expand"><ac:parameter ac:name="title">Click to expand</ac:parameter><ac:rich-text-body>Hidden content</ac:rich-text-body></ac:structured-macro>
• Use case: Long sections, FAQs, detailed explanations, optional reading
• Tip: Use for content that not all readers need

Status

• Purpose: Colored status lozenge (inline label)
• Syntax: <ac:structured-macro ac:name="status"><ac:parameter ac:name="colour">Green</ac:parameter><ac:parameter ac:name="title">DONE</ac:parameter></ac:structured-macro>
• Colors: Grey, Red, Yellow, Green, Blue
• Use case: Task status, review state, approval status
• Tip: Standardize status values across your team (e.g., TODO, IN PROGRESS, DONE)

Integration Macros

Jira Issues

• Purpose: Display Jira issues or JQL query results
• Syntax: <ac:structured-macro ac:name="jira"><ac:parameter ac:name="jqlQuery">project = PROJ AND status = Open</ac:parameter></ac:structured-macro>
• Parameters: jqlQuery, columns (key, summary, status, assignee, etc.), count (true/false), serverId
• Use case: Sprint boards in documentation, requirement traceability, release notes
• Tip: Use columns parameter to show only relevant fields

Roadmap Planner

• Purpose: Visual timeline/Gantt view of items
• Syntax: Available via macro browser (Roadmap Planner)
• Use case: Project timelines, release planning, milestone tracking
• Tip: Link roadmap items to Jira epics for automatic status updates

Chart Macro

• Purpose: Create charts from table data on the page
• Syntax: <ac:structured-macro ac:name="chart"><ac:parameter ac:name="type">pie</ac:parameter><ac:rich-text-body>Table data</ac:rich-text-body></ac:structured-macro>
• Types: pie, bar, line, area, scatter, timeSeries
• Use case: Status distribution, metrics dashboards, trend visualization
• Tip: Place a Confluence table inside the macro body as data source

Content Reuse Macros

Excerpt

• Purpose: Mark a section of content for reuse via Excerpt Include
• Syntax: <ac:structured-macro ac:name="excerpt"><ac:rich-text-body>Reusable content</ac:rich-text-body></ac:structured-macro>
• Use case: Define canonical content blocks (product descriptions, team info)

Excerpt Include

• Purpose: Display an Excerpt from another page
• Syntax: <ac:structured-macro ac:name="excerpt-include"><ac:parameter ac:name=""><ac:link><ri:page ri:content-title="Source Page" /></ac:link></ac:parameter></ac:structured-macro>
• Use case: Embed product descriptions, standard disclaimers, shared definitions

Advanced Macros

Code Block

• Purpose: Display formatted code with syntax highlighting
• Syntax: <ac:structured-macro ac:name="code"><ac:parameter ac:name="language">python</ac:parameter><ac:plain-text-body>code here</ac:plain-text-body></ac:structured-macro>
• Languages: java, python, javascript, sql, bash, xml, json, and many more
• Use case: API documentation, configuration examples, code snippets

Anchor

• Purpose: Create a named anchor point for deep linking
• Syntax: <ac:structured-macro ac:name="anchor"><ac:parameter ac:name="">anchor-name</ac:parameter></ac:structured-macro>
• Use case: Link directly to specific sections within long pages
• Tip: Use with TOC macro for custom navigation

Recently Updated

• Purpose: Show recently modified pages in a space
• Syntax: <ac:structured-macro ac:name="recently-updated" />
• Parameters: spaces, labels, types, max
• Use case: Team dashboards, space homepages, activity feeds

Macro Selection Guide

Need	Recommended Macro
Page navigation	Table of Contents
List child pages	Children Display
Reuse content	Include Page or Excerpt Include
Status tracking	Status + Page Properties
Project dashboard	Page Properties Report
Hide optional content	Expand
Show Jira data	Jira Issues
Visualize data	Chart
Code documentation	Code Block
Important callouts	Info/Warning/Note/Tip panels