Render Mermaid diagrams at build time for blog posts

Add a remark-based Mermaid renderer that converts MDX mermaid fences into static light/dark SVG, document the workflow, and draft a new homelab post that uses the format. Also tighten package-manager guidance around the new pnpm-based dependency additions.

Constraint: The blog is a static Astro site and should not ship Mermaid runtime code to browsers
Rejected: Client-side Mermaid runtime injection | adds JS weight and delays diagram rendering until after hydration
Confidence: high
Scope-risk: moderate
Directive: Keep Mermaid rendering build-time only with strict security settings; do not introduce browser-side Mermaid unless the static approach is demonstrably insufficient
Tested: pnpm install --frozen-lockfile
Tested: pnpm exec astro check
Tested: pnpm build
Not-tested: Published rendering of the new homelab post because frontmatter keeps publish=false

Author: Clickin

AGENTS.md

@@ -5,11 +5,20 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Commands
 
 ```bash
+pnpm install      # Install dependencies and update pnpm-lock.yaml
 pnpm dev          # Start dev server at http://localhost:4321
 pnpm build        # prebuild (copy assets) → astro build → pagefind index
 pnpm preview      # Preview production build locally
 ```
 
+## Package manager
+
+This repository uses `pnpm` only.
+
+- Use `pnpm install`, `pnpm add`, `pnpm remove`, and related `pnpm` commands for dependency changes.
+- Commit `pnpm-lock.yaml` whenever dependencies change.
+- Do not run `bun install` in this repo or commit `bun.lock`; GitHub Actions installs with `pnpm install --frozen-lockfile`.
+
 **Search requires a prior build.** In dev mode, `/pagefind/` requests are proxied to `dist/` by a custom Vite middleware — run `pnpm build` at least once before testing search in dev.
 
 ## Architecture

CLAUDE.md

@@ -1 +1,5 @@
 @AGENTS.md
+
+## Package manager
+
+This repository uses `pnpm` only. Use `pnpm install`, `pnpm add`, and `pnpm remove`, keep `pnpm-lock.yaml` in sync with dependency changes, and do not create or commit `bun.lock`.

README.md

@@ -28,6 +28,14 @@ pnpm dev
 
 Open [http://localhost:4321](http://localhost:4321).
 
+## Package Manager
+
+This repository uses `pnpm` only.
+
+- Use `pnpm install`, `pnpm add`, `pnpm remove`, and other `pnpm` commands for dependency changes.
+- Commit `pnpm-lock.yaml` whenever dependencies change.
+- Do not run `bun install` in this repo or commit `bun.lock`; deployment uses `pnpm install --frozen-lockfile`.
+
 ## Deploy to GitHub Pages
 
 1. Push to `main` branch
@@ -53,6 +61,20 @@ src/content/posts/YYYY-MM-DD-slug/
 └── image.png    # Co-located assets (optional)
 ```
 
+## Mermaid Diagram
+
+Mermaid diagrams are rendered to static SVG during the build. Use a normal fenced code block with the `mermaid` language tag.
+
+````mdx
+```mermaid
+flowchart TD
+  A[Write Mermaid code in MDX] --> B[Astro build renders SVG]
+  B --> C[No Mermaid runtime shipped to the browser]
+```
+````
+
+The site renders light and dark SVG variants at build time and toggles them with CSS, so no Mermaid client bundle is needed.
+
 ## License
 
 MIT

astro.config.mjs

@@ -3,6 +3,7 @@ import sitemap from "@astrojs/sitemap";
 import tailwindcss from "@tailwindcss/vite";
 import { transformerNotationDiff, transformerNotationHighlight } from "@shikijs/transformers";
 import { defineConfig } from "astro/config";
+import remarkRenderMermaid from "./scripts/remark-render-mermaid.mjs";
 import remarkRewritePostAssets from "./scripts/remark-rewrite-post-assets.mjs";
 
 function ghPagesConfig() {
@@ -18,7 +19,7 @@ function ghPagesConfig() {
 export default defineConfig({
   site: "https://clickin.github.io",
   integrations: [
-    mdx({ remarkPlugins: [remarkRewritePostAssets] }),
+    mdx({ remarkPlugins: [remarkRenderMermaid, remarkRewritePostAssets] }),
     sitemap({
       filter: (page) => !page.includes("/blog/tag/"),
     }),

docs/plans/2026-03-09-mermaid-design.md

@@ -0,0 +1,27 @@
+# Mermaid Introduction Design
+
+## Goal
+
+Add Mermaid support to MDX posts without shipping Mermaid runtime code to the browser.
+
+## Chosen Approach
+
+Use a remark-based build renderer that converts ` ```mermaid ` code fences into static SVG during the Astro build via `@mermaid-js/mermaid-cli`.
+
+## Why This Approach
+
+- The final HTML contains only SVG, which matches the blog's static-build and SEO goals.
+- No Mermaid runtime bundle is shipped to the browser.
+- Theme switching can be handled with pre-rendered light/dark SVG variants and CSS only.
+
+## Safety Constraints
+
+- Keep Mermaid on `securityLevel: "strict"`.
+- Render diagrams only at build time.
+- Avoid client-side HTML reparsing entirely.
+
+## Verification
+
+- `pnpm install --frozen-lockfile` must succeed after the dependency and lockfile are updated.
+- `pnpm build` must succeed.
+- A `mermaid` code fence must be replaced with static SVG during build.

package.json

@@ -26,7 +26,9 @@
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.6",
+    "@mermaid-js/mermaid-cli": "^11.12.0",
     "pagefind": "1.5.0-beta.1",
+    "puppeteer": "^23.11.1",
     "sharp": "^0.34.5",
     "typescript": "^5.9.3"
   }