Mermaid ELK Renderer

Share & showcase
1

Disclaimer

Is this project open source? Yes
Is this project completely free? Yes
Is this project vibe-coded beyond the author’s ability to comprehend how it works? No

Hey everyone!

I built a small plugin that re-enables ELK (Eclipse Layout Kernel) layout support for Mermaid diagrams in Obsidian. ELK was supported in older Mermaid versions but got dropped at some point. This plugin patches the Mermaid renderer to bring it back.

How it works

Add %% elk %% at the top of any mermaid code block to switch to the ELK renderer for that specific diagram. Everything else keeps using the default renderer, nothing changes globally.

```mermaid
%% elk %% ← this line enables ELK for this diagram
flowchart LR
    A[Start] --> B[Process]
    B --> C[Done]
```

Custom classDef styling and Obsidian’s light/dark mode colors are both preserved.

Why ELK?

ELK produces significantly better automatic layouts for complex graphs with many nodes and crossing edges, especially flowcharts with lots of dependencies. The default Mermaid renderer can get pretty messy above a certain complexity.

Examples

large dependency graph with custom styling
large dependency graph with custom styling1563×843 59.3 KB

Another example
Another example996×719 39.3 KB

Installation

The plugin is not yet in the Community Plugins directory (submission is in progress). Manual install for now:

  1. Download main.js, manifest.json, and styles.css from the latest release.

  2. In Obsidian:
    Settings → Community Plugins → click the folder icon at the bottom right of the installed plugins list. This opens your plugins folder.

  3. Create a new folder named mermaid-elk-renderer and drop the three files in.

  4. Restart Obsidian, enable the plugin, then restart once more.

  5. The restart after enabling is required.

Without it, the ELK renderer patch is not applied and %% elk %% diagrams will not render correctly.

Source: GitHub - SmolBlackHole/mermaid-elk-renderer · GitHub

3 Likes
Mermaid: Support Elk layout system in core Obsidian
Mermaid Fixer: updates about ability to fix quadrant charts
2

Update: now available in Obsidian Community Plugins

Small update: Mermaid ELK Renderer is now available directly through Obsidian’s Community Plugins.

That means manual installation is no longer required for most users. You can now install it from within Obsidian:

  1. Open Settings → Community plugins
  2. Search for Mermaid ELK Renderer
  3. Install and enable the plugin

Plugin page:

The latest version is currently v1.1.0.

The plugin also ships with a bundled Mermaid 11 runtime. If you want to use newer Mermaid features that are not supported by Obsidian’s built-in Mermaid version yet, enable the bundled runtime in the plugin settings.

After installing the plugin, go to the plugin settings and enable:

Use bundled Mermaid 11

Manual installation is still possible, but installing through Obsidian’s Community Plugins is now the recommended way.

3

Hello.

I stumbled upon the Mermaid: Support Elk layout system in core Obsidian thread and your plugin while searching about support for Mermaid’s Tidy-tree Layout for mindmaps in Obsidian.

@mermaid-js/layout-tidy-tree

---
config:
  layout: tidy-tree
---
mindmap
root((mindmap))
  A
  B

This looks very similar to the use case for ELK support.

Would it be possible to support this layout in a similar fashion in an single plugin? Would that make sense?

Thank you for the plugin.

1 Like
4

Hey, sorry for the slow reply. Inbox got away from me.

Mindmap layouts like tidy-tree work fine with the plugin, you just need the bundled Mermaid 11 runtime for it. Turn on Use bundled Mermaid 11 under the Experimental section in the plugin settings, then restart Obsidian. After that layout: tidy-tree in your frontmatter should render without issues.

I attached a test file with a bunch of mindmap variants so you can see the different layouts and shapes side by side and how it works and how to use it exactly.
You can download it here: Mermaid Elk Renderer Examples.md (4.5 KB). The test file contains the example-images below alongside a few other examples.

Example 1
Example 13415×1181 187 KB

Example 2
Example 21503×1257 83.9 KB

Example 3
Example 32187×437 37.7 KB

If you run into anything weird, open an issue on GitHub.

5

Mermaid ELK Renderer v1.2.0: Mermaid 11.16, new diagram types, and example files you can copy into your vault

Obsidian ships an older Mermaid version. Newer diagram types and syntax from the official Mermaid docs :link: often do not work in stock Obsidian. This plugin bundles Mermaid 11.16.0 and can use that instead.

Source and issues: GitHub :link:.

Mermaid 11.16 is now bundled

Enable Use bundled Mermaid 11 in the plugin settings and you render with Mermaid 11.16.0, bypassing Obsidian’s built-in version. That covers every diagram type from the Mermaid docs: flowchart, sequence, class, state, ER, gantt, pie with showData, gitGraph, mindmap, timeline, quadrantChart, xyChart, block, packet, architecture, radar, treemap, and sankey.

11.16 adds three more:

  • Cynefin Framework (cynefin-beta): five complexity domains with auto-generated decision models
  • Railroad Diagrams: four syntax variants. railroad-beta, railroad-ebnf-beta, railroad-peg-beta, railroad-abnf-beta
  • TreeView (treeView-beta): file trees with auto-detected icons by extension

Also new in 11.16: optional ER attribute types (string?), multiple excludes lines in gantt charts, donut pie charts, and per-point labels on XY charts.

Copy-paste example files

Grab the four Markdown files from the examples/ folder :link:, drop them into your vault, and open them with the plugin enabled:

File What it shows
layout-comparison.md dagre vs. elk on the same flowchart, plus a complex microservice graph
charts.md Pie chart with showData and XY chart with themed styling
cynefin-railroad.md Cynefin framework, all four railroad syntax variants, with explanations
er-state-arch-gantt.md ER with optional types, state diagram comparison, architecture groups, gantt with multiple excludes, and tree view

Each file tells you at the top which diagrams need bundled Mermaid.

Settings cleaned up

The settings tab is now six sections: Basics, Routing, Styling, Experimental, Support, and Danger zone at the bottom. You should not need to scroll around hunting for things.

Docs

README covers the essentials in about half the space it used to. Advanced settings has a dedicated section on the mindmap and layout-override edge case. The support page walks through debug reports step by step. And there is now an `npm run render-svgs` script if you want to regenerate the prerendered images yourself.

Full changelog

CHANGELOG.md :link:

Install

Search for “Mermaid ELK Renderer” in Community plugins, or download the release from GitHub :link:. If something breaks, open an issue here :link:.