Mermaid Diagrams in Markdown: The Complete Developer Guide
Here is a scenario every developer knows: you write a meticulous explanation of a complex system architecture. It is accurate, well-structured, and covers every edge case. A week later, a new engineer joins and asks you to walk them through the system on a call, because nobody reads the document.
The document failed not because of the writing. It failed because prose alone cannot make structure visible. A three-paragraph description of a state machine takes ten minutes to parse. The equivalent state diagram takes ten seconds.

Mermaid is the answer that stays inside your Markdown file. With over 85,000 GitHub stars and 1.2 million weekly npm downloads, it is the most widely adopted text-to-diagram tool in developer documentation. You write diagram definitions as plain text inside a fenced code block, and any Mermaid-compatible renderer, including AnySlate, turns that text into a clean, version-controlled diagram. This guide covers the syntax, the most useful diagram types, and how the workflow operates inside AnySlate specifically.

What Mermaid Is and Why It Exists
Mermaid was created by Knut Sveidqvist to solve what its documentation calls doc-rot, the inevitable gap between diagrams and reality when diagrams live in Figma,Lucidchart, or Visio while the documentation lives elsewhere. By the time a system changes, nobody remembers to update the diagram in the external tool. The diagram becomes a historical artefact rather than a current reference.

The solution is radical in its simplicity: make the diagram text. If a diagram is a fenced code block in a Markdown file, it gets committed to Git with the code it describes. It gets reviewed in pull requests. It gets different when something changes. Updating the system and updating the documentation diagram become the same action in the same file.

Mermaid is now natively supported on GitHub, GitLab, Notion, and Docusaurus, among others. In AnySlate, Mermaid diagrams render live in the preview panel as you write them, the same document where your prose lives, version-controlled, publishable, and readable by AI agents via MCP without any export or conversion step.

A diagram that lives outside the documentation always falls behind the system it describes. A diagram that lives inside the Markdown file stays current because updating the documentation and updating the diagram are the same edit.

The Syntax Pattern: One Rule Covers All Diagram Types
Every Mermaid diagram follows the same syntax: open a fenced code block with the Mermaid identifier, declare the diagram type on the first line, write the definition, and close the block. That is the entire syntax model.

graph TD
A[Request received] --> B{Token valid?}

B -->|Yes| C[Process request]

B -->|No| D[Return 401 Unauthorised]

C --> E[Return 200 OK]

In AnySlate, that block renders live in the preview panel the moment you finish typing it. When you publish the document, the diagram is part of the published page, no separate export, no image file to maintain, no external tool required by the reader.

AnySlate + MCP: When your documents are connected via MCP, your AI agent can read the Mermaid block code directly from the .md file. It can generate new diagram blocks from a plain-English description, update an existing diagram when the architecture changes, or explain what a complex sequence diagram represents, all without leaving the editor or copy-pasting anything into a chat window.

Five Diagram Types That Cover Most Developer Documentation Needs
Mermaid supports over twenty diagram types. These five address the situations where diagrams add the most value in technical documentation:

Flowchart
graph TD or graph LR: Process flows, CI/CD pipelines, decision trees, error-handling logic. The default choice for anything sequential with conditional branches.

graph LR
A[Push to main] --> B[Run tests]

B -->|Pass| C[Build Docker image]

B -->|Fail| D[Notify Slack]

C --> E[Deploy to staging]

E --> F{Manual sign-off?}

F -->|Yes| G[Deploy to production]

F -->|No| H[Hold for review]

Sequence Diagram
sequenceDiagram — API interactions, authentication flows, microservice communication. Indispensable for documenting how components exchange messages over time.

sequenceDiagram
participant Client

participant API Gateway

Participant Auth Service

participant Database

Client->>API Gateway: POST /login {email, password}

API Gateway->>Auth Service: Validate credentials

Auth Service->>Database: SELECT user WHERE email

Database-->>Auth Service: User record

Auth Service-->>API Gateway: JWT token

API Gateway-->>Client: 200 OK {token}

Entity Relationship Diagram
erDiagram — Database schema and data model documentation. Faster to write than SQL DDL for documentation purposes and immediately readable by non-engineers.

erDiagram
USER ||--o{ ORDER : places

ORDER ||--|{ LINE_ITEM : contains

PRODUCT ||--o{ LINE_ITEM : references

USER {

   string id PK

   string email

   string name

}

State Diagram
stateDiagram-v2 — State machines, order lifecycle, UI component states, document approval workflows. The clearest way to document anything that transitions between defined states.

stateDiagram-v2
[*] --> Draft

Draft --> InReview : submit for review

InReview --> Approved : approve

InReview --> Draft : request changes

Approved --> Published : publish

Published --> Archived : archive

Archived --> [*]

Git Graph
gitGraph — Branch strategies, release workflows, contributing guides. Makes branching logic immediately visible in a way that commit history logs never achieve.

gitGraph
commit id: 'initial'

branch feature/auth-refactor

checkout feature/auth-refactor

commit id: 'extract AuthService'

commit id: 'add token refresh'

checkout main

merge feature/auth-refactor

commit id: 'v2.4.0' tag: 'v2.4.0'

Why the Editor You Write In Changes Everything
Most developers write Mermaid diagrams in one of three environments: GitHub’s web editor (no live preview while writing), the Mermaid Live Editor online (disconnected from the documentation), or VS Code with a plugin (variable rendering quality, no publishing path).

AnySlate unifies all three requirements in one environment: live preview while writing, the diagram lives inside the documentation file, and publishing the document produces a readable web page with diagrams rendered inline. The .md file containing your diagram is portable, it renders on GitHub, opens in any Mermaid-compatible tool, and is readable by AI agents via MCP without any export step.

Live preview as you type: Mermaid diagrams render in AnySlate’s preview panel in real time. Syntax errors surface immediately. No commit, no push, no reload required.

Version history on every diagram: because the diagram is code in a .md file, AnySlate’s automatic version history tracks every change. Roll back a diagram through the document’s revision timeline the same way you roll back prose.

Plain .md files with no lock-in: the Mermaid syntax in your AnySlate documents is standard. Open the same file in VS Code, push it to GitHub, and paste it into any Mermaid-compatible renderer. The diagram code is yours in a format that works everywhere.

Published pages render diagrams inline: publish a document from AnySlate, and Mermaid diagrams render as part of the page. Share the URL with a teammate or a client, no Mermaid installation required on their end.

The One Thing to Take Away
Technical documentation without diagrams forces every reader to build a mental model from scratch. Mermaid eliminates that cost by making the structure visible in the same file as the explanation, version-controlled, diffable, and always current because it changes when the surrounding prose changes.
In AnySlate, that workflow is complete: write the diagram in plain text, see it render live, publish the document, and share the URL. The diagram code lives in a portable .md file that your team, your Git repository, and your AI tools can