Complete Guide to Creating Diagrams in MD Editor: Mermaid, Graphviz, and Markmap
Technical documentation often requires clear visualizations to explain complex systems, workflows, and relationships. MD Editor now supports four powerful diagramming formats that let you create professional diagrams directly in your markdown documents. In this guide, we'll explore each diagram type with practical examples.
Why Use Diagrams in Markdown?
Before diving into the specifics, let's understand why embedding diagrams in markdown is powerful:
- Version Control: Diagrams are stored as text, making them easy to track in Git
- Collaboration: Team members can review and edit diagrams just like code
- Consistency: Diagrams use the same syntax everywhere, no proprietary formats
- Automation: Diagrams automatically render in exports (HTML, PDF, DOCX)
- No External Tools: Create professional diagrams without leaving your editor
Mermaid: Versatile Diagrams for Every Need
Mermaid.js is the most versatile option, supporting multiple diagram types from a single syntax.
Flowcharts
Perfect for decision trees and process flows:
flowchart TD
A[Start] --> B{Is it working?}
B -->|Yes| C[Great!]
B -->|No| D[Debug]
D --> E[Fix the bug]
E --> B
C --> F[Deploy]
Sequence Diagrams
Ideal for API interactions and system communication:
sequenceDiagram
participant User
participant Frontend
participant API
participant Database
User->>Frontend: Submit form
Frontend->>API: POST /api/users
API->>Database: INSERT user
Database-->>API: User created
API-->>Frontend: 201 Created
Frontend-->>User: Success message
Gantt Charts
Great for project timelines and scheduling:
gantt
title Project Development Timeline
dateFormat YYYY-MM-DD
section Planning
Requirements gathering :2024-01-01, 14d
System design :2024-01-08, 10d
section Development
Frontend development :2024-01-15, 30d
Backend development :2024-01-20, 35d
section Testing
Integration testing :2024-02-20, 10d
User acceptance testing :2024-02-25, 7d
State Diagrams
Perfect for modeling application states and transitions:
stateDiagram-v2
[*] --> Idle
Idle --> Loading: User clicks
Loading --> Success: Data loaded
Loading --> Error: Request failed
Success --> Idle: Reset
Error --> Idle: Retry
Success --> [*]
Entity Relationship Diagrams
Essential for database design:
erDiagram
USER ||--o{ ARTICLE : writes
USER ||--o{ COMMENT : posts
ARTICLE ||--o{ COMMENT : has
USER {
string id PK
string email
string name
datetime created_at
}
ARTICLE {
string id PK
string user_id FK
string title
text content
datetime published_at
}
COMMENT {
string id PK
string user_id FK
string article_id FK
text content
datetime created_at
}
Graphviz & DOT: Powerful Graph Layouts
Graphviz excels at creating complex graph structures with sophisticated automatic layouts.
Directed Graphs
Perfect for dependency trees and network topologies:
digraph Architecture {
rankdir=TB;
node [shape=box, style=rounded];
Frontend [label="React Frontend"];
API [label="REST API"];
Cache [label="Redis Cache"];
DB [label="PostgreSQL"];
Queue [label="Message Queue"];
Worker [label="Background Worker"];
Frontend -> API [label="HTTPS"];
API -> Cache [label="Read/Write"];
API -> DB [label="SQL"];
API -> Queue [label="Enqueue"];
Queue -> Worker [label="Process"];
Worker -> DB [label="Update"];
}
Undirected Graphs
Great for network relationships and clustering:
graph Network {
layout=neato;
node [shape=circle];
A -- B [label="10ms"];
A -- C [label="15ms"];
B -- C [label="8ms"];
B -- D [label="12ms"];
C -- D [label="7ms"];
C -- E [label="20ms"];
D -- E [label="9ms"];
A [label="Server A"];
B [label="Server B"];
C [label="Server C"];
D [label="Server D"];
E [label="Server E"];
}
Hierarchical Structures
Ideal for organization charts and file systems:
digraph OrgChart {
node [shape=box, style="rounded,filled", fillcolor=lightblue];
CEO [label="CEO"];
CTO [label="CTO"];
CFO [label="CFO"];
VP_Eng [label="VP Engineering"];
VP_Product [label="VP Product"];
Team_Lead_1 [label="Team Lead 1"];
Team_Lead_2 [label="Team Lead 2"];
CEO -> CTO;
CEO -> CFO;
CTO -> VP_Eng;
CTO -> VP_Product;
VP_Eng -> Team_Lead_1;
VP_Eng -> Team_Lead_2;
}
Cluster Diagrams
Perfect for microservices architecture:
digraph Microservices {
compound=true;
rankdir=LR;
subgraph cluster_frontend {
label="Frontend Cluster";
style=filled;
color=lightgrey;
WebApp [label="Web App"];
MobileApp [label="Mobile App"];
}
subgraph cluster_backend {
label="Backend Services";
style=filled;
color=lightblue;
AuthService [label="Auth Service"];
UserService [label="User Service"];
OrderService [label="Order Service"];
}
subgraph cluster_data {
label="Data Layer";
style=filled;
color=lightyellow;
UserDB [label="User DB"];
OrderDB [label="Order DB"];
}
WebApp -> AuthService;
MobileApp -> AuthService;
AuthService -> UserService;
UserService -> UserDB;
OrderService -> OrderDB;
}
Markmap: Interactive Mind Maps
Markmap transforms markdown lists into beautiful, hierarchical mind maps.
Knowledge Organization
# Technical Documentation Guide
## Planning
- Define audience
- Set objectives
- Outline structure
- Gather resources
## Writing
- Introduction
- Purpose
- Scope
- Prerequisites
- Main Content
- Step-by-step guides
- Code examples
- Best practices
- Conclusion
- Summary
- Next steps
- Resources
## Review
- Technical accuracy
- Clarity and readability
- Code testing
- Peer review
## Publishing
- Export formats
- HTML
- PDF
- Markdown
- Distribution
- Documentation site
- GitHub repository
- Internal wiki
Feature Planning
# Application Features
## User Management
- Authentication
- Email/Password
- OAuth (Google, GitHub)
- 2FA
- User Profiles
- Personal information
- Preferences
- Avatar upload
- Permissions
- Role-based access
- Custom permissions
- Team management
## Content Management
- Editor
- Markdown support
- Real-time preview
- Auto-save
- Organization
- Folders
- Tags
- Search
- Collaboration
- Sharing
- Comments
- Version history
## Export & Publishing
- Formats
- HTML
- PDF
- DOCX
- Publishing
- Medium
- Dev.to
- GitHub
Learning Path
# Full-Stack Development Path
## Frontend
- HTML/CSS
- Semantic HTML
- Responsive design
- CSS Grid & Flexbox
- JavaScript
- ES6+ features
- Async programming
- DOM manipulation
- React
- Components
- Hooks
- State management
- Next.js
## Backend
- Node.js
- Express.js
- API design
- Authentication
- Databases
- SQL (PostgreSQL)
- NoSQL (MongoDB)
- ORMs
- DevOps
- Docker
- CI/CD
- Cloud platforms
How to Use Diagrams in MD Editor
Using diagrams in MD Editor is simple:
- Create a code block with the diagram type as the language
- Write your diagram code using the syntax for that type
- The diagram renders automatically in the preview
- Export to any format (HTML, PDF, DOCX) and diagrams are included as images
Example Syntax
For Mermaid:
```mermaid
graph TD
A --> B
```
For Graphviz:
```graphviz
digraph G {
A -> B
}
```
For DOT:
```dot
graph G {
A -- B
}
```
For Markmap:
```markmap
# Root
## Branch 1
## Branch 2
```
Best Practices
Choose the Right Tool
- Mermaid: Best for standard diagrams (flowcharts, sequence, Gantt)
- Graphviz/DOT: Best for complex graphs and custom layouts
- Markmap: Best for hierarchical information and mind maps
Keep Diagrams Readable
- Limit nodes to avoid clutter
- Use meaningful labels
- Add colors to group related elements
- Include legends when necessary
Maintain Consistency
- Use the same diagram type for similar visualizations
- Follow naming conventions
- Document complex diagrams with comments
Version Control Tips
- Keep diagrams in separate code blocks
- Add descriptive comments
- Break complex diagrams into smaller ones
- Use meaningful commit messages when updating diagrams
Export Behavior
When you export your document from MD Editor:
- HTML Export: Diagrams are rendered as embedded PNG images with base64 encoding
- PDF Export: Diagrams appear as high-resolution images
- DOCX Export: Diagrams are included as inline images
- Markdown Export: Original diagram code is preserved for portability
All diagrams are automatically rendered during export, ensuring your documentation looks professional regardless of the output format.
Conclusion
With support for Mermaid, Graphviz, DOT, and Markmap, MD Editor gives you powerful tools to create any type of diagram you need for technical documentation. Whether you're documenting APIs, designing systems, or planning projects, these diagram types have you covered.
Start creating beautiful, version-controlled diagrams today with MD Editor!