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. This reference explains the fence, type declaration, node, arrow, label, and relationship characters one by one.

MarkIOY Team · August 12, 2026 · 24 min read

Start with a Mermaid code fence

A Mermaid diagram is a fenced code block labeled mermaid. The three opening backticks say “start literal code,” the word mermaid selects the renderer, and the closing three backticks end the block. The first line inside declares the diagram type. Mermaid source is text 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]
```

Read the three important parts as flowchart LR: flowchart selects this grammar, one space separates it from the setting, and LR means left-to-right. TD means top-down; RL means right-to-left; BT means bottom-to-top. Choose one direction for one small diagram. Indentation is mainly for human readers, but use two spaces consistently so nested blocks are obvious.

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. IDs should be short ASCII-style names such as Review; labels can be friendly phrases. Keep each node to one idea. If a flowchart needs more than about ten nodes, split it by responsibility or level of detail. A node may be declared once and connected on later lines; repeated IDs refer to the same node.

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
```

A participant line creates a named lifeline. In Writer->>Editor: Edit Markdown, Writer is the sender, ->> is a solid request arrow, Editor is the receiver, the colon separates arrow from message text, and the rest is the message label. -->> makes a dashed response. Use --> or -> when you want an open arrowhead. Sequence diagrams show the order of communication; they are not an implementation specification by themselves.

Class diagram: concepts and relationships

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

Inside class Document { ... }, braces surround one class body. A leading + means public visibility; String markdown is an attribute and +save() is a method. In Workspace "1" o-- "many" Document, quoted text is cardinality, o-- is aggregation (a whole has parts), and the names on either side are classes. Start by naming concepts; do not try to reproduce every source-code member.

State diagram: lifecycle and transitions

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

[*] is Mermaid’s start or end marker. A line reads left to right: Draft --> Review: submit moves from Draft to Review; the colon introduces the event that causes the move. Use state diagrams for mutually exclusive lifecycle states, not for a loose collection of tasks.

Entity relationship diagram: data shape

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

ER entities are usually uppercase names. In WORKSPACE ||--o{ DOCUMENT : contains, the symbols next to each entity show cardinality: || means exactly one, o{ means zero or many, and the colon begins the relationship label. Attributes go in braces as type name. Model the relationship first; add only the attributes a reader needs to understand it.

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
```

In the Gantt task line Draft :done, 2026-08-01, 3d, the colon separates the visible task name from metadata; done is status, commas divide fields, the ISO date is the start, and 3d is three days. Keep the declared dateFormat consistent with every date. A milestone has no duration, so use 0d.

A larger example: document flow

For an architecture view, group related nodes with subgraph. The word starts a group, its following label names the boundary, indentation keeps the enclosed lines readable, and end closes it. 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. Do not use reserved-looking words such as end as an ID. Avoid relying on themes, custom CSS, click handlers, or the newest syntax unless every target renderer is known to support it.

Keep source readable

Indent consistently, write one relationship per line, and use meaningful IDs. Keep labels short and put the detailed explanation in prose beside the chart. Diagram source goes through code review and AI retrieval too; readable source is easier to correct than a dense block of arrows. When rendering fails, check in order: opening/closing backticks, the mermaid language label, the type declaration, matching brackets/braces, then arrow spelling.

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.