Appearance
All Diagram Options for Documentation
A comprehensive visual guide to every diagram tool available for documentation sites.
Quick Comparison Table
| Tool | Type | Syntax | Best For | VitePress Support |
|---|---|---|---|---|
| Mermaid | Text-to-diagram | Markdown-like | Flowcharts, sequences, ER diagrams | Native plugin |
| PlantUML | Text-to-diagram | Custom DSL | UML, architecture | Plugin available |
| Graphviz/DOT | Text-to-diagram | DOT language | Complex graphs, networks | Via Kroki |
| D2 | Text-to-diagram | Modern DSL | Software architecture | Via Kroki |
| Excalidraw | Visual editor | JSON/Draw | Hand-drawn style | Embed/Plugin |
| Draw.io | Visual editor | XML | Complex diagrams | Embed SVG/PNG |
| Markmap | Text-to-diagram | Markdown | Mind maps | Plugin available |
| Nomnoml | Text-to-diagram | Simple DSL | UML-style | Via Kroki |
| ASCII Art | Text | Characters | Simple, universal | Native |
| Svgbob | ASCII-to-SVG | ASCII art | Convert ASCII to pretty | Via Kroki |
| Ditaa | ASCII-to-diagram | ASCII art | ASCII to boxes | Via Kroki |
| Pikchr | Text-to-diagram | PIC-like | Technical docs | Via Kroki |
| BPMN | Visual/Text | BPMN spec | Business processes | Via Kroki |
| Bytefield | Text-to-diagram | Clojure DSL | Data structures, protocols | Via Kroki |
| WaveDrom | Text-to-diagram | JSON | Digital timing | Via Kroki |
| Chart.js | JavaScript | JS/JSON | Data visualization | Custom component |
| Penrose | Text-to-diagram | Custom DSL | Mathematical diagrams | Experimental |
1. Mermaid.js (Current Choice)
Pros: Native VitePress support, large community, many diagram types, easy syntax Cons: Limited styling, can get complex for large diagrams
Flowchart
Sequence Diagram
State Diagram
Entity Relationship
Class Diagram
Gantt Chart
Pie Chart
Mindmap
Timeline
Quadrant Chart
Git Graph
2. PlantUML
Pros: Comprehensive UML support, mature, many diagram types Cons: Requires server/Java, different syntax than Mermaid
Example Syntax (rendered via Kroki or PlantUML server)
@startuml
actor User
participant "Web App" as WA
participant "API Server" as API
database "Database" as DB
User -> WA: Click button
WA -> API: POST /action
API -> DB: INSERT
DB --> API: OK
API --> WA: 200 OK
WA --> User: Show success
@endumlVisual representation:
┌─────┐ ┌─────────┐ ┌───────────┐ ┌──────────┐
│User │ │ Web App │ │API Server │ │ Database │
└──┬──┘ └────┬────┘ └─────┬─────┘ └────┬─────┘
│ Click button │ │ │
│────────────────>│ │ │
│ │ POST /action │ │
│ │─────────────────────>│ │
│ │ │ INSERT │
│ │ │────────────────────>│
│ │ │ OK │
│ │ │<────────────────────│
│ │ 200 OK │ │
│ │<─────────────────────│ │
│ Show success │ │ │
│<────────────────│ │ │3. Graphviz / DOT Language
Pros: Extremely powerful for complex graphs, automatic layout algorithms Cons: Steeper learning curve, requires external rendering
Example DOT Syntax
digraph G {
rankdir=LR;
node [shape=box, style=filled, fillcolor=lightblue];
Start -> Process1;
Start -> Process2;
Process1 -> Merge;
Process2 -> Merge;
Merge -> End;
Start [shape=circle, fillcolor=green];
End [shape=doublecircle, fillcolor=red];
}Visual representation:
┌──────────┐
│ Process1 │──────┐
└──────────┘ │
▲ ▼
┌────┴───┐ ┌────────┐ ┌─────┐
│ Start │ │ Merge │──>│ End │
└────┬───┘ └────────┘ └─────┘
│ ▲
▼ │
┌──────────┐ │
│ Process2 │──────┘
└──────────┘4. D2 (Modern Alternative)
Pros: Modern syntax, beautiful defaults, great for architecture diagrams Cons: Newer tool, smaller community
Example D2 Syntax
direction: right
user: User {
shape: person
}
frontend: Frontend {
web: Web App
mobile: Mobile App
}
backend: Backend {
api: API Server
worker: Background Worker
}
database: Database {
shape: cylinder
}
user -> frontend.web: HTTPS
user -> frontend.mobile: HTTPS
frontend -> backend.api: REST
backend.api -> database: SQL
backend.worker -> database: SQL
backend.api -> backend.worker: QueueVisual representation:
┌─────────────────────────────────────────┐
│ Frontend │
┌───────┐ │ ┌───────────┐ ┌─────────────┐ │
│ │ HTTPS │ │ Web App │ │ Mobile App │ │
│ User │──────>│ └───────────┘ └─────────────┘ │
│ │ │ │
└───────┘ └────────────────────┬────────────────────┘
│ REST
┌────────────────────▼────────────────────┐
│ Backend │
│ ┌───────────┐ ┌─────────────┐ │
│ │API Server │───>│ Worker │ │
│ └─────┬─────┘ └──────┬──────┘ │
└────────┼─────────────────┼──────────────┘
│ SQL │ SQL
▼ ▼
╭───────────────────────╮
│ Database │
╰───────────────────────╯5. Excalidraw (Hand-Drawn Style)
Pros: Beautiful hand-drawn aesthetic, visual editor, collaborative Cons: Not text-based, harder to version control
Visual Style Example
╭─────────────────╮ ╭─────────────────╮
│ │ │ │
│ Frontend │────────>│ Backend │
│ │ │ │
╰────────┬────────╯ ╰────────┬────────╯
│ │
│ │
▼ ▼
╭─────────────────╮ ╭─────────────────╮
│ │ │ │
│ CDN │ │ Database │
│ │ │ │
╰─────────────────╯ ╰─────────────────╯
(Imagine this with wobbly hand-drawn lines and
a sketch-like appearance)6. ASCII Art (Universal)
Pros: Works everywhere, no dependencies, git-friendly Cons: Limited styling, manual layout, time-consuming
Box Drawing Characters
┌─────────────────────────────────────────────────────────────┐
│ SYSTEM ARCHITECTURE │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Client │────>│ API │────>│ Database │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │
│ │ ▼ │
│ │ ┌──────────┐ │
│ └─────────>│ CDN │ │
│ └──────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘Simple ASCII (No Special Characters)
+------------------+
| Client |
+--------+---------+
|
v
+--------+---------+
| API Server |
+--------+---------+
|
v
+--------+---------+
| Database |
+------------------+7. Markmap (Mind Maps from Markdown)
Pros: Uses familiar markdown syntax, great for hierarchical info Cons: Only for mind maps
Example Markdown Source
markdown
# Project
## Frontend
- React
- TypeScript
- Tailwind
## Backend
- Node.js
- Express
- PostgreSQL
## DevOps
- Docker
- Kubernetes
- GitHub ActionsCreates an interactive mind map radiating from center
8. Nomnoml (Simple UML)
Pros: Very simple syntax, clean output Cons: Limited diagram types
Example Syntax
[User] -> [Application]
[Application] -> [Database]
[Application] -> [Cache]
[User|
+name: string
+email: string
]
[Application|
+start()
+stop()
]9. Svgbob (ASCII to Pretty SVG)
Pros: Converts ASCII art to beautiful SVG Cons: Requires rendering step
Input ASCII
+--------+
| |
| Server |----+
| | |
+--------+ |
v
.-------.
( Cloud )
`-------'Output
Renders to smooth SVG with proper curves and styling.
10. Ditaa (ASCII to Diagrams)
Pros: Rich ASCII conversion, recognizes shapes Cons: Java dependency
Input
+--------+ +-------+ +-------+
| | --+ ditaa +--> | |
| Text | +-------+ |diagram|
|Document| |!magic!| | |
| {d}| | | | |
+---+----+ +-------+ +-------+
: ^
| Lots of work |
+-------------------------+Output
Converts to colored diagram with proper shapes, shadows, and styling.
11. Chart.js / Data Visualizations
Pros: Beautiful charts, interactive, responsive Cons: Requires JavaScript, not text-based
Types Available
- Line charts
- Bar charts
- Pie/Doughnut charts
- Radar charts
- Scatter plots
- Bubble charts
- Area charts
12. BPMN (Business Process)
Pros: Standard notation, great for business workflows Cons: Complex, specific use case
Example Visual
○──────>□──────>◇──────>□──────>◎
Start Task1 Gateway Task2 End
│
└──────>□
Task313. Bytefield (Data Structures)
Pros: Perfect for protocol documentation, memory layouts Cons: Very specific use case
Example - TCP Header
┌─────────────────┬─────────────────┐
│ Source Port │ Dest Port │
├─────────────────┴─────────────────┤
│ Sequence Number │
├───────────────────────────────────┤
│ Acknowledgment Number │
├────┬──────┬──────┬────────────────┤
│Offs│Reserv│Flags │ Window │
├────┴──────┴──────┼────────────────┤
│ Checksum │ Urgent Ptr │
└──────────────────┴────────────────┘14. WaveDrom (Digital Timing)
Pros: Perfect for hardware/protocol timing diagrams Cons: Very specific use case
Example
{ signal: [
{ name: "clk", wave: "p......." },
{ name: "data", wave: "x.345x..", data: ["a","b","c"] },
{ name: "req", wave: "0.1..0.." },
{ name: "ack", wave: "1....01." }
]}Renders to:
┌─┐ ┌─┐ ┌─┐ ┌─┐ ┌─┐ ┌─┐ ┌─┐ ┌─┐
clk │ └─┘ └─┘ └─┘ └─┘ └─┘ └─┘ └─┘ └─
─────┬───┬───┬───────────────────
data xxxxx│ a │ b │ c │xxxxxxxxxxxxxxx
─────┴───┴───┴───┴───────────────
┌───────────┐
req ─────┘ └───────────────
─────────────────────┐ ┌─────
ack └─────┘Recommendation Matrix
For General Documentation
- Mermaid - Best overall, native VitePress support
- PlantUML - If you need comprehensive UML
- ASCII - For maximum compatibility
For Architecture Diagrams
- D2 - Modern, beautiful output
- Mermaid - Good enough for most cases
- Graphviz - Complex graphs
For Business Process
- Mermaid (flowcharts)
- BPMN - If you need standard notation
- PlantUML - Activity diagrams
For Hand-Drawn Style
- Excalidraw - Best visual editor
- Svgbob - If you want ASCII source
For Data/Charts
- Chart.js - Interactive charts
- Mermaid - Pie, Gantt charts
For Technical/Hardware
- WaveDrom - Timing diagrams
- Bytefield - Protocol structures
- Graphviz - State machines
VitePress Integration Guide
Native Support
- Mermaid -
vitepress-plugin-mermaid
Via Kroki (Universal Renderer)
Kroki supports: PlantUML, GraphViz, D2, Excalidraw, Nomnoml, Svgbob, Ditaa, BPMN, Bytefield, WaveDrom, and more!
js
// vitepress config for Kroki
import { defineConfig } from 'vitepress'
export default defineConfig({
markdown: {
config: (md) => {
// Add Kroki plugin for multiple diagram types
}
}
})As Embedded Images
- Export from Draw.io, Excalidraw, Lucidchart as SVG/PNG
- Reference in markdown:
Interactive Demo
Try changing between these examples to see different rendering styles!
Same Workflow - Different Tools
Mermaid:
ASCII:
┌───────┐ ┌─────────┐ ┌────────┐
│ Input │────>│ Process │────>│ Output │
└───────┘ └─────────┘ └────────┘Simple Text:
Input --> Process --> Output