Best Mermaid

English | 简体中文

Diagrams that feel like they belong in your notes.

Your notes have a theme. Your diagrams don't — the same purple boxes, mismatched fonts, and edges that cross like spaghetti. Best Mermaid re-renders every mermaid diagram in your vault with your theme's own colors, curated styles, and professional layout. No configuration. No new syntax.

Install it, open a note, and it just looks right.

• ✦ Zero config — your existing diagrams look better the moment the plugin loads
• ✦ Follows your theme — light/dark, custom CSS, accent colors: diagrams dress accordingly
• ✦ Style packs — one line switches a diagram to a print-ready or presentation look
• ✦ Stays offline — mermaid and elk are bundled; nothing leaves your vault

Left: the default Obsidian mermaid renderer. Right: Best Mermaid with the Paper style — theme-matched grayscale palette and clean orthogonal routing.

Ctrl + scroll zooms at the cursor (trackpad pinch works too); drag to pan; double-click to reset — zoom stays put across re-renders.

Click the download icon at the bottom-right of any diagram: edit the file name, pick 1x–4x quality, and save anywhere through the native save dialog.

The style gallery: four built-in style packs with live swatches. Pick a default here; override any single diagram with %% bm-style: <id> %%.

Why another mermaid plugin?

There are several mermaid appearance plugins already. Best Mermaid differs in a few ways:

• Style packs, not just color tweaks. Each style is a complete, self-describing card: palette, typography, line style, spacing, and even the layout engine. Switching a style re-lays out the diagram.
• Theme fusion. Diagram colors are resolved from your theme's CSS variables through a probe element, so diagrams follow your light/dark theme (and custom theme CSS) instead of mermaid's fixed palettes.
• Style choice travels with the diagram. A per-diagram directive in the code block keeps your style choice when you copy the block or sync the note.
• Engine and style are linked. The print-oriented style automatically uses the elk layout engine for orthogonal routing; other styles use dagre. You can also pin the engine in settings.

Features

• Take over rendering of ```mermaid blocks in reading view, replacing the built-in renderer
• Style packs with a gallery in settings — 4 built-in styles:
  • Follow theme — colors resolved from Obsidian CSS variables, follows light/dark
  • Midnight — slate night + indigo accent for screenshots and presentations
  • Paper — black & white orthogonal routing (elk), print/export friendly
  • Terra — warm, humanist palette for teaching and sharing
• Per-diagram style override that lives in the diagram source
• %%{init}%% directives respected — in-diagram directives merge over plugin settings (user intent always wins); themeCSS appends instead of replacing
• Layout engine: dagre (default) or elk with orthogonal edge routing, switched per style, per diagram, or globally
• Pan & zoom: Ctrl + scroll to zoom at the cursor (trackpad pinch works), drag to pan, double-click to reset; zoom state survives re-renders
• Horizontal alignment of rendered diagrams (left / center / right)
• Readable errors: syntax problems render as a visible error box with the offending line, never a silent blank
• Render cache + serial render queue: concurrent diagrams can't clobber each other's config; identical diagrams render once
• Fully offline — mermaid and elk are bundled, no network requests, no telemetry

Usage

Write mermaid blocks as usual:

```mermaid
flowchart LR
    A[Start] --> B[End]
```

Pin a style to a diagram (the directive is a comment — Obsidian without this plugin ignores it safely):

```mermaid
%% bm-style: midnight %%
flowchart LR
    A --> B
```

In-diagram customization still works and takes priority over the plugin:

```mermaid
%%{init: {'themeVariables': {'primaryColor': '#ffd54f'}}}%%
flowchart TB
    A[Custom gold] --> B
```

Built-in style ids

Interactions (reading view)

Limitations

• Live Preview (editing view) still uses Obsidian's built-in mermaid renderer; this plugin takes over the reading view
• Desktop only for now (isDesktopOnly: true); the bundle includes mermaid + elk (~12 MB)

Development

npm install
npm run dev     # esbuild watch
npm test        # vitest + jsdom, real mermaid render pipeline tests
npm run build   # type-check + production bundle

Manual install for testing: copy main.js, manifest.json, styles.css into <vault>/.obsidian/plugins/best-mermaid/.

License

MIT