Marcos Silva
113 lines
3.5 KiB
Markdown
113 lines
3.5 KiB
Markdown
# 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.
|