Mermaid to tldraw

Batch-convert every fenced mermaid diagram in a folder of Markdown files into tldraw-styled SVG or PNG assets.

This repository is also a Codex plugin marketplace. The plugin lives under plugins/mermaid-tldraw/, and its bundled skill teaches Codex how to run and verify the converter.

Mermaid is converted to native tldraw shapes in a headless browser, then exported through tldraw. Unsupported Mermaid diagram types fall back to Mermaid's SVG inside tldraw.

Install the Codex plugin

Add this public GitHub repository as a Codex plugin marketplace, then install the plugin:

codex plugin marketplace add matijagrcic/mermaid-tldraw
codex plugin add mermaid-tldraw@mermaid-tldraw

Start a new Codex thread after installation so the mermaid-tldraw skill is available.

Update the Codex plugin

Pull the latest marketplace snapshot, then reinstall the plugin:

codex plugin marketplace upgrade mermaid-tldraw
codex plugin add mermaid-tldraw@mermaid-tldraw

Start a new Codex thread after updating.

Setup

Requires Bun.

cd plugins/mermaid-tldraw
bun install
bunx playwright install chromium

Usage

bun run convert ./notes --out-dir ./diagrams --format svg
bun run convert ./notes --out-dir ./diagrams --format png
bun run convert ./notes --out-dir ./diagrams --format both --theme both

Options:

--out-dir <folder>        Output folder (default: ./diagrams)
--format <svg|png|both>   Output format (default: svg)
--theme <light|dark|both> Theme variant (default: light)
--padding <pixels>        Padding around each diagram (default: 16)
--scale <number>          PNG resolution multiplier (default: 2)

The source folder structure is preserved. For example, the second diagram in notes/guides/setup.md becomes:

diagrams/guides/setup--diagram-2.svg

When --theme both is used, filenames include .light and .dark.

Example

bun run convert examples --out-dir diagrams --format both

Plugin validation

python3 /path/to/plugin-creator/scripts/validate_plugin.py plugins/mermaid-tldraw
python3 /path/to/skill-creator/scripts/quick_validate.py plugins/mermaid-tldraw/skills/mermaid-tldraw
cd plugins/mermaid-tldraw
bun test
bun run check

Credit

This project builds on the Mermaid-to-tldraw rendering approach introduced by Sunil Pai (threepointone) in threepointone/sunilpai-dev commit f4bd28a.