diff --git a/docs/markdown.md b/docs/markdown.md
index 10fd962..c6fe934 100644
--- a/docs/markdown.md
+++ b/docs/markdown.md
@@ -79,6 +79,94 @@ go get github.com/yuin/goldmark github.com/yuin/goldmark-highlighting/v2 github.
 
 That's the entire markdown story for static-content sites.
 
+## Mermaid diagrams
+
+This example site renders fenced ` ```mermaid ` blocks as flowcharts
+and sequence diagrams using [mermaid.js](https://mermaid.js.org/). A
+small extension lives next to the renderer in
+[`md/mermaid.go`](https://github.com/andrioid/gastro/blob/main/examples/gastro/md/mermaid.go);
+the SSE doc has a [live example](/docs/sse#sse-from-page-the-headline)
+of the GET/POST page lifecycle as a flowchart.
+
+The pattern is small enough to copy verbatim and zero new Go
+dependencies are required — it composes the same `goldmark`,
+`goldmark/ast`, `goldmark/parser`, `goldmark/renderer`, `goldmark/text`
+and `goldmark/util` packages that goldmark-highlighting already pulls
+in. Two pieces wired together:
+
+1. **Parser-stage AST transformer.** Walks the parsed tree and replaces
+   every `*ast.FencedCodeBlock` whose info string is `mermaid` with a
+   custom `mermaidBlock` AST node. Running at the parser stage — not as
+   a higher-priority node renderer — means goldmark-highlighting's
+   chroma renderer never sees these nodes, so we don't have to fight
+   the highlighter's registry or re-implement code-block rendering.
+2. **Custom node renderer.** Emits the raw mermaid source (HTML-escaped)
+   inside `<pre class="mermaid">…</pre>`. mermaid.js' default scanner
+   picks up that selector and swaps the element for an SVG diagram on
+   first paint.
+
+Wire it into your goldmark instance alongside the highlighter:
+
+```go
+var renderer = goldmark.New(
+    goldmark.WithExtensions(
+        extension.GFM,
+        extension.Footnote,
+        highlighting.NewHighlighting(/* ... */),
+        md.NewMermaid(), // ```mermaid → <pre class="mermaid">
+    ),
+)
+```
+
+For the client side, lazy-load mermaid.js only when a diagram is
+actually present on the page. This keeps mermaid's ~600KB off every
+page that doesn't need it. Add this once near the bottom of your
+base layout:
+
+```html
+<script>
+    if (document.querySelector('pre.mermaid')) {
+        import('https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs')
+            .then(({ default: mermaid }) => {
+                mermaid.initialize({ startOnLoad: false, securityLevel: 'strict' });
+                mermaid.run({ querySelector: 'pre.mermaid' });
+            });
+    }
+</script>
+```
+
+Use it from any markdown file:
+
+````md
+```mermaid
+flowchart LR
+    A[.md file] -->|gastro:embed| B[raw string]
+    B -->|md.MustRender| C[template.HTML]
+    C --> D[rendered page]
+```
+````
+
+This renders to a flowchart on first paint, while sibling code blocks
+such as ` ```go ` continue to flow through chroma untouched.
+
+The same shape — *parser AST transformer + custom node kind +
+minimal node renderer* — generalises to other diagram or DSL
+extensions you might want (KaTeX math, GraphViz, custom admonitions).
+When one fits your project, copy `md/mermaid.go` and adjust the
+language string and rendered wrapper.
+
+### Trust boundary
+
+Everything inside ` ```mermaid ` ends up as text that mermaid.js
+parses in the browser. The renderer HTML-escapes the source so any
+stray `<script>` in the diagram's labels can't break out and execute,
+and the loader configures `securityLevel: 'strict'` so mermaid itself
+strips dangerous markup from labels before rendering. If you accept
+user-submitted markdown that may contain diagrams, that escape +
+strict combo is the floor; consider also rendering server-side with
+[mermaid-cli](https://github.com/mermaid-js/mermaid-cli) if you want
+to avoid running mermaid in untrusted browsers altogether.
+
 ## Static markdown — the canonical case
 
 Most sites have markdown files committed to the repo: documentation
diff --git a/docs/sse.md b/docs/sse.md
index 625aee1..571a0bb 100644
--- a/docs/sse.md
+++ b/docs/sse.md
@@ -58,6 +58,17 @@ Count := int(state.Count.Load())
 
 What happens at runtime:
 
+```mermaid
+flowchart TD
+    R[Incoming request] --> M{r.Method}
+    M -->|GET| G[Frontmatter computes<br/>Title, Count]
+    G --> GT[Template renders<br/>full page]
+    M -->|POST| P[Frontmatter mutates state<br/>via state.Count.Add 1]
+    P --> PR[gastro.Render.Counter<br/>→ template.HTML]
+    PR --> PS[datastar.NewSSE<br/>+ PatchElements]
+    PS --> PX[return — body-written flag set<br/>template render skipped]
+```
+
 - **`GET /counter`** — `r.Method == "POST"` is false; the if-block is
   skipped. `Title` and `Count` are computed. The codegen-wrapped
   writer's body-written flag is still false, so the template renders.
diff --git a/examples/gastro/components/layout.gastro b/examples/gastro/components/layout.gastro
index fcea0f6..781aac6 100644
--- a/examples/gastro/components/layout.gastro
+++ b/examples/gastro/components/layout.gastro
@@ -41,6 +41,19 @@ Title := p.Title
         </div>
     </header>
     {{ .Children }}
+    <script>
+        // Lazy-load mermaid.js only when the page actually contains a
+        // diagram. Pages without ```mermaid blocks pay zero bytes for
+        // mermaid (the library is ~600KB gzipped).
+        if (document.querySelector('pre.mermaid')) {
+            import('https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs')
+                .then(({ default: mermaid }) => {
+                    mermaid.initialize({ startOnLoad: false, theme: 'default', securityLevel: 'strict' });
+                    mermaid.run({ querySelector: 'pre.mermaid' });
+                })
+                .catch((err) => console.error('mermaid load failed', err));
+        }
+    </script>
     <footer class="site-footer">
         <div class="footer-container">
             <p>Built with Gastro &mdash; a file-based component framework for Go.</p>
diff --git a/examples/gastro/md/md.go b/examples/gastro/md/md.go
index a43bf0f..b56f720 100644
--- a/examples/gastro/md/md.go
+++ b/examples/gastro/md/md.go
@@ -15,10 +15,14 @@ import (
 	highlighting "github.com/yuin/goldmark-highlighting/v2"
 )
 
-// renderer is created once at package init. goldmark renderers are safe
-// for concurrent use across goroutines once configured, so a single
-// shared instance is fine for a static-content site.
-var renderer = goldmark.New(
+// mdRenderer is created once at package init. goldmark renderers are
+// safe for concurrent use across goroutines once configured, so a
+// single shared instance is fine for a static-content site.
+//
+// (Named `mdRenderer` rather than `renderer` to avoid shadowing the
+// `github.com/yuin/goldmark/renderer` import pulled in by the mermaid
+// extension in mermaid.go.)
+var mdRenderer = goldmark.New(
 	goldmark.WithExtensions(
 		extension.GFM,
 		extension.Footnote,
@@ -26,6 +30,10 @@ var renderer = goldmark.New(
 			highlighting.WithStyle("github"),
 			highlighting.WithFormatOptions(chromahtml.WithClasses(true)),
 		),
+		// Mermaid: ```mermaid fences become <pre class="mermaid">…</pre>
+		// and are rendered client-side by mermaid.js (loaded lazily in
+		// components/layout.gastro). See md/mermaid.go.
+		NewMermaid(),
 	),
 )
 
@@ -55,7 +63,7 @@ func MustRender(src string) template.HTML {
 // than panic.
 func Render(src string) (template.HTML, error) {
 	var buf bytes.Buffer
-	if err := renderer.Convert([]byte(src), &buf); err != nil {
+	if err := mdRenderer.Convert([]byte(src), &buf); err != nil {
 		return "", err
 	}
 	return template.HTML(buf.String()), nil
diff --git a/examples/gastro/md/md_test.go b/examples/gastro/md/md_test.go
index 0280d13..f263c13 100644
--- a/examples/gastro/md/md_test.go
+++ b/examples/gastro/md/md_test.go
@@ -55,6 +55,51 @@ func TestMustRender_Footnote(t *testing.T) {
 	}
 }
 
+func TestMustRender_MermaidPassthrough(t *testing.T) {
+	src := "```mermaid\nflowchart LR\n    A --> B\n```\n"
+	out := md.MustRender(src)
+	s := string(out)
+	if !strings.Contains(s, `<pre class="mermaid">`) {
+		t.Errorf("expected <pre class=\"mermaid\"> wrapper, got: %s", s)
+	}
+	if !strings.Contains(s, "flowchart LR") || !strings.Contains(s, "A --&gt; B") {
+		t.Errorf("expected mermaid source preserved (HTML-escaped), got: %s", s)
+	}
+	// Mermaid blocks must NOT be passed through chroma — no highlight
+	// classes should leak in.
+	if strings.Contains(s, "chroma") {
+		t.Errorf("mermaid block should not be syntax-highlighted by chroma, got: %s", s)
+	}
+}
+
+func TestMustRender_NonMermaidStillHighlighted(t *testing.T) {
+	// Non-mermaid fences must remain unaffected by the mermaid extension.
+	src := "```mermaid\nflowchart LR\n    A --> B\n```\n\n```go\nfunc main() {}\n```\n"
+	out := md.MustRender(src)
+	s := string(out)
+	if !strings.Contains(s, `<pre class="mermaid">`) {
+		t.Errorf("expected mermaid wrapper, got: %s", s)
+	}
+	if !strings.Contains(s, "chroma") {
+		t.Errorf("expected chroma class on adjacent Go block, got: %s", s)
+	}
+}
+
+func TestMustRender_MermaidEscapesHTML(t *testing.T) {
+	// Mermaid sources can include angle brackets in arrow syntax. The
+	// renderer must escape them so the SVG renderer (and the browser's
+	// HTML parser before it) sees the original characters.
+	src := "```mermaid\nA-->B & <script>alert(1)</script>\n```\n"
+	out := md.MustRender(src)
+	s := string(out)
+	if strings.Contains(s, "<script>alert(1)</script>") {
+		t.Errorf("raw <script> must not survive HTML escaping, got: %s", s)
+	}
+	if !strings.Contains(s, "&lt;script&gt;") {
+		t.Errorf("expected escaped script tag, got: %s", s)
+	}
+}
+
 func TestRender_ReturnsErrorRatherThanPanic(t *testing.T) {
 	// goldmark is famously hard to make fail; this is mostly a smoke
 	// test that the non-panic API path is wired.
diff --git a/examples/gastro/md/mermaid.go b/examples/gastro/md/mermaid.go
new file mode 100644
index 0000000..2d47c2d
--- /dev/null
+++ b/examples/gastro/md/mermaid.go
@@ -0,0 +1,128 @@
+package md
+
+// Mermaid extension for goldmark. Replaces fenced code blocks tagged
+// `mermaid` with a custom AST node that renders to
+// `<pre class="mermaid">…</pre>`. The browser-side mermaid.js loader
+// (see components/layout.gastro) finds those elements and swaps in
+// SVG diagrams on first paint.
+//
+// Why an AST transformer rather than a higher-priority FencedCodeBlock
+// renderer? goldmark-highlighting registers its own renderer for
+// FencedCodeBlock, and goldmark's renderer registry is last-write-wins
+// per kind. Overriding by priority works, but then *every* code block
+// has to either be re-implemented in our renderer or routed back to
+// chroma — awkward. Replacing only the mermaid nodes with a distinct
+// AST kind leaves chroma's renderer alone and keeps the two concerns
+// independent.
+//
+// No new Go dependencies: this uses only the goldmark APIs already
+// pulled in for syntax highlighting.
+
+import (
+	"github.com/yuin/goldmark"
+	"github.com/yuin/goldmark/ast"
+	"github.com/yuin/goldmark/parser"
+	"github.com/yuin/goldmark/renderer"
+	"github.com/yuin/goldmark/text"
+	"github.com/yuin/goldmark/util"
+)
+
+// kindMermaid is the AST node kind used for mermaid blocks.
+var kindMermaid = ast.NewNodeKind("MermaidBlock")
+
+// mermaidBlock is a leaf block holding the raw mermaid source (the
+// fenced block's content lines, verbatim). Rendering is trivial: emit
+// the content inside `<pre class="mermaid">` so mermaid.js can find
+// it and render an SVG client-side.
+type mermaidBlock struct {
+	ast.BaseBlock
+}
+
+func (n *mermaidBlock) Kind() ast.NodeKind { return kindMermaid }
+
+func (n *mermaidBlock) Dump(source []byte, level int) {
+	ast.DumpHelper(n, source, level, nil, nil)
+}
+
+// mermaidTransformer walks the parsed AST and rewrites every
+// `FencedCodeBlock` whose info string starts with "mermaid" into a
+// mermaidBlock. Running as a parser-stage transformer (rather than at
+// render time) means downstream renderers — including the chroma
+// highlighter — never see these nodes at all.
+type mermaidTransformer struct{}
+
+func (t *mermaidTransformer) Transform(doc *ast.Document, reader text.Reader, _ parser.Context) {
+	source := reader.Source()
+
+	// Collect first, mutate after: replacing children mid-walk would
+	// invalidate the iteration.
+	var targets []*ast.FencedCodeBlock
+	_ = ast.Walk(doc, func(n ast.Node, entering bool) (ast.WalkStatus, error) {
+		if !entering {
+			return ast.WalkContinue, nil
+		}
+		cb, ok := n.(*ast.FencedCodeBlock)
+		if !ok {
+			return ast.WalkContinue, nil
+		}
+		if string(cb.Language(source)) != "mermaid" {
+			return ast.WalkContinue, nil
+		}
+		targets = append(targets, cb)
+		return ast.WalkSkipChildren, nil
+	})
+
+	for _, cb := range targets {
+		mb := &mermaidBlock{}
+		mb.SetLines(cb.Lines())
+		parent := cb.Parent()
+		if parent == nil {
+			continue
+		}
+		parent.ReplaceChild(parent, cb, mb)
+	}
+}
+
+// mermaidNodeRenderer renders mermaidBlock to HTML. The output is the
+// raw mermaid source (HTML-escaped for safety) wrapped in a
+// `<pre class="mermaid">` element. mermaid.js' default scanner picks
+// up that selector and replaces the element with an SVG.
+type mermaidNodeRenderer struct{}
+
+func (r *mermaidNodeRenderer) RegisterFuncs(reg renderer.NodeRendererFuncRegisterer) {
+	reg.Register(kindMermaid, r.render)
+}
+
+func (r *mermaidNodeRenderer) render(w util.BufWriter, source []byte, n ast.Node, entering bool) (ast.WalkStatus, error) {
+	if !entering {
+		return ast.WalkContinue, nil
+	}
+	_, _ = w.WriteString(`<pre class="mermaid">`)
+	lines := n.Lines()
+	for i := 0; i < lines.Len(); i++ {
+		seg := lines.At(i)
+		_, _ = w.Write(util.EscapeHTML(seg.Value(source)))
+	}
+	_, _ = w.WriteString("</pre>\n")
+	return ast.WalkSkipChildren, nil
+}
+
+// mermaidExt wires the transformer and the renderer into a goldmark
+// instance. It implements goldmark.Extender so it can be passed via
+// `goldmark.WithExtensions(...)`.
+type mermaidExt struct{}
+
+// NewMermaid returns a goldmark extension that renders fenced
+// ```mermaid blocks as `<pre class="mermaid">` elements. Pair with a
+// client-side mermaid.js loader (see components/layout.gastro for the
+// lazy loader used by this example site).
+func NewMermaid() goldmark.Extender { return &mermaidExt{} }
+
+func (e *mermaidExt) Extend(m goldmark.Markdown) {
+	m.Parser().AddOptions(parser.WithASTTransformers(
+		util.Prioritized(&mermaidTransformer{}, 0),
+	))
+	m.Renderer().AddOptions(renderer.WithNodeRenderers(
+		util.Prioritized(&mermaidNodeRenderer{}, 0),
+	))
+}