mmd — Mermaid diagrams from your terminal, browser, or a local LLM

  ███╗   ███╗███╗   ███╗██████╗
  ████╗ ████║████╗ ████║██╔══██╗
  ██╔████╔██║██╔████╔██║██║  ██║
  ██║╚██╔╝██║██║╚██╔╝██║██║  ██║
  ██║ ╚═╝ ██║██║ ╚═╝ ██║██████╔╝
  ╚═╝     ╚═╝╚═╝     ╚═╝╚═════╝

A zero-cloud toolkit for creating Mermaid diagrams. Build them via CLI, in a local web editor with live preview, or by chatting with an offline LLM through Ollama. Everything runs on your machine — no accounts, no API keys, no data leaves your laptop.

Part of @steveapo/opensource-mini-apps — a collection of small, self-contained tools.

---

What you can do

• Convert .mmd files to SVG, PNG, or PDF from the terminal — single file or bulk folder
• Edit diagrams in a local web editor with live preview, light/dark themes, and instant export
• Generate diagrams from natural language using a local LLM (via Ollama) — e.g. "draw me the OAuth flow" and get a Mermaid diagram back
• Iterate on existing diagrams — the web chat can take your current editor contents as context so you can say "add an isHungry field to the Cat class" and get the whole diagram back with your change applied

All of this runs 100% locally. Puppeteer + bundled Chromium handle rendering; Ollama handles the LLM if you opt in.

Screenshots

Coming soon — demo GIFs of the CLI interactive mode and the web chat iterating on a diagram.

Quick start

Prerequisites

• Node.js 18 or newer
• ~200 MB free disk (Puppeteer downloads a Chromium build on first install)
• (Optional) Ollama installed and a model pulled (e.g. ollama pull qwen2.5-coder) for AI features

Install

git clone https://github.com/steveapo/mmd.git
cd mmd
./setup.sh          # macOS / Linux
# or on Windows:
powershell -ExecutionPolicy Bypass -File setup.ps1

The setup script runs npm install, builds the web bundle, and links the mmd command globally so you can run it from anywhere.

First run

# Interactive menu: convert diagrams, open web editor, or chat with AI
mmd

# Or straight to the web editor (http://localhost:3000)
mmd --web

# Or one-shot conversion
mmd --input path/to/diagram.mmd --format svg --theme dark

Drop your .mmd files into ./input/ and results appear in ./output/. Two example diagrams are included so you can try it immediately.

AI chat (optional)

If you have Ollama running, you'll see an AI chat pane in the web editor and a "Generate with AI" option in the CLI menu. It streams tokens live, auto-saves generated diagrams, and lets you iterate: describe a change, the model returns the updated full diagram, one click to apply.

Recommended models for diagram generation (strict syntax output):

ollama pull qwen2.5-coder:7b   # 4.7 GB — best for Mermaid syntax
ollama pull llama3.2:3b        # 2.0 GB — fast, good instruction-following
ollama pull mistral:7b         # 4.1 GB — solid current-gen

The model's behavior is guided by rules/mermaid-system-prompt.md — an editable file with syntax rules, response format, and room for your own project-specific vocabulary.

CLI flags

Flag	Description
-i, --input <file>	Input .mmd / .mermaid / .md file (single-file mode)
-b, --bulk	Process every file in the input folder
-f, --format <fmt>	svg, png, png-hd, png-4k, or pdf
-t, --theme <theme>	dark (default) or light
-w, --web	Launch the web editor
--input-dir <dir>	Input folder (default: ./input)
--output-dir <dir>	Output folder (default: ./output)
-q, --quiet	Suppress progress output

Architecture

• bin/mmd.js — CLI entry point (Clack-prompts TUI + Commander flags)
• server.js — Express server for the web editor + Ollama proxy (SSE streaming)
• src/renderer.js — Shared Puppeteer + Mermaid rendering pipeline (used by CLI and web export)
• src/ollama.js — Ollama detection and streaming client
• src/chat.js — Web chat UI with editor-context injection
• src/chat-ui.js — CLI chat UI
• rules/mermaid-system-prompt.md — Editable system prompt for LLM guidance
• src/*.js — Monaco editor, live preview, theme, export, templates, autocomplete

Supported diagram types

Everything Mermaid supports: flowcharts, sequence, class, state, ER, gantt, pie, mindmap, journey, quadrant, timeline, sankey, git, and more. See the Mermaid docs.

License

PolyForm Noncommercial 1.0.0 — see LICENSE.

This means you can freely use, modify, and share this project for:

• Personal use, hobby projects, study, and experimentation
• Research and academic work
• Use inside non-profit, charitable, educational, or government organizations

You cannot use it in a commercial product, a paid service, or any for-profit application without a separate commercial license. If that's something you need, open an issue to discuss.

This license is source-available but not OSI-certified "open source" — the no-commercial-use clause is what makes it non-OSI. That's a deliberate choice.

Contributing

PRs welcome for bug fixes, new diagram-type support, and improvements to the AI chat rules. For larger changes, open an issue first to align on the approach.

Credits

Built on the shoulders of:

• Mermaid — the diagram engine
• Puppeteer — rendering to SVG/PNG/PDF
• Monaco Editor — the web editor
• Ollama — local LLM runtime
• Clack + picocolors — CLI prompts and colors

---

_{Built with care as part of the opensource-mini-apps collection.}