Preview Mermaid diagrams and Markdown files instantly — Ctrl+click a URL in your terminal and it opens in the browser.
A zero-dependency local server for .mmd and .md files. One Python file, no pip installs, fully offline.
python3 server.py
# → http://localhost:6789
When you're coding or working with an AI agent, you shouldn't have to leave the terminal to see a diagram. The agent writes a file and prints a URL — you Ctrl+click it, the diagram opens. Edit the file, the diagram updates live. No page reload, no flash.
- AI agent workflow — Claude Code skill included. Agent writes
.mmd→ prints link → you click it - Ctrl+click in terminal — works in VS Code terminal, Windows Terminal, iTerm2, any modern terminal
- Live reload without flash — SSE-based, re-renders in place, no page blink
- Double-click from Explorer — Windows file association registers
.mmd(and optionally.md) - Zero dependencies — pure Python 3 stdlib, single file, works anywhere Python runs
- Offline — Mermaid.js loaded once from CDN, cached by browser, nothing leaves your machine
git clone https://github.com/ramonramirez/local-mermaid
cd local-mermaid
python3 server.pyOpen http://localhost:6789. Drop a .mmd file in /tmp and it appears in the index. Or point it at your project:
python3 server.py --dir ~/my-project/docscp skills/mermaid-preview.md ~/.claude/skills/Claude will write diagrams to the watch directory and give you a clickable link directly in the conversation. You Ctrl+click it without leaving the chat.
Requires WSL with Python 3.
1. Open install\windows\ in Explorer
2. Double-click install.cmd
3. Follow the prompts
- Registers
.mmdto open with local-mermaid (no admin required) - Optionally registers
.md - Detects VS Code, Sublime Text, Notepad++ — adds "Edit with..." right-click
- Creates a Startup shortcut so the server auto-starts with Windows
To uninstall: install\windows\uninstall.cmd
bash install/linux/install.shInstalls to ~/.local/bin/mermaid-preview, creates a systemd user service that starts on login.
bash install/macos/install.shInstalls to /usr/local/bin/mermaid-preview, creates a launchd agent that starts on login.
python3 server.py [OPTIONS] [DIR]
-d, --dir DIR Watch directory (default: system temp)
-p, --port PORT Port (default: 6789)
-v, --version Print version
--quiet Suppress startup output
The _open endpoint previews any file on disk — not just the watch directory:
http://localhost:6789/_open?path=/home/you/project/docs/architecture.mmd
Windows UNC paths work too (server converts automatically):
http://localhost:6789/_open?path=\\wsl.localhost\Ubuntu\home\you\project\arch.mmd
| Endpoint | Description |
|---|---|
/ |
File browser — lists all .mmd/.md in watch dir |
/diagram.mmd |
Render file from watch dir |
/_open?path=... |
Render any file by absolute path |
- Zoom & pan — scroll wheel to zoom, click-drag to pan, double-click to fit
- Lightbox — click any diagram in a
.mdfile to open fullscreen with zoom/pan - Theme switcher — System (follows OS), Light, Dark, Forest, Neutral
- SVG download — export any diagram
- Markdown rendering — prose, tables, code blocks, and multiple Mermaid diagrams in one file
server.py is a ThreadingHTTPServer (Python stdlib, zero deps). When a file is requested it injects the content into an HTML template that loads Mermaid.js and renders client-side as SVG. A single background thread watches file mtimes; each open tab subscribes via Server-Sent Events and re-renders in place when the file changes.
- Python 3.8+
- Any modern browser
- Internet for the first Mermaid.js load (CDN, cached after that)
examples/architecture.mmd— multi-tier system diagramexamples/mixed-doc.md— Markdown with tables and three Mermaid diagrams
MIT — see LICENSE.