🧜 Mermaid File Viewer

A local web app for live-editing and previewing Mermaid diagrams.
Diagrams live as plain .mmd files on disk — edit in the browser or in any external editor.
Both sync instantly via WebSocket. This allows to change local files and see your results, without the need to start any additional IDE plugins etc.

┌─────────────────┬──────────────────────────┬────────────────────────┐
│  File tree      │  Monaco Editor           │  Live preview          │
│                 │  (VS Code engine)        │                        │
│ ⬡ getting-…    │                          │                        │
│ ⬡ arch.mmd     │  flowchart TD            │   ┌──────┐            │
│ ⬡ seq.mmd  ←   │    A[Start] --> B        │   │Start │            │
│                 │    B --> C[End]          │   └──┬───┘            │
│  [＋ New file]  │                          │      ↓                 │
│                 │  auto-save · Ctrl+S      │   ┌──────┐            │
└─────────────────┴──────────────────────────┴───│ End  │────────────┘
                                                  └──────┘

Note that this repo was mostly generated with anthropic models and might be messy here and there.

Quick start

Option 1 — npx (no install needed)

# From this project directory — works right now, no npm publish required
npx .

# From anywhere, once the package is published on npm
npx mermaid-file-viewer
npx mermaid-file-viewer ./my-diagrams
npx mermaid-file-viewer /abs/path --port 4000
npx mermaid-file-viewer --no-open     # skip auto-opening the browser

Option 2 — global install (after publishing)

npm install -g mermaid-file-viewer

mermaid-viewer                        # watch ./diagrams, port 3000
mermaid-viewer ./my-diagrams          # custom directory
mermaid-viewer --port 4000            # custom port
mermaid-viewer --help                 # full usage

Option 3 — shell script (local, opens browser automatically)

./start.sh                          # watches ./diagrams, port 3000
./start.sh /path/to/your/diagrams   # custom directory
PORT=4000 ./start.sh                # custom port

start.sh installs node_modules on the first run if needed and finds a free port automatically.

Option 4 — npm scripts

npm install        # only needed once
npm start          # node server.js  (PORT / DIAGRAMS_DIR env vars respected)
npm run dev        # same, but restarts on server file changes (Node 18+)
npm run open       # same as npx . — also opens the browser

Option 5 — Docker Compose

docker compose up          # mounts ./diagrams into the container

Then open http://localhost:3000

To point at a different directory on your host, edit docker-compose.yml:

volumes:
  - /absolute/path/to/your/diagrams:/data

Option 6 — plain Docker

docker build -t mermaid-viewer .

docker run -p 3000:3000 \
  -v /absolute/path/to/your/diagrams:/data \
  mermaid-viewer

Environment variables

| Variable | Default | Description | |----------------|---------------|------------------------------------| | PORT | 3000 | HTTP / WebSocket port | | DIAGRAMS_DIR | ./diagrams | Directory of .mmd files to watch |

Keyboard shortcuts

| Shortcut | Action | |--------------|-----------------------------| | Ctrl+S | Save immediately | | Ctrl+N | New file | | Ctrl+Space | Force autocompletion popup | | Tab | Accept suggestion / indent | | Escape | Dismiss suggestion / modal |

Autocompletion

Completions are context-aware — they know which diagram type you're editing.

On line 1 (empty file or first line) → all diagram types appear as full scaffolding snippets with tab stops:

flowchart TD      sequenceDiagram   classDiagram
stateDiagram-v2   erDiagram         gantt
pie               gitGraph          mindmap
timeline          xychart-beta      quadrantChart

Inside a diagram → targeted keyword and snippet completions:

| Diagram | What you get | |---------------------|------------------------------------------------------------| | flowchart / graph | All node shapes, arrow variants, subgraph, classDef | | sequenceDiagram | participant, actor, every arrow type, loop/alt/par blocks | | classDiagram | class, all relationship types, annotations, namespace | | stateDiagram-v2 | state, transition, fork/join/choice, concurrent regions | | erDiagram | entity with attributes, all cardinality combos, PK/FK/UK | | gantt | title, dateFormat, section, task variants (active/crit) | | gitGraph | commit, branch, checkout, merge, cherry-pick | | mindmap | root shapes, icon, class | | pie / timeline | slices, sections, events |

How it works

Your editor (or Monaco)
        │
        │  writes file
        ▼
  📁 diagrams/foo.mmd          ← plain text, always on disk
        │
        │  chokidar detects change
        ▼
  Node.js server
        │
        │  WebSocket broadcast { type: "changed", content }
        ▼
  Browser
        │  Monaco editor updated (cursor preserved)
        │  Mermaid.js re-renders (280 ms debounce)
        ▼
  Live preview ✓

Auto-save path (typing in browser Monaco):

keystroke → 280 ms debounce → Mermaid re-render
keystroke → 1200 ms debounce → POST /api/files/:name → file saved
Ctrl+S                       → immediate save

REST API

| Method | Path | Body / Response | |----------|----------------------------|------------------------------| | GET | /api/files | ["a.mmd", "b.mmd"] | | GET | /api/files/:name | { content: "..." } | | POST | /api/files/:name | { content } → { ok } | | DELETE | /api/files/:name | { ok } | | POST | /api/files/:name/rename | { newName } → { ok } | | GET | /api/info | { dir: "/abs/path" } |

WebSocket events (server → browser):

{ "type": "init",    "files": ["a.mmd", "b.mmd"] }   // on connect
{ "type": "added",   "name": "new.mmd" }
{ "type": "changed", "name": "foo.mmd", "content": "…" }
{ "type": "deleted", "name": "old.mmd" }

Project structure

mermaid-file-viewer/
├── server.js            Express + WebSocket + chokidar file watcher
├── public/
│   ├── index.html       App shell, CDN script tags (no build step)
│   ├── style.css        Dark theme, three-panel resizable layout
│   └── app.js           Monaco editor + Mermaid language + file tree + WS
├── diagrams/            Default watched directory (sample files included)
├── start.sh             Smart launch script (auto-install, free port, browser)
├── Dockerfile
├── docker-compose.yml
└── package.json

Publishing to npm

If you want npx mermaid-file-viewer to work for anyone, anywhere:

# 1. Make sure you're logged in
npm login

# 2. Bump the version if needed
npm version patch   # or minor / major

# 3. Publish (only the files listed in "files" in package.json are uploaded)
npm publish

The files field in package.json ensures only bin/, public/, and server.js are shipped — no node_modules, no diagrams/, no dot-files.

After publishing, anyone can run:

npx mermaid-file-viewer ./my-diagrams

Tips

• Rename a file by clicking ✎ next to it in the sidebar — the URL and open tab update automatically.
• Drag the dividers between panels to resize them; positions are remembered across reloads.
• Switch diagram theme (Dark / Default / Forest / Neutral) from the header — affects only the rendered SVG.
• Switch preview background between Dark and Light — useful when the default Mermaid theme renders on white.
• Zoom the preview with ＋ － ⊙ buttons without affecting the file.
• Files are watched with depth 0 — subdirectories are intentionally ignored (flat list).