---
title: Draw diagrams from text
description: Turn Mermaid sequence, class, state and flowchart diagrams in markdown into SVG drawn on the server, with broken diagrams caught at build time.
section:
title: Content & feeds
order: 7
order: 31
lastUpdated: 2026-10-08
---
A diagram written as text lives beside the prose it explains: it diffs, it reviews, and it
changes in the same commit as the code it describes. This guide draws those diagrams as SVG
on the server, wherever one appears: in a markdown post, in a string you render for a feed,
and directly in a `remix/component` view. It uses [`@sdxc/diagram`](/api/diagram) together
with [`@sdxc/markdown`](/api/markdown).
```bash
npm add @sdxc/diagram @sdxc/markdown @sdxc/result remix
```
The page carries finished SVG: no script runs to draw it, and no stylesheet or font loads for
it. Lines and text take the color of the text around them, so a diagram follows the page into
dark mode.
## Write a diagram
Diagrams use [Mermaid](https://mermaid.js.org)'s syntax, the one GitHub renders, so the same
file shows the same picture on GitHub and on your site. The first line names the kind:
`sequenceDiagram`, `classDiagram`, `stateDiagram-v2` or `flowchart` with a direction.
Write it inside a fenced block marked `mermaid`:
```text
sequenceDiagram
actor Reader
participant Worker
participant Cache
Reader->>+Worker: GET /posts/hello
Worker->>Cache: match(request)
alt cached
Cache-->>Worker: response
else missing
Worker->>Worker: render the post
Worker-)Cache: put(request, response)
end
Worker-->>-Reader: 200 OK
```
That source draws this:
```mermaid
sequenceDiagram
actor Reader
participant Worker
participant Cache
Reader->>+Worker: GET /posts/hello
Worker->>Cache: match(request)
alt cached
Cache-->>Worker: response
else missing
Worker->>Worker: render the post
Worker-)Cache: put(request, response)
end
Worker-->>-Reader: 200 OK
```
Class and state diagrams read the same way. A class diagram puts each parent and each whole
above the classes that point at it, whichever way round the relation is written:
```mermaid
classDiagram
class Post {
+String slug
+String title
+publish() void
}
class Draft
class Comment {
+String body
}
Post <|-- Draft
Post "1" *-- "many" Comment : collects
```
A state diagram nests composite states, each with its own start:
```mermaid
stateDiagram-v2
[*] --> Draft
Draft --> Review : submit
Review --> Draft : request changes
Review --> Live : approve
state Live {
direction LR
[*] --> Listed
Listed --> Archived : archive
}
```
Labels break onto a new line at ` `. A `title` or `accTitle:` statement names the drawing
for screen readers, and `accDescr:` describes it; without one, the drawing is named after its
kind. The [package reference](/api/diagram) lists every statement each kind reads.
## Draw a diagram from a string
`toSVG` takes the source and answers with a `Result` holding the markup:
```typescript {% title="app/content/architecture.ts" %}
import { toSVG } from "@sdxc/diagram";
import { isFailure } from "@sdxc/result";
export function architecture(): string {
let result = toSVG("flowchart LR\n Browser --> Worker --> D1[(D1)]");
if (isFailure(result)) {
let { reason, line, column } = result.error;
return `${reason} at ${line}:${column}`;
}
return result.data; // '