Tools, Ecosystem & Workflow

🔄 You can write Mermaid syntax (Lessons 2-5) and generate it with AI (Lesson 6). But where do these diagrams actually live? How do you integrate them into your daily workflow? This lesson covers the tools ecosystem and the workflows that make diagrams-as-code practical.

The Mermaid Live Editor

Your primary development tool: mermaid.live

Workflow: Write or paste your Mermaid code in the editor, debug until it renders correctly, then copy the code to its final home (README, docs, Obsidian note).

The editor also generates shareable links — useful for code reviews where you want to show a diagram change without requiring the reviewer to run anything locally.

GitHub: Native Rendering

Since February 2022, GitHub renders Mermaid natively. Wrap your code in a fenced block:

```mermaid
graph LR
    A[Frontend] --> B[API]
    B --> C[(Database)]
```

This renders automatically in:

• README.md files
• Issues and comments
• Pull request descriptions and reviews
• Wiki pages
• Markdown files anywhere in the repo

Best practice: Put architecture diagrams in docs/architecture.md or directly in the relevant README. When the architecture changes, update the diagram in the same pull request as the code change. Reviewers see both changes together.

✅ Quick Check: A developer updates the payment service but doesn’t update the architecture diagram. How does a diagrams-as-code workflow prevent this? (The diagram lives in the repo. During code review, the reviewer sees the code change but no diagram update and requests the change. If you include a CI check or a PR template reminder, it becomes systematic.)

VS Code

The Mermaid Chart extension for VS Code (official, by Mermaid Chart Inc.) provides:

• Syntax highlighting for .mmd and .mermaid files
• Live preview pane — see the diagram as you edit
• AI-powered diagram generation (with Mermaid Chart account)
• Export to SVG/PNG

Install from the VS Code marketplace: search “Mermaid Chart.” The basic syntax highlighting and preview work without an account.

Alternative: The community extension “Markdown Preview Mermaid Support” adds Mermaid rendering to VS Code’s built-in Markdown preview. Useful if you write Mermaid inside Markdown files rather than standalone .mmd files.

Obsidian

Obsidian supports Mermaid natively. Use a fenced code block:

```mermaid
stateDiagram-v2
    [*] --> Draft
    Draft --> Published : Publish
    Published --> Archived : Archive
```

The diagram renders in both reading view and live preview mode. For knowledge management workflows, Mermaid in Obsidian is powerful — link your notes to visual diagrams of the concepts they describe.

Tip: The Obsidian community has a “Mermaid View” plugin that lets you create standalone .mermaid files. Useful for large diagrams that you want to manage separately from your notes.

Notion

Notion renders Mermaid in code blocks. Create a code block, set the language to “Mermaid,” and paste your code. The rendering happens inline — no exports needed.

Limitations: Notion’s Mermaid support doesn’t include every diagram type (some newer types like architecture diagrams may not render). Test in the Live Editor first.

Other Integrations

The Documentation Workflow

Here’s a practical workflow that keeps diagrams current:

For a Project Repository

project/
├── docs/
│   ├── architecture.md      ← High-level system diagram
│   ├── api-flows.md          ← Sequence diagrams for key APIs
│   └── database-schema.md    ← ER diagram
├── src/
└── README.md                 ← Overview with simple flowchart

Rules:

1. Diagrams live in docs/ as Markdown with Mermaid code blocks
2. When code changes affect architecture, update the diagram in the same PR
3. PR template includes: “Does this change require a diagram update?”
4. Large changes get a before/after diagram in the PR description

For Personal Knowledge Management

obsidian-vault/
├── Projects/
│   ├── Project-A.md          ← Includes project flowchart
│   └── Project-B.md
├── Architecture/
│   ├── System-Overview.md    ← High-level Mermaid diagram
│   └── API-Flows.md          ← Sequence diagrams
└── Templates/
    └── Project-Template.md   ← Includes blank Mermaid template

✅ Quick Check: Your team uses Notion for documentation and GitHub for code. Where should the architecture diagram live? (Both — but the source of truth should be in GitHub (version-controlled, reviewed in PRs). Copy the rendered version to Notion for the team wiki. When the GitHub version updates, update Notion.)

Accessibility

Mermaid supports accessibility attributes:

graph TD
    accTitle: User Login Flow
    accDescr: Shows the steps from login form submission through authentication to dashboard display
    A[Login Form] --> B[Validate]
    B --> C[Dashboard]

accTitle adds an accessible title, accDescr adds a description. Screen readers use these. Always include them for diagrams in public documentation.

Key Takeaways

• The Mermaid Live Editor (mermaid.live) is your primary tool for writing and debugging diagrams
• GitHub, GitLab, Obsidian, and Notion all render Mermaid natively — just use fenced code blocks with the mermaid language identifier
• VS Code has official and community extensions for Mermaid editing with live preview
• Store diagrams as code in your repo alongside the code they describe — update both in the same PR
• Add accTitle and accDescr for accessibility in public documentation
• The source of truth for diagrams should be version-controlled; copy rendered versions to wikis as needed

Up Next

Final lesson. In the Capstone, you’ll document a complete project using multiple diagram types — architecture, API flows, database schema, and timeline. You’ll combine everything from the course into a real deliverable.