# Mermaid Diagrams
Turn Mermaid code blocks into responsive, themed SVG diagrams at build time.
import { Callout, Steps, TabItem, Tabs } from '@prosefly/astro-components';
Write a fenced code block with the `mermaid` language and the shared
`proseflyComponents()` integration turns it into a static SVG. The same syntax
works in Markdown and MDX, requires no component import, and ships no Mermaid
runtime to the browser.
[Dahlia](https://astro-theme-dahlia.prosefly.dev/) and
[Lotus](https://astro-theme-lotus.prosefly.dev/) already register the shared
integration. Mermaid diagrams work automatically in those projects.
## Quick Start
Add `title="..."` after the language when the diagram needs a specific
accessible name. Without it, the renderer derives a name from the diagram
type.
```mermaid title="Publishing flow"
flowchart LR
Markdown --> Astro
Astro --> SVG
```
````markdown
```mermaid title="Publishing flow"
flowchart LR
Markdown --> Astro
Astro --> SVG
```
````
The transform runs during the Astro build. It replaces the code block with a
responsive `` containing inline SVG, so the result appears immediately
and continues to work when JavaScript is disabled.
## Supported Diagram Types
Rendering is powered by
[`beautiful-mermaid`](https://github.com/lukilabs/beautiful-mermaid) and supports
a focused subset of Mermaid:
| Diagram | Opening declaration | Good for |
| --- | --- | --- |
| Flowchart | `flowchart LR` or `graph TD` | Processes, decisions, and architecture |
| State | `stateDiagram-v2` | Lifecycles and transitions |
| Sequence | `sequenceDiagram` | Requests and interactions over time |
| Class | `classDiagram` | Types, members, and relationships |
| Entity relationship | `erDiagram` | Data models and cardinality |
| XY chart | `xychart-beta` | Bar, line, and combined charts |
### Flowchart
Flowcharts support top-down, left-right, bottom-top, and right-left directions,
along with labels and common node shapes.
```mermaid title="Content publishing decision"
flowchart TD
Draft[Write draft] --> Review{Approved?}
Review -->|Yes| Publish[Publish page]
Review -->|No| Draft
```
````markdown
```mermaid title="Content publishing decision"
flowchart TD
Draft[Write draft] --> Review{Approved?}
Review -->|Yes| Publish[Publish page]
Review -->|No| Draft
```
````
### State Diagram
Use state diagrams when the important information is how one state changes
into another.
```mermaid title="Article lifecycle"
stateDiagram-v2
[*] --> Draft
Draft --> Review: submit
Review --> Published: approve
Review --> Draft: request changes
Published --> [*]
```
````markdown
```mermaid title="Article lifecycle"
stateDiagram-v2
[*] --> Draft
Draft --> Review: submit
Review --> Published: approve
Review --> Draft: request changes
Published --> [*]
```
````
### Sequence Diagram
Sequence diagrams make request order and cache behavior visible without a
long procedural explanation.
```mermaid title="Cached metadata request"
sequenceDiagram
participant Page
participant Cache
participant Provider
Page->>Cache: Resolve URL
alt Cached
Cache-->>Page: Return metadata
else Missing
Cache->>Provider: Fetch metadata
Provider-->>Cache: Return response
Cache-->>Page: Return metadata
end
```
````markdown
```mermaid title="Cached metadata request"
sequenceDiagram
participant Page
participant Cache
participant Provider
Page->>Cache: Resolve URL
alt Cached
Cache-->>Page: Return metadata
else Missing
Cache->>Provider: Fetch metadata
Provider-->>Cache: Return response
Cache-->>Page: Return metadata
end
```
````
### Class Diagram
Class diagrams support members, methods, annotations, inheritance, composition,
aggregation, dependencies, and relationship labels.
```mermaid title="Markdown rendering classes"
classDiagram
class MarkdownPage {
+String title
+String body
+render() String
}
class Diagram {
+String source
+toSVG() String
}
MarkdownPage *-- Diagram
```
````markdown
```mermaid title="Markdown rendering classes"
classDiagram
class MarkdownPage {
+String title
+String body
+render() String
}
class Diagram {
+String source
+toSVG() String
}
MarkdownPage *-- Diagram
```
````
### Entity Relationship Diagram
Use an ER diagram to show entities and cardinality. Entity fields are optional
when the relationships are the main point.
```mermaid title="Documentation content model"
erDiagram
SITE ||--o{ PAGE : contains
PAGE ||--o{ DIAGRAM : renders
PAGE {
string slug
string title
}
DIAGRAM {
string type
string source
}
```
````markdown
```mermaid title="Documentation content model"
erDiagram
SITE ||--o{ PAGE : contains
PAGE ||--o{ DIAGRAM : renders
PAGE {
string slug
string title
}
DIAGRAM {
string type
string source
}
```
````
### XY Chart
XY charts accept bar and line series. The accent token supplies the primary
series color and the renderer derives additional series from it.
```mermaid title="Documentation traffic by month"
xychart-beta
title "Documentation traffic"
x-axis [Jan, Feb, Mar, Apr, May, Jun]
y-axis "Visits (K)" 0 --> 50
bar [18, 24, 29, 31, 38, 46]
line [16, 22, 27, 34, 40, 44]
```
````markdown
```mermaid title="Documentation traffic by month"
xychart-beta
title "Documentation traffic"
x-axis [Jan, Feb, Mar, Apr, May, Jun]
y-axis "Visits (K)" 0 --> 50
bar [18, 24, 29, 31, 38, 46]
line [16, 22, 27, 34, 40, 44]
```
````
Gantt charts, mindmaps, pie charts, user journeys, and C4 diagrams are not
currently supported. Unsupported syntax fails the build instead of silently
producing an empty or incomplete diagram.
## Authoring Rules
1. **Use the exact `mermaid` language.**
Other language names remain normal code blocks.
2. **Add a short, descriptive title.**
Write `title="Request lifecycle"` on the opening fence. It becomes the SVG
`` referenced by `aria-labelledby`; it is not a visible caption.
3. **Use supported Mermaid syntax.**
`beautiful-mermaid` intentionally implements the six diagram families listed
above, not the complete Mermaid grammar.
4. **Treat render failures as content errors.**
Invalid and unsupported diagrams stop the build. The error includes the
source file and code-block line so the diagram can be fixed at its origin.
</Steps>
## Theming
The generated SVG references the same CSS custom properties as the Astro
components. It updates with the site's light or dark theme without being
rendered again.
| Token | Diagram role |
| --- | --- |
| `--pf-background` | Diagram background and color calculations |
| `--pf-text` | Primary labels |
| `--pf-text-muted` | Secondary labels and annotations |
| `--pf-surface` | Node surfaces |
| `--pf-border-subtle` | Node and group borders |
| `--pf-border-muted` | Connectors |
| `--pf-accent` | Arrowheads and chart series |
| `--pf-font-sans` | Labels and headings |
| `--pf-font-mono` | Monospaced diagram text |
Every token has a built-in fallback. Standalone sites can override the tokens
in their layout; Prosefly themes already provide them.
## Standalone Astro Setup
Register the shared integration once. Mermaid rendering is enabled by default,
and the integration safely adds `mermaid` to the existing
`markdown.syntaxHighlight.excludeLangs` list.
```ts title="astro.config.ts"
import { defineConfig } from 'astro/config';
import proseflyComponents from '@prosefly/astro-components/integration';
export default defineConfig({
integrations: [proseflyComponents()],
});
```
To keep the other shared Markdown transforms but disable Mermaid rendering:
```ts title="astro.config.ts"
proseflyComponents({
markdown: { mermaid: false },
});
```
## Advanced Processor Setup
Use the public `rehypeMermaid` plugin when composing the Markdown processor
yourself. Manual setups must also exclude `mermaid` from syntax highlighting so
the plugin receives the original code block.
```ts title="astro.config.ts"
import { defineConfig } from 'astro/config';
import {
rehypeMermaid,
unified,
} from '@prosefly/astro-components/markdown';
export default defineConfig({
markdown: {
syntaxHighlight: {
type: 'shiki',
excludeLangs: ['math', 'mermaid'],
},
processor: unified({
rehypePlugins: [rehypeMermaid],
}),
},
});
```