Astro Starlight Mermaid Diagrams Tutorial

What You Are Learning

Mermaid is a text-based diagram tool. You write diagram code, and Mermaid renders it as a visual diagram.

• How Mermaid fits into Astro/Starlight documentation.
• Safe diagram syntax for Markdown and MDX.
• Flowcharts, timelines, sequence diagrams, and relationship diagrams.
• Common syntax problems and how to avoid them.

Why Use Mermaid?

Mermaid is useful when you want diagrams that are easy to edit as text.

Text diagram source
  ↓
Mermaid renderer
  ↓
Visual flowchart, timeline, or relationship map

For tutorial sites, Mermaid can explain workflows. For world bible sites, Mermaid can show factions, relationships, timelines, and political structures.

Basic Setup Option

A simple way to support Mermaid is to load Mermaid on pages where you need diagrams.

<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
  mermaid.initialize({ startOnLoad: true });
</script>

Then use a Mermaid block:

<div class="mermaid">
graph TD
  A[Start] --> B[Write Markdown]
  B --> C[Build Site]
  C --> D[Deploy]
</div>

For a production Starlight site, consider moving the setup into a reusable component or layout.

Basic Flowchart

Use graph TD for a vertical top-down chart.

<div class="mermaid">
graph TD
  A[Create Astro Project] --> B[Add Starlight]
  B --> C[Write Docs]
  C --> D[Build]
  D --> E[Deploy]
</div>

Use graph LR for a left-to-right chart.

<div class="mermaid">
graph LR
  A[Markdown] --> B[Astro]
  B --> C[Static HTML]
</div>

Vertical vs Horizontal

Safe Node Text

Mermaid can break when node text contains complex HTML, quotes, or special characters. Keep node text simple.

Safer:
A[Check dependency array]

Riskier:
A[Check "dependency array" with <br/> HTML]

If a diagram fails, simplify the text first. Then add details back slowly.

Decision Flowchart

<div class="mermaid">
graph TD
  A[Need a page?] --> B{Mostly writing?}
  B -->|Yes| C[Use Markdown]
  B -->|No| D{Needs components?}
  D -->|Yes| E[Use MDX]
  D -->|No| F[Use Astro page]
</div>

Worldbuilding Relationship Diagram

<div class="mermaid">
graph TD
  A[House Valoire] --> B[Aurelian Valoire VI]
  A --> C[Aurelian Rassendyll]
  D[House Miraculo] --> E[Veritas Miraculo]
  E --> F[Political Rivalry]
  C --> F
</div>

Lesson Workflow Diagram

<div class="mermaid">
graph TD
  A[Read Lesson] --> B[Follow Example]
  B --> C[Try Exercise]
  C --> D{Did it work?}
  D -->|Yes| E[Move to Next Lesson]
  D -->|No| F[Check Troubleshooting]
  F --> C
</div>

Timeline Diagram

Timeline diagrams can be useful, but keep entries short.

<div class="mermaid">
timeline
  title Project Timeline
  Week 1 : Create Astro project
  Week 2 : Add Starlight pages
  Week 3 : Add components
  Week 4 : Deploy site
</div>

Sequence Diagram

<div class="mermaid">
sequenceDiagram
  participant User
  participant Browser
  participant Vercel
  User->>Browser: Visit site
  Browser->>Vercel: Request page
  Vercel-->>Browser: Send static HTML
  Browser-->>User: Show page
</div>

Adding Styling

Mermaid style lines can work, but they are a common source of syntax mistakes. Start with an unstyled diagram first.

<div class="mermaid">
graph TD
  A[Start] --> B[Build]
  B --> C[Deploy]
  style A fill:#e8f0ff,stroke:#333
  style C fill:#e8ffe8,stroke:#333
</div>

Common Mermaid Mistakes

HTML inside node labels

Risky:
A[Line one<br/>Line two]

Safer:
A[Line one and line two]

Quotes inside labels

Risky:
A[path="/about"]

Safer:
A[path /about]

Too much text in one node

Risky:
A[This is a very long explanation that should probably be normal paragraph text instead]

Safer:
A[Short label]

Mermaid in Markdown vs MDX

In Markdown, simple HTML blocks are usually enough:

<div class="mermaid">
graph TD
  A[Start] --> B[End]
</div>

In MDX, be more careful because MDX parses JSX-like syntax. If raw HTML causes issues, use a reusable component.

Good Diagram Design

• Keep labels short.
• Use paragraphs below diagrams for details.
• Prefer simple flowcharts before complex diagram types.
• Use vertical diagrams for lessons and decisions.
• Use horizontal diagrams for pipelines.
• Test diagrams one at a time.

Troubleshooting Checklist

[ ] Does a very simple Mermaid diagram render?
[ ] Is the Mermaid script loading?
[ ] Are node labels short?
[ ] Did you remove risky quotes?
[ ] Did you remove HTML tags from labels?
[ ] Did you test without style lines?
[ ] Are you using graph TD or graph LR correctly?
[ ] Does the diagram work outside MDX first?

Simple Rule of Thumb

Start with plain Mermaid.
Keep labels simple.
Avoid quotes and HTML in nodes.
Use graph TD for step-by-step lessons.
Use graph LR for process pipelines.
Add styling only after the diagram works.