Macros

Macros

atlcli provides extensive Confluence macro support with bidirectional conversion between markdown and Confluence Storage Format.

Prerequisites

• Basic understanding of markdown syntax
• For push operations: Edit permission on target Confluence space

Mermaid diagrams

Install Mermaid Integration for Confluence (macro name mermaid) on the Confluence site before pushing Mermaid fences. Atlcli writes the source into that macro’s inline JSON body; the app renders it in Confluence. No diagram image or source attachment is uploaded by atlcli.

```mermaid
flowchart LR
  Plan --> Release
```

For a themed cutover plan:

```mermaid{theme="forest"}
flowchart LR
  Rehearsal --> Gate{Go / no-go}
  Gate -->|Go| Cutover
  Gate -->|No-go| Rollback
  Cutover --> Validate
```

Themes: default (the default), forest, dark, neutral. Inline macro sources return as editable Mermaid fences through wiki docs pull, wiki sh and WebDAV. The shared Storage and Cloud ADF export adapters also pass these sources to the existing PDF/DOCX diagram renderer.

Compatibility: this mapping targets the named app, not every marketplace Mermaid app. Missing app installation means Confluence cannot render the macro. Attachment-backed v2 macros, malformed bodies and unrecognized parameters stay in the existing :::confluence raw-XML form; atlcli does not silently convert or discard their external sources. DOCX import does not infer Mermaid from an ordinary Word code paragraph.

Panel Macros

Info Panel

:::info
This is an informational message.
:::

With title:

:::info "Important Information"
This is an info panel with a title.
:::

Note Panel

:::note
This is a note for the reader.
:::

Warning Panel

:::warning
This action cannot be undone!
:::

Tip Panel

:::tip
Pro tip: Use keyboard shortcuts for faster navigation.
:::

Custom Panel

Full control over panel styling:

:::panel title="Custom Panel" bgColor="#f0f0f0" borderColor="#ccc" borderStyle="solid"
Custom styled panel content.
:::

Options:

Option	Description
title	Panel title
bgColor	Background color (hex)
borderColor	Border color (hex)
borderStyle	solid, dashed, none

Expand/Collapse

Basic Expand

:::expand "Click to expand"
This content is hidden by default.
:::

The title is the quoted text (or the whole rest of the line when unquoted). The Confluence expand macro has no “expanded by default” option, so parameters after a quoted title (for example expanded=true) are dropped on push, and atlcli wiki docs check warns about them (MACRO_INVALID_PARAMS).

Table of Contents

:::toc
:::

With options:

:::toc minLevel=2 maxLevel=4 style=none
:::

Options (passed to the Confluence toc macro and preserved on pull):

Option	Description
minLevel	Minimum heading level (default: 1)
maxLevel	Maximum heading level (default: 7)
type	list or flat
outline	true to number headings
style	List bullet style: none, disc, circle, square
indent	Indent per level, for example 10px
separator	Separator for type=flat: brackets, braces, parens, pipe, or custom text
include	Regex of headings to include, for example include="^Intro.*"
exclude	Regex of headings to exclude
printable	false hides the TOC when printing
class	CSS class for the TOC
absoluteUrl	true to use absolute links

Values with spaces or special characters need quotes. Unknown options are dropped on push and reported as warnings by atlcli wiki docs check.

Code Blocks

atlcli converts standard fenced code blocks to Confluence code macros:

```javascript
function hello() {
  console.log("Hello, world!");
}
```

With title:

```python title="example.py"
def hello():
    print("Hello, world!")
```

With line numbers:

```typescript linenumbers=true
const greeting: string = "Hello";
console.log(greeting);
```

Empty code and noformat blocks, including blocks containing only line breaks, are preserved during pull/push round trips. Code language, title, and collapse settings are retained. Intentional trailing blank lines stay unchanged when present in the returned storage. Confluence Cloud may normalize a block containing only line breaks to an empty block; atlcli preserves that empty block.

Supported Languages

JavaScript, TypeScript, Python, Java, Go, Rust, C, C++, C#, Ruby, PHP, SQL, Bash, YAML, JSON, XML, HTML, CSS, and many more.

Noformat Block

Preformatted text without syntax highlighting:

```noformat
This text preserves whitespace
  and formatting exactly
    as written.
```

Text Formatting

Colored Text

Apply color to inline text:

This is {color:red}red text{color} and {color:#0066cc}blue text{color}.

Supports CSS color names and hex codes.

Background Color

Highlight text with background color:

This is {bg:yellow}highlighted{bg} text.
{bg:#e6f3ff}Custom background{bg}

Subscript and Superscript

H~2~O (subscript)
E=mc^2^ (superscript)

Task Lists

Native checkbox support:

- [ ] Unchecked task
- [x] Completed task
- [ ] Another pending task

Converts to Confluence’s native task list format with proper checkboxes.

Date Macro

Insert formatted dates:

{date:2025-01-15}

Rendered as a Confluence date picker showing the specified date.

Emoticons

Use one of the supported emoji shortcodes when authoring Markdown:

:smile: :thumbsup: :warning: :star:

atlcli converts these authoring tokens to typed Confluence emoticons. During DOCX/PDF export, only typed ADF emoji, Body Storage ac:emoticon, or typed custom-panel icon metadata is projected to a graphical character. Ordinary stored text such as :warning: remains literal. Unknown or site-custom emoji also remain visible as their short name and produce an export note.

Cloud exports use ADF as their primary source. Data Center exports use the shared Body Storage adapter. Both source paths use the same typed resolver and catalog when no usable Unicode text is already present; existing source Unicode remains exact. Confluence Cloud may rewrite a typed legacy value to a product-owned short name such as :check_mark: or :light_bulb_on: during ADF read-back. The export adapter recognizes those spellings, but they are not additional Markdown authoring aliases and are therefore not listed below.

The table below is the complete Markdown/legacy authoring catalog, not a limit on Confluence Cloud’s native emoji picker. A live Cloud picker inventory on 2026-07-24 contained 50 unique entries: 44 standard emoji carried exact Unicode in ADF emoji.attrs.text, while six product-owned assets used colon text. Those six portable read-back projections are :check_mark: → ✓, :warning: → ⚠, :minus: → −, :question_mark: → ❓, :cross_mark: → ✕, and :info: → ℹ. Standard Unicode remains byte-for-byte unchanged. The Body Storage/Data Center ac:emoticon adapter applies the same resolver when ac:emoji-fallback contains one of those typed short names and preserves a usable Unicode fallback exactly.

Supported Emoticons

Canonical shortcode	Graphical export	Supported aliases
:smile:	☺	:grinning:, :grin:, :smiley:
:sad:	☹	:disappointed:, :cry:
:cheeky:	😛	:stuck_out_tongue:
:laugh:	😄	:joy:, :laughing:
:wink:	😉	—
:thumbs-up:	👍	:+1:, :thumbsup:
:thumbs-down:	👎	:-1:, :thumbsdown:
:tick:	✓	:check:, :white_check_mark:, :heavy_check_mark:
:cross:	✕	:x:, :heavy_multiplication_x:
:warning:	⚠	:warn:, :alert:
:information:	ℹ	:info:
:question:	❓	—
:light-on:	💡	:bulb:, :idea:, :lightbulb:
:light-off:	○	—
:yellow-star:	Y★	:star:
:red-star:	R★	—
:green-star:	G★	—
:blue-star:	B★	—
:heart:	♥	:love:, :red_heart:
:broken-heart:	💔	—
:plus:	✚	—
:minus:	−	—

The graphical export is a portable monochrome projection, not a claim of pixel parity with Confluence’s color emoji. PDF bundles and checks the required fonts. DOCX stores the exact projected Unicode, but the receiving application still chooses the display font. Arbitrary source-provided Unicode sequences are preserved exactly; glyph availability for those sequences depends on the recipient. The 50-entry live picker corpus rendered completely in Microsoft Word; LibreOffice retained the exact DOCX text but did not provide every platform color-emoji glyph. Site-custom emoji are not fetched because Atlassian does not expose a documented, authorized portable asset contract for this export path.

User Mentions

Mention users by account ID:

@[John Doe](557058:abcd-efgh-ijkl)

The account ID can be found in Confluence user profiles or via the API.

Escape square brackets in a name with a backslash. atlcli writes names that way when it pulls:

@[Max Muster \[extern\]](557058:abcd-efgh-ijkl)

On Server and Data Center, mentions point at a user key. atlcli writes it with a userkey: prefix:

@[Jane Roe](userkey:8a7f808a8b1c2d3e)

When you pull or diff a page, atlcli fills in the display name of each mentioned user. Confluence often stores a mention without one, so atlcli looks the user up once per run. If the lookup fails, for example for a deleted user, the mention keeps its ID as the name: @[557058:abcd-efgh-ijkl](557058:abcd-efgh-ijkl). When you push such a mention, atlcli writes it without link text, so Confluence shows the user’s current name.

Status Macro

Inline status labels:

{status:green}Approved{status}
{status:yellow}In Review{status}
{status:red}Rejected{status}
{status:blue}In Progress{status}
{status:grey}Draft{status}

Colors: green, yellow, red, blue, grey

Anchor Macro

Create link anchors:

{#my-anchor}

Link to [my section](#my-anchor).

Smart Links

Atlassian smart links are rich links to Jira issues, Confluence pages, and other Atlassian content that display contextual information. atlcli supports bidirectional conversion of smart links.

Markdown Format

When pulling pages, atlcli converts smart links to standard markdown URLs:

# Inline link (default)
[PROJ-123](https://your-site.atlassian.net/browse/PROJ-123)

# Card view - shows preview card
[PROJ-123](https://your-site.atlassian.net/browse/PROJ-123)<!--card-->

# Embed view - embeds content
[Page Title](https://your-site.atlassian.net/wiki/spaces/TEAM/pages/12345)<!--embed-->

How It Works

Direction	Process
Pull	Smart links → Full URLs with display mode annotations
Push	Atlassian URLs → Smart links with data-card-appearance

Display Modes

Mode	Annotation	Description
Inline	(none)	Link appears inline in text
Card	<!--card-->	Shows preview card with title and metadata
Embed	<!--embed-->	Embeds full content preview

Supported URL Patterns

• Jira Issues: /browse/PROJ-123
• Confluence Pages: /wiki/spaces/SPACE/pages/12345
• Trello: trello.com/c/... or trello.com/b/...
• Bitbucket: bitbucket.org/user/repo

Profile-Based Conversion

atlcli converts only URLs matching your active profile’s Atlassian instance to smart links. External URLs remain as regular markdown links.

# Converted to smart link (same instance)
[Issue](https://your-site.atlassian.net/browse/PROJ-123)

# Remains regular link (different instance)
[External](https://other-site.atlassian.net/browse/PROJ-456)

Jira Integration

Single Issue (Legacy)

The {jira:KEY} syntax is deprecated. Use full URLs instead:

# Deprecated (still works)
{jira:PROJ-123}

# Recommended - use full URL
[PROJ-123](https://your-site.atlassian.net/browse/PROJ-123)

When pulling pages, Jira macros are automatically converted to full URLs.

JQL Query

{jira:project = PROJ AND status = Open|columns=key,summary,status}

Options:

Option	Description
columns	Columns to display
count	Show count only
cache	Cache duration

Page Structure

Children Macro

List child pages:

:::children
:::

With options:

:::children depth=2 sort=title
:::

Options:

Option	Description
depth	How many levels deep
sort	title, created, modified
reverse	Reverse sort order
style	none, disc, circle, square

Page Tree

Display page tree navigation:

:::pagetree root=12345 depth=3
:::

Recently Updated

:::recently-updated spaces=TEAM,DOCS max=10
:::

Content by Label

:::content-by-label labels=api,documentation
:::

Layout Macros

Section and Column

:::section
:::column width="50%"
Left column content.
:::column-end
:::column width="50%"
Right column content.
:::column-end
:::section-end

Sections and columns close with :::section-end and :::column-end, not a bare :::. Only columns are kept inside a section.

Excerpt

Mark content for reuse:

:::excerpt
This content can be included in other pages.
:::

Include Excerpt

Include excerpt from another page:

:::excerpt-include page="Page Title" nopanel=true
:::

Media Macros

Gallery

Display attached images as gallery:

:::gallery columns=3
:::

Attachments List

List page attachments:

:::attachments patterns=*.pdf,*.docx
:::

Multimedia

Embed video or audio:

:::multimedia url="https://youtube.com/watch?v=..." width=640 height=480
:::

Widget/Embed

Embed external content:

:::widget url="https://example.com/embed" width=100%
:::

TOC Zone

Create a table of contents for a specific section:

:::toc-zone minLevel=2 maxLevel=4
## Section 1
Content...
## Section 2
Content...
:::

Only headings within the zone are included in the TOC.

Page Properties

Details Summary (Page Properties Panel)

Display page metadata in a panel:

:::details
| Property | Value |
|----------|-------|
| Status | Active |
| Owner | John |
:::

Details (Hidden Metadata)

Store metadata without displaying:

:::detailssummary hidden=true
| Key | Value |
|-----|-------|
| internal-id | 12345 |
:::

Tasks Report

Display a summary of tasks across pages:

:::tasks-report-macro spaces="TEAM" pageSize=20
:::

Shows tasks from specified spaces with pagination.

Labels Macros

Labels List

Display labels for the current page:

:::labels-list
:::

Popular Labels

Show frequently used labels in a space:

:::popular-labels spaces="TEAM" count=20
:::

Related Labels

Show labels related to current page’s labels:

:::related-labels labels="api,docs"
:::

Blog Posts

Display recent blog posts:

:::blog-posts max=10 spaces="DEV,OPS" labels="announcement"
:::

Options:

Option	Description
max	Maximum posts to show
spaces	Comma-separated space keys
labels	Filter by labels
author	Filter by author account ID
time	Time period filter
sort	Sort order

Spaces List

List available spaces:

:::spaces-list
:::

Page Index

Display alphabetical index of pages:

:::page-index
:::

Contributors

Show page contributors:

:::contributors mode=list showCount=true
:::

Options:

Option	Description
mode	list or inline
showCount	Show contribution count
limit	Max contributors to show
order	update or name
showLastTime	Show last contribution time

Change History

Display page change history:

:::change-history
:::

Options:

Option	Description
limit	Max entries to show
showProfilePic	Show contributor avatars
showSpace	Show space name

Lorem Ipsum

Generate placeholder text:

:::loremipsum paragraphs=3
:::

Confluence Wiki Syntax

For compatibility, Confluence wiki attachment syntax is also supported:

!image.png!                    <!-- Inline image -->
!image.png|alt=Description!    <!-- Image with alt text -->
!document.pdf!                 <!-- File download link -->

Unknown Macros

atlcli preserves unrecognized macros as-is. This ensures no information loss during sync:

:::unknown-macro param1=value1 param2=value2
Content inside the unknown macro.
:::

On push, atlcli converts this to Confluence’s storage format and preserves it. On pull, atlcli converts it back exactly.

Conversion Details

Direction	Process
Push	Markdown → Confluence Storage Format (XHTML)
Pull	Storage Format → Markdown

Round-Trip Safety

All supported macros round-trip cleanly:

1. Pull page with macros → Markdown
2. Edit markdown
3. Push back → Identical macro rendering

Nesting Macros

Block macros can be nested: write the inner ::: block inside the outer body. atlcli converts the innermost macro first, in both directions.

:::expand Details
:::warning
Check {status:red}BLOCKED{status} items first.
:::

More text in the expand.
:::

An unrecognized macro is kept as one raw XML block (:::confluence name with a <!--raw ... --> comment), together with every macro nested in it, so a push restores it byte for byte. Edit its content in Confluence.

Unsupported Macros

Some complex macros render to placeholder text with a note:

<!-- Confluence macro: roadmap - not fully supported, preserved as-is -->
:::roadmap
...
:::

Best Practices

1. Use standard markdown when possible (tables, code blocks, lists)
2. Reserve macros for Confluence-specific features (panels, toc, jira)
3. Test round-trips for complex pages before relying on sync
4. Check preview with atlcli wiki docs preview before pushing

Troubleshooting

Macro Not Rendering

Symptom: Macro appears as raw text in Confluence.

Cause: Unclosed macro block or incorrect syntax.

Fix: Ensure every :::macro has a matching ::: closing tag (:::section and :::column close with :::section-end and :::column-end). Nested macros need their own closing ::: line, see Nesting Macros. Validate with:

atlcli wiki docs check ./docs/page.md

Unknown Macro Warning

Symptom: Warning about unrecognized macro during push.

Cause: The macro isn’t in atlcli’s supported list.

Fix: This is safe—atlcli preserves unknown macros as-is, and they render correctly in Confluence.

Related Topics

• Sync - Push and pull pages with macro content
• Validation - Pre-push checks including macro syntax
• File Format - Frontmatter and markdown structure
• Pages - Create and update pages