Mermaid Diagrams in Obsidian: Setup, Styling, and Export

Obsidian renders Mermaid natively. A fenced code block tagged mermaid turns into a diagram in Reading view and in Live Preview, with no plugin and no network call. Diagrams live inside the note as text, so they sync, diff, and search like everything else in the vault.

The rendering part takes thirty seconds to learn. The parts people search for later are styling, version differences, and getting a diagram out of the vault as an image. This post covers all four.

The code block

Open a note in Source mode or Live Preview and type three backticks followed by mermaid, then the diagram, then three closing backticks. In Live Preview the block renders as soon as the cursor leaves it; click the rendered diagram to edit the code again. In Reading view it is always rendered.

flowchart TD
    Daily[Daily note] --> Project[Project page]
    Project --> Decision{Decision needed?}
    Decision -- Yes --> ADR["Decision record (ADR)"]
    Decision -- No --> Tasks[Task list]
    ADR --> Review[Weekly review]
    Tasks --> Review

Two habits save time. First, keep one diagram per block; Obsidian cannot render two diagram headers in a single fence. Second, write the diagram in Source mode if it is long. Live Preview re-renders on every pause, which is helpful for small diagrams and distracting for a thirty-line sequence diagram.

Which Mermaid version you are running

Obsidian ships a specific Mermaid build and updates it with Obsidian releases, typically a few versions behind the latest Mermaid. That matters in two cases. Newer diagram types, for example architecture or packet diagrams, may be unknown to the bundled version. And syntax tightening in newer releases can make a diagram that renders in Obsidian fail in a tool on the current version.

When a diagram fails and you cannot tell whether the cause is version or syntax, paste it into the MermanDraw editor, which tracks a current Mermaid release. If it renders there and not in Obsidian, the gap is the version. If it fails in both, the editor marks the line and offers a fix for common mistakes such as quotes, arrows, and stray Markdown fences.

Styling with a CSS snippet

Obsidian wraps each diagram in an element with the class mermaid, and the body carries theme-dark or theme-light. A CSS snippet can therefore center diagrams, add padding, and recolor nodes for each mode. Create the file in .obsidian/snippets/, then enable it under Settings → Appearance → CSS snippets.

/* .obsidian/snippets/mermaid.css */
.mermaid {
  display: flex;
  justify-content: center;
  padding: 1rem 0;
}

.theme-dark .mermaid .node rect,
.theme-dark .mermaid .node polygon {
  fill: #1e1b4b;
  stroke: #818cf8;
}

.theme-light .mermaid .node rect,
.theme-light .mermaid .node polygon {
  fill: #eef2ff;
  stroke: #6366f1;
}

Mermaid's SVG uses many class names (.node, .edgeLabel, .actor, .messageText, and so on). Open the developer console with Ctrl/Cmd+Shift+I, inspect a rendered diagram, and copy the selectors you need. Snippets apply to the whole vault, which is the point: every diagram picks up the same look.

Per-diagram themes with an init directive

When one diagram needs a different palette, use a Mermaid directive instead of CSS. The first line of the block sets the theme and any theme variables for that diagram only:

%%{init: {'theme': 'dark', 'themeVariables': {'primaryColor': '#312e81'}}}%%
stateDiagram-v2
    [*] --> Inbox
    Inbox --> Processing : triage
    Processing --> Done : complete
    Processing --> Someday : defer
    Someday --> Inbox : revisit
    Done --> [*]

The built-in themes are default, dark, forest, neutral, and base. The base theme exists to be customized through themeVariables. The state diagram guide and flowchart guide list the variables that matter most for each type.

Getting a diagram out as an image

Right-clicking a rendered diagram offers no "copy image" option in a stock vault. Three routes work:

1. Export to PDF. File menu → Export to PDF. The diagram is rendered into the PDF at print resolution. Good for sharing a whole note; clumsy for extracting one diagram.
2. A community plugin. Search Community plugins for "Mermaid". Several add an export button or a right-click action that saves the block as PNG or SVG. Check the plugin's last update date before relying on it.
3. Render outside the vault. Copy the code block, paste it into MermanDraw, pick a theme, and download PNG at 2× resolution or SVG. The editor strips the fence lines on paste, so you can copy the whole block including the backticks.

The third route also produces a share link with a preview image, which is useful when the diagram goes to someone who does not use Obsidian. The export guide compares PNG and SVG for slides, documents, and email.

Where to go from here

The cheatsheet covers every diagram type with a copy-paste example, and the examples gallery has complete diagrams for architecture, process, and planning notes. For a list of every tool that renders a mermaid block natively, see where Mermaid renders natively.

FAQ

Related

• Mermaid diagrams in Notion — code block preview and its limits.
• Mermaid in VS Code — preview extensions and CLI export.
• Mermaid in a GitHub README