Dynamic Architecture Diagrams

Static images of architecture flows get outdated the moment you push a code change. To keep our documentation living and breathing, this site utilizes Mermaid.js integrated directly through astro-mermaid.

Instead of opening a design tool like Figma or Visio, our diagrams are written as pure text, version-controlled in Git, and compiled into responsive SVGs at build time.

How to Write a Mermaid Diagram

To render a flowchart, wrap your syntax inside a standard Markdown code block and label the language as mermaid.

Define the Direction: Start your block by declaring the layout flow (e.g., graph TD for Top-to-Down, or graph LR for Left-to-Right).
Declare Your Nodes: Give each node a unique letter identifier and wrap its display text in the appropriate shape brackets:
- A[Square Box] for standard components.
- B(Rounded Pill) for entry/exit points.
- C{Diamond} for conditional decision gates.
Connect the Flow: Use arrows (-->) and optional text pipes (-->|action|) to map out the system logic.

Behind the Curtain

How the compiled SVG flowchart renders on the live documentation page.

graph TD;
    A[Local VS Code] -->|git push| C(GitHub Repository);
    B[Sveltia CMS] -->|Direct Commit| C;
    C -->|Webhook Trigger| D{Render CI/CD};
    D -- Invalid Frontmatter --> E[Build Fails Safely];
    D -- Passes Zod Schema --> F[Deploy to Live Site];

The raw markdown and mermaid syntax used in the source file.

```mermaid
graph TD;
    A[Local VS Code] -->|git push| C(GitHub Repository);
    B[Sveltia CMS] -->|Direct Commit| C;
    C -->|Webhook Trigger| D{Render CI/CD};
    D -- Invalid Frontmatter --> E[Build Fails Safely];
    D -- Passes Zod Schema --> F[Deploy to Live Site];
```

How content editors interact with Mermaid syntax inside Sveltia.

In your Sveltia CMS markdown editor, authors simply write standard fenced code blocks tagged with mermaid. Because astro-mermaid handles the asset parsing at build time, no custom form widgets or complex UI shortcodes are required.