The Markdown macro
Write Markdown on a Confluence page, with Mermaid diagrams, KaTeX maths and highlighted code.
What it does. Renders Markdown you type into a block on the page. Insert it by typing /Markdown.
When to use it. For content that is written in Markdown by the people who own it: runbooks kept next to code, architecture notes, generated documentation. It stays Markdown instead of being rewritten into the Confluence editor — and the diagrams inside it stay text, which is the part that pays off six months later.
The macro has two modes: Write, where you type or paste, and Preview, which shows exactly what the page will render.
## Deploy flow
> [!NOTE]
> Requires the release checklist to be complete.
```mermaid
graph LR
A[PR merged] --> B[CI]
B --> C{Tests pass?}
C -->|yes| D[Deploy staging]
C -->|no| E[Block]
```
| Stage | Owner | SLA |
|-------|-------|-----|
| CI | Platform | 10 min |
| Staging | Release | 30 min |
Error budget: $1 - \frac{failures}{requests}$What it renders
| You write | You get |
|---|---|
| Standard and GitHub-flavoured Markdown | Headings, emphasis, lists, task lists, links, images, quotes and tables. |
| A fenced code block with a language | A code block with syntax highlighting, via highlight.js. |
A fenced mermaid block | A rendered diagram. Twenty-one types, from a flowchart to a Gantt chart to a C4 context diagram — see the gallery. |
$…$ or $$…$$ | Maths, typeset with KaTeX. |
> [!NOTE], > [!WARNING] | Coloured panels. |
Deploy flow
| Stage | Owner | SLA |
|---|---|---|
| CI | Platform | 10 min |
| Staging | Release | 30 min |
A diagram, in eleven lines
One more example of the row above, rendered here by the same library the macro runs. It is a decision tree out of a runbook — the kind of thing that normally arrives as a screenshot nobody can correct.
Maths, on the page
The $$…$$ block below is from the app's own architecture note, where it costs an export job. It is typed as LaTeX and typeset by KaTeX in the browser — no image, no external service.
Sizing a diagram
Each macro carries its own layout settings, because a sequence diagram and a pie chart do not want the same treatment.
- Width
- Natural keeps the diagram's own width and scrolls inside the block — the default, and the right answer for anything wide. Fit shrinks it to the column. A number caps it at that many pixels.
- Max height
- Caps the block and scrolls inside it. Useful for a long Gantt chart you do not want owning the whole page.
- Alignment
- Left by default. A diagram is only centred when it actually fits: centring something wider than the column pushes its left edge out of reach.