1.2 Installing and Using Mermaid
Using Mermaid in Markdown editors (VS Code, Obsidian, GitBook).
How to test syntax in online editors like Mermaid Live Editor.
Overview of integrations (GitHub, GitLab, Notion).
1. Using Mermaid in Markdown Editors (VS Code, Obsidian, GitBook)
One of the biggest advantages of Mermaid is how easily it integrates with popular Markdown editors and documentation tools. Whether you’re writing code, taking notes, or creating team documentation, you can add diagrams directly where you write — no extra design software needed.
Here’s how it works in some of the most popular tools:
✅ VS Code
Visual Studio Code (VS Code) is one of the most widely used code editors for developers — and it works beautifully with Mermaid.
Write Mermaid directly in your Markdown files using fenced code blocks:
```mermaid graph TD A --> B B --> C ```To preview your diagrams, you can install an extension like Markdown Preview Mermaid Support or Markdown Preview Enhanced. These extensions render your Mermaid diagrams in the built-in Markdown preview pane, right alongside the rest of your document.
When you push your Markdown files to GitHub or GitBook, the diagrams render automatically, so you don’t have to export images separately.
✅ Obsidian
Obsidian is a popular Markdown-based note-taking app, often used for personal knowledge bases and technical documentation.
Mermaid is built right into Obsidian — no plugins required. Simply add a
```mermaidcode block inside your note.Obsidian’s preview mode will automatically render your diagram. You can edit the text and see your changes live.
Many users love Obsidian for creating flowcharts, mind maps, and process diagrams right inside their connected notes — all version-controlled in plain text.
✅ GitBook
GitBook is a modern documentation platform for teams, perfect for sharing project docs, API references, and handbooks.
GitBook has native support for Mermaid diagrams. You don’t need to install anything extra.
Just create a new block by typing
/and choosing Mermaid diagram, or insert a fenced```mermaidblock directly in Markdown.When you publish your GitBook, all Mermaid diagrams are automatically rendered for your readers, ensuring your visuals are always up to date with your text.
✅ Why This Matters
This seamless integration means you can focus on writing — your diagrams live right next to your content. No switching apps, no exporting files, no worries about image versions — just edit, save, and your visuals update automatically wherever your Markdown lives.
In short: Mermaid makes it easy to bring clear, consistent diagrams into VS Code, Obsidian, and GitBook, helping you write better documentation that’s always in sync with your ideas.
2. How to Test Syntax in Online Editors like Mermaid Live Editor
When you’re learning Mermaid or experimenting with new diagrams, it helps to test your syntax quickly — without setting up a project or installing any tools. The easiest way to do this is by using the Mermaid Live Editor, a free online playground built by the Mermaid community.
✅ What is the Mermaid Live Editor?
The Mermaid Live Editor is an online tool where you can:
Write your Mermaid code in the left-hand panel.
Instantly see the rendered diagram in the right-hand panel.
Spot syntax errors immediately and adjust your diagram in real time.
Export your diagram as an image (PNG or SVG) or copy the diagram code to reuse elsewhere.
You can access it at 👉 mermaid.live
✅ Why Use It?
The Live Editor is perfect for:
Learning: If you’re new to Mermaid, you can experiment with different diagram types and syntax in a safe sandbox.
Prototyping: Before adding a diagram to your GitBook, README, or wiki, you can check that the syntax is valid and the diagram looks right.
Troubleshooting: If your diagram isn’t rendering as expected, you can test pieces of code to isolate errors.
Sharing: You can generate a shareable link to your diagram, so teammates can view or edit it online.
✅ How to Use It
1️⃣ Open mermaid.live in your browser. 2️⃣ Delete the default code and paste your own Mermaid syntax:
3️⃣ The right panel will automatically refresh to show your diagram. 4️⃣ Edit the code, try different arrows or nodes, and see changes instantly. 5️⃣ When you’re done, click Export or copy the code into your Markdown file.
✅ Pro Tip
The Live Editor supports different themes, so you can see how your diagram will look in dark or light mode. It also has helpful features like auto-formatting and error highlighting to make writing clean syntax easier.
In short: The Mermaid Live Editor is your go-to sandbox for practicing, testing, and perfecting your diagrams — no installation required. Once you’re happy with your diagram, just copy the code into your Markdown file, and you’re ready to go!
3. Overview of Integrations (GitHub, GitLab, Notion)
One of the biggest strengths of Mermaid is how easily it integrates with popular tools you already use for writing, collaborating, and documenting. Instead of exporting static images, you can embed dynamic, always-up-to-date diagrams directly in your everyday workspaces. Here’s how Mermaid works with some of the most widely used platforms:
✅ GitHub
GitHub is the world’s leading platform for hosting code and open-source projects — and it supports Mermaid diagrams natively in many contexts.
In Markdown files (
.md), like your README, you can include a```mermaidcode block.GitHub renders Mermaid automatically in the web UI for issues, pull requests, and discussions (in supported contexts).
This makes it easy to document system architecture, workflows, or project processes alongside your code — keeping everything version-controlled in one place.
🔍 Example:
Last updated