# Confluence Storage Macros

Confluence Cloud storage format accepts a fixed set of macros. Anything not in
this catalog either renders as plain text or fails silently. Before adding a
new macro to a draft, check the name here.

## Inline

| Macro | When |
|-------|------|
| `{code}` | Fenced code with optional language |
| `{plantuml}` | Diagrams — see `diagram-plantuml` skill |
| `{info}` | Info panel |
| `{note}` | Note panel |
| `{warning}` | Warning panel |
| `{tip}` | Tip panel |
| `{excerpt}` | Reusable fragment; also `excerpt-include` |
| `{anchor}` | Inline anchor for `{pageref}` |
| `{pageref}` | Cross-page reference by anchor |
| `{children}` | Lists child pages |
| `{include}` | Includes another page (full or excerpt) |
| `{table-of-content}` | Outline from heading hierarchy |
| `{expand}` | Collapsible section |
| `{status}` | Coloured status pill |
| `{cheese}` | Image gallery — prefer `image` element instead |
| `{noformat}` | Plain monospace, no language hint |

## Panels

Panels take rich-text bodies. PlantUML inside a panel does not render — put
diagrams at body root.

```xml
<ac:structured-macro ac:name="info">
  <ac:rich-text-body>
    <p>Body goes here.</p>
  </ac:rich-text-body>
</ac:structured-macro>
```

Available panel macros: `info`, `note`, `warning`, `tip`, `success`,
`error`, `panel` (generic).

## Code block

```xml
<ac:structured-macro ac:name="code">
  <ac:parameter ac:name="language">python</ac:parameter>
  <ac:parameter ac:name="title">example.py</ac:parameter>
  <ac:parameter ac:name="linenumbers">true</ac:parameter>
  <ac:plain-text-body><![CDATA[def hello():
    pass]]></ac:plain-text-body>
</ac:structured-macro>
```

`language` accepts the short names from Confluence's language list (`python`,
`java`, `javascript`, `typescript`, `go`, `bash`, `sql`, `json`, `yaml`,
`xml`, `markdown`). Anything outside the list falls back to plain monospace.

## Tables

Standard XHTML tables. Confluence does not need the `<ac:structured-macro
ac:name="table">` wrapper for plain tables.

```xml
<table>
  <tbody>
    <tr>
      <th>Column A</th>
      <th>Column B</th>
    </tr>
    <tr>
      <td>cell</td>
      <td>cell</td>
    </tr>
  </tbody>
</table>
```

For sortable or filterable tables, use the `table-plus` macro — but only
when the table is genuinely worth the overhead.

## Links

- External: `<a href="https://…">label</a>`
- Page by title: `<ac:link><ri:page ri:content-title="Hub"/></ac:link>`
- Page by id: `<ac:link><ri:page ri:content-id="12345"/></ac:link>`
- Attachment: `<ac:link><ri:attachment ri:filename="diagram.png"/></ac:link>`
- User mention: `<ac:link><ri:user ri:username="marcos"/></ac:link>`

## Attachments

Attachments go through `mcp__atlassian.confluence_upload_attachment` /
`confluence_create_page_from_file` (with the file path) — never as base64 in
the body. See `attachments.md`.

## What is NOT a macro

| Construct | Status |
|-----------|--------|
| Wiki markup (`{code}…{code}`) | Renders only on pages whose renderer is set to wiki; do not assume |
| Markdown fences | Not interpreted; render as text |
| HTML5 `<details>` | Rendered as plain HTML; works but no styling |
| Inline SVG | Works but is not editable through the page editor; prefer PlantUML |
| `<script>` / `<iframe>` | Stripped by Confluence; do not bother |

## Naming conventions

- Macro names are lowercase.
- Parameter names are lowercase with words separated by `-`, not `_`
  (`linenumbers`, not `line_numbers`).
- Parameter values that include spaces must be quoted.