Mermaid Studio documentation

Mermaid Studio draws Mermaid diagrams on your Confluence pages. This guide covers setup, everyday use, limits and troubleshooting.

Setup

1. Install the app. A Confluence site admin opens the Atlassian Marketplace, finds Mermaid Studio for Confluence and chooses Get app.
2. Open a page. Go to any Confluence page and choose Edit.
3. Type /mermaid. Pick Mermaid Studio from the menu.
4. Pick a template. In the editor, choose Templates and select the diagram type you want.
5. Save. Choose Save in the editor, then publish the page. Your diagram is drawn on the page.

There is nothing to configure and no account to create. The app is free for up to 10 users.

Using Mermaid Studio

Write a diagram

Type Mermaid text in the editor, for example:

flowchart LR
  A[Idea] --> B[Draft] --> C[Publish]

Mermaid 12 is supported, with 20+ diagram types including flowchart, sequence, class, state, ER, Gantt, pie, mindmap, timeline, gitGraph, C4, architecture, kanban, packet, radar and treemap.

Code, Split and Preview

Use the tabs at the top of the editor to switch between Code, Split and Preview. In Split, drag the divider to give the code or the preview more room. The preview updates as you type.

Highlighting, autocomplete and error markers

The editor colours Mermaid syntax, suggests keywords as you type, and marks the line number of any mistake so you can fix it before saving. While you edit, a change that breaks the diagram keeps showing the last valid preview. If you save a diagram that still has a mistake, the editor asks you to confirm first.

Templates

Choose Templates to start from an example for every diagram type. Picking one replaces the text in the editor.

Themes, looks and layout

Open the options under the editor to choose a theme. Match Confluence follows your light or dark setting. You can also choose the neo or hand-drawn look, and ELK layout, which helps with large or crowded diagrams.

Zoom, pan and full screen

On the published page, use the toolbar above the diagram to zoom in and out, reset the zoom, and open the diagram full screen. Drag to pan, and hold Ctrl (⌘ on Mac) and scroll, or pinch, to zoom.

Copy and download

The toolbar has Copy PNG, Copy SVG, PNG and SVG download buttons. Use them to paste a diagram into a slide or an email.

PDF and Word export

When you export a page to PDF or Word, your diagrams are included as images. Open and save a diagram once in the editor so its image is up to date. If an image is not available, the export shows the diagram text instead.

Convert existing code blocks

If a page already has Mermaid code blocks, open the page's more actions menu and choose Convert Mermaid code blocks. The app tells you how many it found. Choose Convert to turn them into live diagrams. Code blocks inside lists, quotes or panels are left as code. This saves a new page version, so you can restore the old one from page history. You need edit permission on the page.

Use a .mmd file as the source

Attach a .mmd file to the page. In the editor, use the source drop-down (it starts as Source: written here) and choose the file. The diagram is drawn from the file. To change it, edit the file on the page.

Accessible titles and descriptions

Add accTitle and accDescr lines to your diagram text. They become the diagram's accessible name and description, and its alt text.

flowchart LR
  accTitle: Publishing steps
  accDescr: An idea becomes a draft, then is published.
  A[Idea] --> B[Draft] --> C[Publish]

All toolbar buttons are labelled and can be reached with the keyboard.

Limits

• Diagram text: up to 100 KB per diagram. The editor shows your size at the bottom and will not save above the limit.
• A .mmd file attached as a source: up to 1 MB.

Messages you might see

• This diagram has a syntax error on line N. The diagram text has a mistake. On the page, a diagram saved with a mistake shows this message with the line number instead of the diagram. Open the editor and fix the marked line.
• The attached diagram file could not be found. It may have been deleted or renamed. Re-attach the file, or choose another source.
• The attached diagram file is larger than 1 MB. Shorten the file.
• You do not have permission to view the attached diagram file. Ask the page owner for access.
• You need edit permission on this page to convert code blocks. Ask for edit access, then try again.
• Someone else changed this page. Refresh and try again. Reload the page and repeat the conversion.
• No Mermaid code blocks found on this page. Nothing to convert.

Getting help

Use the support portal or email support@wattlebrooks.com. See also the support page.