Slatebox Docs
Browse documentation
Docs / Using Slatebox

Export and import Mermaid

Read Markdown
View agent prompt
Help me complete my task in Slatebox using the official app guide. Ask which outcome I want, then walk me through the relevant steps and verify it on my slate.

Read https://docs.slatebox.com/Using-Slatebox/mermaid.md first. Ask for the inputs you need. Tell me what you verified and which steps I still need to do.

If your client cannot fetch the documentation, read the same published file at https://raw.githubusercontent.com/Slatebox/slatebox-docs/retype/Using-Slatebox/mermaid.md.

Any slate you can open comes out as Mermaid text, and a Mermaid flowchart, mind map or Gantt chart goes in as real notes and lines. It is free, uses no AI, and works the same on Slatebox Cloud and on your own server.

Export a slate

  1. In the slate, open the slate menu and choose Mermaid. The Export tab shows the slate as Mermaid.
  2. Pick a Format if you want another kind of diagram than the one chosen for you. Turn on Include colours to keep each note's colours.
  3. Choose Copy Mermaid, Copy as Markdown, Download .mmd or Download .md.

You can also open it from Export → Mermaid: export or import. A guest registers first, as for any export.

Format What you get
Automatic A mind map that is one tree as mindmap; anything else as flowchart
Flowchart Notes and lines. Direction comes from the way the lines run. Shapes, labels, arrowheads and dotted, thick or hidden lines are kept; a note drawn behind the notes it holds becomes a subgraph; a workshop's lanes become subgraphs of their cards
Mind map The tree under the root note
Gantt chart Launch plans only. Each lane is a section, each card's points are days, and the chart starts today

What Mermaid cannot say is listed as a warning, never dropped quietly. Mermaid has one broken-line style, so a dashed line is written as dotted. A line with an arrow only at its start is written from its other end. A line from a note to itself is left out.

Share a public slate's Mermaid

A public slate also has a plain-text address that always shows the slate as it is now. The Export tab shows it as Public Mermaid address.

Address Returns
/slates/your-share-id.mmd The Mermaid, as text/plain
/slates/your-share-id.md The same, in a Markdown code block

Add ?format=mindmap (or flowchart, gantt) to choose the format. It needs no token. A private slate answers 404.

Import Mermaid

  1. In a slate you can edit, open the slate menu, choose Mermaid, then Import.
  2. Paste Mermaid, or choose Open a file for a .mmd file or a Markdown file with a Mermaid block. A line such as “Ready: a flowchart of 3 notes and 2 lines, in 1 frame.” says what will be drawn.
  3. Choose Add to this slate or Open as a new slate.

You get real notes and lines laid out in the diagram's direction. Subgraphs and Gantt sections arrive as frames. Everyone on the slate sees the diagram drawn.

Mermaid Read
flowchart and graph Every link form, chains, &, subgraphs, @{ shape: … }, classDef, class and style colours, and click links to web pages
mindmap The tree, with its node shapes
gantt Sections as frames and tasks as notes; durations stay in the note's text
Any other kind Refused by name, and nothing is added

One import takes up to 100,000 characters and 1,000 notes, counting frames.

Export and import from an exec script

Agents use the same two calls on every surface: the hosted MCP endpoint, the slatebox command and POST /api/v1/exec. Save the script as mermaid.js:

JavaScript
const shareId = "your-share-id"
const { mermaid, warnings } = await slatebox.slates.exportMermaid({ shareId })

const drawn = await slatebox.slates.importMermaid({
  mermaid: "flowchart LR\n  idea --> plan --> ship",
  name: "From the README",
})
return { mermaid, warnings, url: drawn.url, notes: drawn.notes }
TypeScript
const shareId: string = "your-share-id"
const { mermaid, warnings } = await slatebox.slates.exportMermaid({ shareId })

const drawn = await slatebox.slates.importMermaid({
  mermaid: "flowchart LR\n  idea --> plan --> ship",
  name: "From the README",
})
return { mermaid, warnings, url: drawn.url, notes: drawn.notes }

Preview it first. The Node.js and Python tabs use the exec.mjs and exec.py helpers from Run a script.

Node.js
node exec.mjs mermaid.js --preview
Python
python3 exec.py mermaid.js --preview
curl
jq -n --rawfile code mermaid.js --arg key "$(uuidgen)" \
  '{intent: "Export and import Mermaid", code: $code, mode: "preview", idempotencyKey: $key}' |
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $SLATEBOX_API_TOKEN" -H 'Content-Type: application/json' \
  --data @- "$SLATEBOX_BASE_URL/api/v1/exec"
CLI
npx --no-install slatebox exec mermaid.js --remote --preview

The result holds the slate's Mermaid and what the import would draw; a preview saves nothing. Run it again without --preview (or with mode: "save") to create the new slate. Leave out name and pass shareId to importMermaid to add the diagram to a slate you can edit.

Call Input Returns
slatebox.slates.exportMermaid shareId, format (auto, flowchart, mindmap, gantt), styles, start (a Gantt chart's first day, YYYY-MM-DD) mermaid, markdown, format, formats, warnings, publicUrl
slatebox.slates.importMermaid mermaid (or Markdown with a Mermaid block), shareId or name shareId, url, kind, notes, frames, lines, created, warnings, message

Export and import over HTTP

Read a slate as Mermaid with slates:read. A public slate needs no token.

Node.js
const res = await fetch(`${process.env.SLATEBOX_BASE_URL}/api/v1/slates/${process.env.SLATEBOX_SHARE_ID}/mermaid?format=auto`, {
  headers: { Authorization: `Bearer ${process.env.SLATEBOX_API_TOKEN}` },
})
const { mermaid, warnings } = await res.json()
console.log(mermaid, warnings)
Python
import os, requests

res = requests.get(
    f"{os.environ['SLATEBOX_BASE_URL']}/api/v1/slates/{os.environ['SLATEBOX_SHARE_ID']}/mermaid",
    params={"format": "auto"},
    headers={"Authorization": f"Bearer {os.environ['SLATEBOX_API_TOKEN']}"},
)
body = res.json()
print(body["mermaid"], body["warnings"])
curl
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $SLATEBOX_API_TOKEN" \
  "$SLATEBOX_BASE_URL/api/v1/slates/$SLATEBOX_SHARE_ID/mermaid?format=auto"

You get 200 with mermaid, markdown and any warnings.

Draw Mermaid with slates:write. Send shareId to add to that slate, or leave it out for a new private slate. Send "mode": "preview" to see the counts without saving.

Node.js
const res = await fetch(`${process.env.SLATEBOX_BASE_URL}/api/v1/slates/mermaid`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SLATEBOX_API_TOKEN}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ mermaid: 'flowchart LR\n  idea --> plan --> ship', name: 'From the README' }),
})
console.log(res.status, await res.json())
Python
import os, uuid, requests

res = requests.post(
    f"{os.environ['SLATEBOX_BASE_URL']}/api/v1/slates/mermaid",
    headers={
        "Authorization": f"Bearer {os.environ['SLATEBOX_API_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"mermaid": "flowchart LR\n  idea --> plan --> ship", "name": "From the README"},
)
print(res.status_code, res.json())
curl
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $SLATEBOX_API_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  --data '{"mermaid":"flowchart LR\n  idea --> plan --> ship","name":"From the README"}' \
  "$SLATEBOX_BASE_URL/api/v1/slates/mermaid"

You get 201 with the new slate's shareId and url, and notes: 3, lines: 2. A retry with the same key returns the original result.

What a round trip keeps

Mermaid → slate → Mermaid keeps the notes, labels, lines, arrowheads and subgraphs, and a second trip writes the same text.

Changes Why
A shape with no slate counterpart becomes the nearest one (a cylinder or subroutine becomes a rectangle) The slate has no such shape
o and x line ends become arrows The slate draws arrowheads only
Two lines between the same two notes become one A slate holds one line per pair
An id a note cannot hold changes (v1.2 becomes v1_2) Note ids take letters, digits, - and _

Troubleshooting

Symptom Fix
“This is a sequence diagram, which it can't draw as notes yet, so nothing was added.” Only flowcharts, mind maps and Gantt charts are drawn. Export them from your source as one of those.
400 mermaid_invalid naming a line Fix that line. Write A -- text --> B with spaces around the label.
422 mermaid_too_large Split the diagram: one import takes up to 1,000 notes and 5,000 lines, frames up to 50 deep.
Mermaid is missing from the slate menu You can read this slate but not change it. A public slate's Mermaid is still at its .mmd address.
Gantt chart is not in the Format list Gantt is offered for launch plans only.