Mermaid Diagrams

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.

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

The transform runs during the Astro build. It replaces the code block with a responsive <figure> 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 and supports a focused subset of Mermaid:

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

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 --> [*]
```

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

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

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

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

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 <title> 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.

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.

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.

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:

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.

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],
    }),
  },
});