Master this essential documentation concept
In platforms like Confluence, a reusable dynamic content block that automatically generates or displays specific information, such as tables of contents, Jira issue lists, or status indicators.
In platforms like Confluence, a reusable dynamic content block that automatically generates or displays specific information, such as tables of contents, Jira issue lists, or status indicators.
When your team onboards new members to Confluence, walkthroughs showing how to insert and configure macros are often recorded as training videos. A screen recording that demonstrates how to add a Table of Contents macro or wire up a Jira Issues macro to a project filter is genuinely useful in the moment — but that usefulness has a short shelf life.
The problem is that macros change. Confluence updates alter configuration panels, deprecate options, or introduce new macro variants. A video recorded six months ago may now show a workflow that no longer matches what your team sees on screen. Worse, when someone needs to remember the exact parameter settings for a custom macro, scrubbing through a recording to find that one configuration step wastes time that structured documentation would recover instantly.
Converting those training recordings into searchable documentation changes this entirely. Each macro gets its own documented section — purpose, configuration steps, common parameters, and known limitations — that your team can update in place as Confluence evolves. When a new hire asks how to use the Status macro consistently across a space, they find a precise written answer rather than a video timestamp buried in a shared drive.
If your team relies on recorded walkthroughs to pass along knowledge about Confluence macros and other platform workflows, see how converting video to structured documentation can make that knowledge genuinely reusable →
Engineering teams manually copy Jira ticket titles, statuses, and assignees into Confluence release notes pages, which become outdated within hours as tickets are updated, reassigned, or closed during the sprint.
The Jira Issues Macro embeds a live-queried list of Jira tickets directly in the release notes page using a JQL filter, automatically reflecting current ticket status, priority, and assignee without any manual updates.
['Insert the Jira Issues Macro on the release notes Confluence page and open its configuration panel.', "Enter a JQL query such as 'project = BACKEND AND fixVersion = 3.2.1 ORDER BY priority DESC' to scope the macro to the correct sprint or release.", 'Select the columns to display: Issue Key, Summary, Status, Assignee, and Story Points.', 'Save the page — the macro will re-query Jira on every page load, ensuring stakeholders always see current ticket data.']
Release notes pages stay accurate throughout the sprint without any manual edits, reducing the time engineers spend updating documentation by approximately 2-3 hours per release cycle.
Architecture Decision Records (ADRs) accumulate over months into long Confluence pages or nested spaces, making it difficult for new engineers to locate relevant decisions without scrolling through hundreds of lines of content.
The Table of Contents Macro automatically generates a clickable, hierarchical navigation panel from the heading structure of each ADR page, allowing engineers to jump directly to the decision context, rationale, or consequences sections.
['Structure each ADR page with consistent H2 headings: Context, Decision, Rationale, Consequences, and Status.', 'Insert the Table of Contents Macro at the top of the ADR page template so every new ADR inherits it automatically.', 'Configure the macro to display headings from level 2 to level 3 only, filtering out minor sub-headings that clutter the TOC.', 'Publish the updated ADR template so all future ADRs auto-generate a navigable TOC on creation.']
New engineers onboarding to the codebase can locate the rationale or consequences of any architectural decision within seconds, reducing onboarding ramp-up time for architecture context from days to hours.
Compliance and legal teams maintain dozens of policy documents in Confluence, but readers cannot tell at a glance whether a document is a draft, under legal review, approved, or deprecated — leading to teams acting on outdated or unapproved policies.
The Status Macro is placed at the top of each policy document and configured with color-coded labels (yellow for Draft, blue for In Review, green for Approved, red for Deprecated), giving readers an immediate visual signal of the document's authority.
['Add a Status Macro in the document header section of the policy page template, positioned directly below the document title.', 'Configure the macro with four distinct statuses and colors: Draft (yellow), In Review (blue), Approved (green), Deprecated (red).', 'Establish a team convention that the document owner updates the Status Macro when the document moves through the review workflow.', 'Add an Info Panel Macro below the status badge to display the last review date and the name of the approving authority.']
Policy consumers immediately understand document authority before reading, and compliance audit trails become cleaner because status is embedded in the document itself rather than tracked in a separate spreadsheet.
SRE teams maintain runbooks across multiple Confluence spaces for different services, but during an incident, engineers waste critical minutes navigating nested spaces and page trees to find the correct runbook for the failing service.
The Confluence Children Display Macro and Page Properties Report Macro are combined to auto-generate a searchable, tabular index of all runbooks tagged with service name, severity level, and owning team — updated automatically as new runbooks are added.
['Add a Page Properties Macro to each runbook template containing metadata fields: Service Name, Severity Tier, On-Call Team, and Last Tested Date.', "Create a central 'Runbook Index' Confluence page and insert a Page Properties Report Macro configured to aggregate all pages using the runbook template label.", 'Configure the report macro to display Service Name, Severity Tier, On-Call Team, and Last Tested Date as sortable columns.', "Bookmark the Runbook Index page in the SRE team's incident response channel so it is the first resource opened during an alert."]
During incidents, engineers locate the correct runbook in under 30 seconds from the index page, compared to the previous average of 4-6 minutes of manual navigation — measurably reducing mean time to resolution (MTTR).
When macros like Table of Contents, Status, or Page Properties are added to Confluence page templates rather than individual pages, every new document created from that template inherits the macro automatically. This eliminates the dependency on individual contributors remembering to add navigation or metadata elements and ensures a uniform reading experience across hundreds of pages.
The Jira Issues Macro can return hundreds of tickets if configured with a broad or vague JQL query, overwhelming readers with irrelevant issues and slowing page load times. Precise JQL filters scoped to a specific project, fix version, component, or label ensure the macro surfaces only the tickets that are contextually relevant to the documentation page.
Readers scanning technical documentation often miss important caveats, prerequisites, or deprecation warnings when they are written as plain paragraphs. The Info, Warning, and Note Panel Macros visually distinguish these callouts with colored backgrounds and icons, directing the reader's eye to content that requires special attention before proceeding.
Macros like Jira Issues, Page Properties Report, and RSS Feed dynamically pull external data, but the underlying JQL queries, page labels, or feed URLs can become stale as projects are renamed, archived, or restructured. Scheduling a quarterly macro audit ensures that dynamic content blocks still return accurate, relevant data rather than empty results or outdated information.
Each macro that queries external systems like Jira or renders complex layouts adds processing overhead to the page load. Pages with more than five or six dynamic macros can become slow to render, particularly for readers on lower-bandwidth connections, and visually cluttered pages with excessive macros reduce comprehension rather than improving it.
Join thousands of teams creating outstanding documentation
Start Free Trial