Enhanced Markdown

Enhanced Markdown
PlantUML, Mermaid & D2 diagrams, rendered right inside VS Code's Markdown preview.

Why Enhanced Markdown?

🧩 Three diagram engines, one preview — write plantuml, mermaid or d2 fenced code blocks and see them rendered inline, exactly where you write them.
⚡ Instant Mermaid — Mermaid's rendering engine (a pure-JavaScript library) ships inside the extension, so Mermaid diagrams render with zero setup, zero installs, zero network.
🔍 A viewer built for big diagrams — diagrams open at a readable, font-anchored default size inside a scrollable viewport, with a hover toolbar and shortcuts to zoom. Long flowcharts stay crisp; tall sequence diagrams stop stretching the page.
🗄️ Render once, cache forever — every diagram is keyed by a SHA-1 content hash and cached in memory and on disk. Reopening a document never re-runs a renderer.
🧵 Fast by design — a concurrency-limited render queue with per-render timeouts, debounced preview refreshes, and an optional local HTTP server for large documents.
🛠️ Extensible — renderers are a registry; map any fence language to any renderer via enhancedMarkdown.languages.

Get started in 30 seconds

Install the extension.
Open any Markdown file and add a fenced code block tagged plantuml, mermaid or d2.
Open the preview (Ctrl/Cmd + Shift + V). Done.

You tag the block with…	Rendered by…	Anything to install?
`mermaid`	Bundled mermaid.js	Nothing ✅
`plantuml` (or `puml`)	Your local PlantUML	Java + `plantuml.jar` (Graphviz not required)
`d2`	Your local `d2` binary	d2 on PATH

No heavyweight binaries are bundled or downloaded. PlantUML, Graphviz, D2 and mermaid-cli stay on your machine, under your control — the extension just calls them. Only the Mermaid JavaScript engine is packaged, because that is what makes Mermaid work out of the box.

A viewer that respects large diagrams

Diagrams open at a font-anchored default size: the dominant text size of the rendered diagram is measured, and the whole diagram is scaled so body text lands in the usual readable 11–13px range — fonts anchor the size of every shape, line and arrow. Content is never squashed to fit the column.

The viewport has no fixed size of its own — it wraps the diagram, capped only by a maximum (the current tab's page size minus margin by default; set enhancedMarkdown.diagram.maxHeight in px to override):

Wide diagrams keep their true proportions and scroll horizontally instead of shrinking into a blur.
Tall diagrams scroll vertically once they pass the cap.

Hover any diagram for the zoom toolbar in the top-right corner:

Control	Action
`−`	Zoom out
`100%`	Reset to natural size
`+`	Zoom in
`Fit`	Fit to the preview width

Shortcuts — click a diagram once to focus it, then:

Input	Action
`Ctrl/Cmd + mouse wheel`	Zoom in / out under the cursor
`+` / `=`	Zoom in
`-`	Zoom out
`0`	Reset zoom
`f`	Fit to width

Settings

All settings live under enhancedMarkdown.* and ship with sensible defaults — you only need them to point at local tools or tune behavior.

General

Setting	Default	Description
`enable`	`true`	Master switch for diagram rendering in the preview.
`languages`	plantuml/puml, mermaid/mmd, d2	Maps a fence language to a renderer id. Extend freely.
`renderOutput`	`"data-uri"`	`"server"` serves diagrams from a local HTTP server — faster for very large documents, but requires preview security level Allow insecure local content.
`renderConcurrency`	`4`	Parallel renderer processes (1–16).
`renderTimeoutMs`	`60000`	Kill a renderer after this long.
`refreshDebounceMs`	`200`	Debounce for preview refreshes after a render finishes.
`cacheEnabled`	`true`	In-memory + disk cache keyed by content hash.
`cacheMaxAgeDays`	`30`	Disk-cache pruning age. `0` disables pruning.

PlantUML

Setting	Default	Description
`plantuml.command`	`""`	PlantUML executable; a `.jar` path here is run as `java -jar`. Takes precedence over `jarPath`.
`plantuml.jarPath`	`""`	Path to `plantuml.jar`, used when `command` is empty.
`plantuml.javaPath`	`"java"`	Java executable used to run the jar.
`plantuml.args`	`-tsvg -pipe -charset UTF-8`	Extra CLI arguments.

Mermaid

Setting	Default	Description
`mermaid.engine`	`"client"`	`client`: bundled mermaid.js in the preview (recommended). `cli`: external `mmdc`.
`mermaid.cliPath`	`"mmdc"`	Path to mermaid-cli (only for the `cli` engine).
`mermaid.cliArgs`	`[]`	Extra arguments for `mmdc`.
`mermaid.theme`	`"auto"`	`auto` follows your VS Code theme; or `default` / `neutral` / `dark` / `forest`.

D2

Setting	Default	Description
`d2.cliPath`	`"d2"`	Path to the `d2` binary.
`d2.layout`	`"default"`	Layout engine: `default` / `dagre` / `elk`.
`d2.theme`	`-1`	D2 theme id; `-1` keeps D2's default.
`d2.sketch`	`false`	Hand-drawn sketch style.
`d2.args`	`[]`	Extra CLI arguments.

Viewer

Setting	Default	Description
`diagram.maxHeight`	`0` (auto)	Max height (px) of a diagram viewport; taller diagrams scroll vertically. `0` = the tab's page height minus margin.

Commands

Command	What it does
Enhanced Markdown: Clear diagram cache	Drops all cached renders and refreshes the preview — useful after upgrading a renderer binary.

Notes & limitations

PlantUML !include resolves relative to the first workspace folder (a limitation of -pipe mode). Add -I <dir> to enhancedMarkdown.plantuml.args to point at your includes.
renderOutput: "server" binds to 127.0.0.1 on an ephemeral port and serves only image/svg+xml. The preview blocks localhost by default, so switch the preview security level to Allow insecure local content to use it.
Rendered diagram blocks carry no source line, so they are skipped by line-highlight sync; scroll sync still works.

Development

Command	Purpose
`npm run build`	Bundle `dist/extension.js` + `dist/preview.js`
`npm run typecheck`	Type-check with `tsc`
`npm test`	Smoke tests: preview bundle in a simulated DOM + markdown-it plugin output
`npm run package`	Produce the `.vsix`

_{MIT licensed · Issues & feedback: GitHub}

MulanAi