Diagrams in Markdown

A diagram can remain text: easy to review in a diff, quick to revise, and rendered only where the reader needs the picture. Mermaid is the most broadly supported place to begin.

MarkIOY Team · August 11, 2026 · 12 min read

Start with a Mermaid code fence

A Mermaid diagram is a fenced code block labeled mermaid. The first line inside the block declares the diagram type. It is source code rather than an image, so it can be reviewed, searched, and changed alongside the document that explains it.

```mermaid
flowchart LR
  A[Draft] --> B[Review]
  B --> C[Publish]
```

Use LR for left-to-right reading and TD for top-down reading. Choose the direction that matches the surrounding layout; do not mix directions within one small diagram.

Diagram types and syntax

Flowchart: decisions and processes

```mermaid
flowchart TD
  A[Open document] --> B{Ready to publish?}
  B -- Yes --> C[Export]
  B -- No --> D[Keep editing]
  D --> B
```

Use square brackets for steps and curly braces for decisions. Keep each node to one idea. If a flowchart needs more than about ten nodes, split it by responsibility or level of detail.

Sequence diagram: messages over time

```mermaid
sequenceDiagram
  participant Writer
  participant Editor
  participant File
  Writer->>Editor: Edit Markdown
  Editor->>File: Save locally
  File-->>Editor: Updated content
  Editor-->>Writer: Render preview
```

Use ->> for a request and -->> for a response. Sequence diagrams explain the order of communication; they are not a replacement for an implementation specification.

Class diagram: concepts and relationships

```mermaid
classDiagram
  class Document {
    +String markdown
    +save()
  }
  class Workspace {
    +open(Document)
  }
  Workspace "1" o-- "many" Document
```

State diagram: lifecycle and transitions

```mermaid
stateDiagram-v2
  [*] --> Draft
  Draft --> Review: submit
  Review --> Draft: revise
  Review --> Published: approve
  Published --> [*]
```

Entity relationship diagram: data shape

```mermaid
erDiagram
  WORKSPACE ||--o{ DOCUMENT : contains
  DOCUMENT ||--o{ REVISION : has
  WORKSPACE {
    string name
  }
  DOCUMENT {
    string title
    string markdown
  }
```

Planning and summary diagrams

```mermaid
gantt
  title Release plan
  dateFormat  YYYY-MM-DD
  section Writing
  Draft     :done, 2026-08-01, 3d
  Review    :active, 2026-08-04, 2d
  Publish   :milestone, 2026-08-06, 0d
```

A larger example: document flow

For an architecture view, group related nodes with subgraph. The labels explain intent; arrows explain the direction of data or control. This is more useful than a decorative diagram with every internal detail.

```mermaid
flowchart LR
  Writer[Writer] --> Web[MarkIOY Web]
  subgraph Browser
    Web --> Source[Markdown source]
    Source --> Preview[Rendered preview]
  end
  Source --> Download[Local .md file]
  Download --> Git[Git or another editor]
```

Start with this conceptual level. Add a second diagram for technical dependencies only when a different reader needs it. One diagram should answer one question.

Compatibility and best practices

Check support in the final destination

Mermaid support varies by product and version. MarkIOY, many documentation tools, and many static-site setups render it; plain Markdown viewers may show only the source block. Preview in the actual destination and provide a short textual explanation so the document still works without rendering.

Prefer stable, plain syntax

Use simple node IDs such as Editor and put human-facing text inside brackets. Quote labels with punctuation when the parser needs it. Avoid relying on themes, custom CSS, or the newest syntax unless every target renderer is known to support it.

Keep source readable

Indent consistently, one relationship per line, and use meaningful IDs. Diagram source goes through code review and AI retrieval too; a readable source is easier to correct than a dense block of arrows.

Choose another format only for a clear reason

PlantUML is useful where a team already has a PlantUML renderer; Graphviz DOT is strong for graph layout; SVG or a linked image may be better for a hand-crafted illustration. These are not core Markdown features. Put them in a labeled fence or link to the generated asset, then document the tool needed to render them.

Make the diagram accessible

Introduce the diagram with its conclusion, not just its title. Do not distinguish states by color alone, and repeat important relations in nearby text. A diagram should clarify the prose, never carry the only copy of a decision.