astro-better-mermaid 0.1.1

package/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright (c) 2026 Better Static Sites
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# astro-better-mermaid
+
+Astro integration that renders ` ```mermaid ` code blocks to inline SVG at build time. No client-side JavaScript is shipped to the browser.
+
+Rendering happens via [svgdom](https://github.com/svgdotjs/svgdom), a headless DOM shim that convinces mermaid it is running in a browser. It is not running in a browser.
+
+## Installation
+
+```
+npm install astro-better-mermaid mermaid svgdom
+```
+
+`mermaid` and `svgdom` are peer dependencies — install them alongside this package.
+
+## Usage
+
+```ts
+// astro.config.ts
+import { defineConfig } from 'astro/config';
+import mermaidSSR from 'astro-better-mermaid';
+
+export default defineConfig({
+  integrations: [mermaidSSR()],
+});
+```
+
+Mermaid code blocks in your Markdown and MDX files will be replaced with pre-rendered SVG wrapped in a `<div class="mermaid">` at build time. Blocks that fail to render are left as fenced code blocks.
+
+## Options
+
+```ts
+mermaidSSR({
+  theme: 'default',       // mermaid theme — 'default', 'dark', 'neutral', 'forest'
+  securityLevel: 'loose', // mermaid securityLevel
+  titleFix: true,         // parse title="..." from code block meta as a caption
+  injectCSS: true,        // inject the bundled stylesheet automatically
+})
+```
+
+### Diagram titles
+
+With `titleFix` enabled, you can add a caption to any code block via its meta string:
+
+````
+```mermaid title="Authentication flow"
+...
+```
+````
+
+Captions on mermaid blocks appear below the diagram; captions on other code blocks appear above.
+
+## Styles
+
+The integration injects a default stylesheet that covers light mode and dark mode. Dark mode is driven by a `.dark` class on an ancestor element (the Tailwind `darkMode: 'class'` convention).
+
+To use your own styles instead, set `injectCSS: false` and import the bundled CSS as a starting point:
+
+```css
+@import 'astro-better-mermaid/styles.css';
+```
+
+### Custom cluster fill colors
+
+Mermaid's `style X fill:#color` directive injects `!important` inline styles that block CSS overrides. This integration strips the `!important` from cluster background rects and stores the original color in a `data-fill-color` attribute. The default stylesheet handles `#999` and `#944`. For other colors, add rules of the form:
+
+```css
+.cluster > rect[data-fill-color="#abc"] { fill: your-color !important; }
+.dark .cluster > rect[data-fill-color="#abc"] { fill: your-dark-color !important; }
+```
+
+## Using the remark plugins directly
+
+If you prefer to wire up the remark plugins yourself:
+
+```ts
+import { remarkMermaidSSR, mermaidTitleFix } from 'astro-better-mermaid';
+
+export default defineConfig({
+  markdown: {
+    remarkPlugins: [
+      mermaidTitleFix,
+      [remarkMermaidSSR, { theme: 'default' }],
+    ],
+  },
+  vite: {
+    ssr: { external: ['svgdom', 'mermaid'] },
+  },
+});
+```
+
+`svgdom` and `mermaid` must be listed in `vite.ssr.external` — they are Node-only packages and cannot be bundled into client output.

package/index.mjs

@@ -0,0 +1,68 @@
+/**
+ * astro-mermaid-ssr
+ *
+ * Astro integration + remark plugins for server-side mermaid diagram rendering.
+ * No client-side JavaScript required — diagrams are pre-rendered to SVG at build time.
+ *
+ * Usage (astro.config.ts):
+ *
+ *   import mermaidSSR from 'astro-mermaid-ssr';
+ *   export default defineConfig({
+ *     integrations: [mermaidSSR()],
+ *   });
+ *
+ * Options:
+ *   titleFix     {boolean}  — Include the title="..." remark plugin (default: true)
+ *   injectCSS    {boolean}  — Auto-inject default styles (default: true)
+ *   theme        {string}   — Mermaid theme, e.g. 'default', 'dark', 'neutral' (default: 'default')
+ *   securityLevel {string}  — Mermaid securityLevel (default: 'loose')
+ *
+ * If injectCSS is false, import the styles yourself:
+ *   import 'astro-mermaid-ssr/styles.css';
+ *
+ * To use the remark plugins directly without the integration:
+ *   import { remarkMermaidSSR, mermaidTitleFix } from 'astro-mermaid-ssr';
+ */
+
+import { fileURLToPath } from 'node:url';
+import { remarkMermaidSSR, mermaidTitleFix } from './src/remark.mjs';
+
+export { remarkMermaidSSR, mermaidTitleFix };
+
+const STYLES_PATH = fileURLToPath(new URL('./src/styles.css', import.meta.url));
+
+export default function astroMermaidSSR(opts = {}) {
+  const {
+    titleFix = true,
+    injectCSS = true,
+    theme = 'default',
+    securityLevel = 'loose',
+  } = opts;
+
+  return {
+    name: 'astro-mermaid-ssr',
+    hooks: {
+      'astro:config:setup': ({ updateConfig, injectScript }) => {
+        updateConfig({
+          markdown: {
+            remarkPlugins: [
+              ...(titleFix ? [mermaidTitleFix] : []),
+              [remarkMermaidSSR, { theme, securityLevel }],
+            ],
+          },
+          vite: {
+            ssr: {
+              // svgdom and mermaid are Node-only packages; they must not be bundled
+              // into the client-side Vite output.
+              external: ['svgdom', 'mermaid'],
+            },
+          },
+        });
+
+        if (injectCSS) {
+          injectScript('page-ssr', `import ${JSON.stringify(STYLES_PATH)}`);
+        }
+      },
+    },
+  };
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "astro-better-mermaid",
+  "version": "0.1.1",
+  "description": "Astro integration for server-side mermaid diagram rendering via svgdom — no client-side JavaScript required",
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "mermaid",
+    "ssr",
+    "remark",
+    "diagram"
+  ],
+  "license": "MIT",
+  "author": "Nathan Contino <ncontino@lambdalatitudinarians.org>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/better-static-sites/better-static-sites.github.io.git",
+    "directory": "astro-better-mermaid"
+  },
+  "homepage": "https://better-static-sites.github.io",
+  "bugs": {
+    "url": "https://github.com/better-static-sites/better-static-sites.github.io/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./index.mjs",
+    "./styles.css": "./src/styles.css"
+  },
+  "files": [
+    "index.mjs",
+    "src/"
+  ],
+  "scripts": {
+    "test": "node --test test/test.mjs"
+  },
+  "dependencies": {
+    "svgdom": "^0.1.28",
+    "unist-util-visit": "^5.0.0"
+  },
+  "peerDependencies": {
+    "astro": ">=4.0.0",
+    "mermaid": ">=10.0.0"
+  },
+  "peerDependenciesMeta": {
+    "mermaid": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "mermaid": "^11.0.0"
+  }
+}

package/src/remark.mjs

@@ -0,0 +1,180 @@
+/**
+ * Remark plugins for mermaid SSR.
+ *
+ * remarkMermaidSSR  — renders ```mermaid blocks to inline SVG at build time using
+ *                     svgdom as a headless browser shim. Diagrams that fail are
+ *                     left as fenced code blocks.
+ *
+ * mermaidTitleFix   — reads `title="..."` from mermaid code block meta and emits
+ *                     a <p data-title-bottom> node below the diagram. Non-mermaid
+ *                     blocks are left alone; rehypeCodeBlocks handles their titles.
+ *
+ * IMPORTANT: mermaid must be imported at module-evaluation time — Vite's module
+ * runner closes before remark callbacks fire, making dynamic imports impossible
+ * inside the plugin body.
+ */
+
+import { visit } from 'unist-util-visit';
+import { createRequire } from 'node:module';
+import { webcrypto } from 'node:crypto';
+
+const _require = createRequire(import.meta.url);
+
+function setupSvgdom() {
+  let createSVGWindow;
+  try { ({ createSVGWindow } = _require('svgdom')); } catch { return null; }
+
+  const win = createSVGWindow();
+  const doc = win.document;
+
+  // svgdom creates SVG documents with no <body>; mermaid's d3 needs select("body").
+  const body = doc.createElement('body');
+  doc.documentElement.appendChild(body);
+  Object.defineProperty(doc, 'body', { get: () => body, configurable: true });
+
+  class CSSStyleSheet {
+    constructor() { this.cssRules = []; }
+    insertRule(rule) { this.cssRules.push({ cssText: rule }); }
+  }
+
+  // svgdom only implements SVG element geometry; mermaid calls this on HTML elements
+  // to measure label text. Return a plausible box based on character count.
+  if (win.HTMLElement) {
+    win.HTMLElement.prototype.getBoundingClientRect = function () {
+      const w = Math.max(50, (this.textContent || '').length * 8);
+      return { width: w, height: 24, top: 0, left: 0, right: w, bottom: 24, x: 0, y: 0 };
+    };
+  }
+
+  win.location = new URL('http://localhost/');
+  win.crypto = webcrypto;
+  win.CSSStyleSheet = CSSStyleSheet;
+  win.addEventListener    = () => {};
+  win.removeEventListener = () => {};
+  win.dispatchEvent       = () => false;
+  win.getComputedStyle    = () => new Proxy({}, { get: () => '' });
+  win.MutationObserver = class { observe(){} disconnect(){} takeRecords(){ return []; } };
+  win.ResizeObserver   = class { observe(){} disconnect(){} };
+
+  globalThis.window        = win;
+  globalThis.document      = doc;
+  globalThis.CSSStyleSheet = CSSStyleSheet;
+  for (const k of ['SVGElement', 'HTMLElement', 'Element', 'Node', 'DocumentFragment', 'Event']) {
+    if (win[k]) globalThis[k] = win[k];
+  }
+
+  return { win, doc };
+}
+
+const domReady = setupSvgdom();
+
+// Import mermaid at module-evaluation time — see file header.
+const _mermaidImport = domReady
+  ? import('mermaid').then(m => m.default).catch(err => {
+      console.warn(`[astro-mermaid-ssr] Failed to import mermaid: ${err.message}`);
+      return null;
+    })
+  : Promise.resolve(null);
+
+/**
+ * Remark plugin factory. Options:
+ *   theme         — mermaid theme (default: 'default')
+ *   securityLevel — mermaid securityLevel (default: 'loose')
+ */
+export function remarkMermaidSSR(options = {}) {
+  const {
+    theme = 'default',
+    securityLevel = 'loose',
+  } = options;
+
+  const mermaidReady = _mermaidImport.then(mermaid => {
+    if (!mermaid) return null;
+    mermaid.initialize({
+      startOnLoad: false,
+      theme,
+      securityLevel,
+      htmlLabels: false, // svgdom loses innerHTML inside <foreignObject>; use SVG text
+    });
+    return mermaid;
+  });
+
+  return async (tree) => {
+    const nodes = [];
+    visit(tree, 'code', (node) => {
+      if (node.lang === 'mermaid') nodes.push(node);
+    });
+    if (nodes.length === 0) return;
+
+    const mermaid = await mermaidReady;
+    if (!mermaid) return;
+
+    for (let i = 0; i < nodes.length; i++) {
+      const node = nodes[i];
+      try {
+        const id = `mermaid-ssr-${i}-${Math.random().toString(36).slice(2, 6)}`;
+        let { svg } = await mermaid.render(id, node.value);
+
+        // `style X fill:#color` directives inject `fill:color !important` on cluster
+        // background rects, blocking CSS theme overrides. Strip the !important and stash
+        // the color in data-fill-color so CSS can override per theme.
+        // Skip rects with a class attribute — those are node rects with intentional colors.
+        svg = svg.replace(
+          /(<rect\b[^>]*)\bstyle="fill:(#[0-9a-fA-F]{3,6})\s*!important([^"]*)"/g,
+          (match, prefix, color, rest) => {
+            if (/\bclass=/.test(prefix)) return match;
+            return `${prefix}data-fill-color="${color.toLowerCase()}" style="fill:${color}${rest}"`;
+          }
+        );
+
+        // Multi-word edge labels: the .label group has translate(dx, dy) but the outer
+        // tspan keeps x="0", placing text dx pixels left of its background rect.
+        // Shift the tspan's x by -dx to re-center it on the rect.
+        svg = svg.replace(
+          /(<g class="label"[^>]* transform="translate\()(-?[\d.]+)(,\s*-?[\d.]+\)"><g><rect[^>]*><\/rect><text[^>]*><tspan[^>]* )x="0"/g,
+          (_, pre, dxStr, mid) => {
+            const dx = parseFloat(dxStr);
+            if (Math.abs(dx) < 0.5) return pre + dxStr + mid + 'x="0"';
+            return `${pre}${dxStr}${mid}x="${-dx}"`;
+          }
+        );
+
+        const escapedSrc = node.value.replace(/&/g, '&amp;').replace(/"/g, '&quot;');
+        node.type  = 'html';
+        node.value = `<div class="mermaid" data-processed="true" data-mermaid-src="${escapedSrc}">\n${svg}\n</div>`;
+        delete node.lang;
+        delete node.meta;
+      } catch (err) {
+        console.warn(`[astro-mermaid-ssr] Diagram ${i} failed to render.\n  ${err.message.slice(0, 120)}`);
+      }
+    }
+  };
+}
+
+/**
+ * Remark plugin: reads `title="..."` from mermaid code block meta and emits a
+ * <p data-title-bottom> element AFTER (below) the diagram.
+ * Non-mermaid blocks are left alone -- rehypeCodeBlocks handles their titles.
+ */
+export function mermaidTitleFix() {
+  return (tree) => {
+    visit(tree, 'code', (node, index, parent) => {
+      if (node.lang !== 'mermaid') return;
+      const meta = node.meta || '';
+      const titleMatch = meta.match(/title=["'](.*?)["']/);
+      if (!titleMatch) return;
+
+      const title = titleMatch[1];
+      const titleNode = {
+        type: 'paragraph',
+        data: {
+          hName: 'p',
+          hProperties: { 'data-title-bottom': title },
+        },
+        children: [{ type: 'text', value: title }],
+      };
+
+      parent.children.splice(index + 1, 0, titleNode);
+      return index + 2;
+    });
+  };
+}

package/src/styles.css

@@ -0,0 +1,148 @@
+/* astro-mermaid-ssr default styles
+ *
+ * Covers light mode ([id^="mermaid-"]) and dark mode (.dark [id^="mermaid-"]).
+ * Dark mode uses the .dark parent-class convention (e.g. Tailwind darkMode: 'class').
+ * If your project uses a different dark mode convention, import these rules as a
+ * starting point and adapt the selectors.
+ *
+ * Diagram titles (from title="..." meta) sit below mermaid blocks and above other
+ * code blocks. The .mermaid wrapper div comes from remarkMermaidSSR.
+ */
+
+foreignObject { overflow: visible; }
+
+/* Mermaid diagram title positioning */
+.mermaid:has(+ p[data-title-bottom]) {
+  margin-bottom: 0 !important;
+  padding-bottom: 0 !important;
+}
+.mermaid + [data-title-bottom] {
+  display: block;
+  width: 100%;
+  margin: 0 !important;
+  padding: 0 1rem;
+  border-bottom-left-radius: 0.375rem;
+  border-bottom-right-radius: 0.375rem;
+  font-size: 0.7rem;
+  font-style: italic;
+  text-align: center;
+  letter-spacing: 0.025em;
+}
+
+/* --- Light mode --- */
+[id^="mermaid-"] {
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: auto;
+  font-size: 16px !important;
+  width: 100%;
+
+  p { color: #000 !important; }
+  /* stroke on > * sets the default line/border color and is inherited by all descendants */
+  > * { stroke: #1e293b !important; }
+  line { stroke: #cbd5e1 !important; fill: #cbd5e1 !important; }
+  .cluster > rect { fill: none !important; stroke: #94a3b8 !important; }
+  .error-icon { fill: red !important; }
+  .error-text { fill: red !important; stroke: red !important; }
+
+  /* Lines & arrow markers */
+  .marker { fill: #1e293b !important; stroke: #1e293b !important; }
+  .marker.cross { stroke: red !important; }
+  .messageLine0, .messageLine1 { stroke: #64748b !important; }
+  .flowchart-link { stroke: #64748b !important; }
+  /* flowchart arrows (v2) use .arrowMarkerPath; sequence diagrams use marker IDs */
+  .arrowMarkerPath { fill: #64748b !important; stroke: none !important; }
+  [id$="-arrowhead"] path, [id$="-filled-head"] path,
+  [id$="-solidTopArrowHead"] path, [id$="-solidBottomArrowHead"] path { fill: #64748b !important; stroke: none !important; }
+  [id$="-crosshead"] path,
+  [id$="-stickTopArrowHead"] path, [id$="-stickBottomArrowHead"] path { fill: none !important; stroke: #64748b !important; }
+
+  /* Text */
+  .messageText, .labelText, .labelText > tspan, .noteText, .noteText > tspan { fill: #1e293b !important; stroke: none !important; }
+  .loopText, .loopText > tspan { fill: #f8fafc !important; stroke: none !important; }
+  .labelBox, .loopLine, .note { fill: #c7d2fe !important; stroke: #818cf8 !important; }
+  .nodeLabel p { color: #1e293b !important; }
+  .edgeLabel p { background-color: #e2e8f0 !important; color: #1e293b !important; }
+  /* stroke: none prevents the inherited stroke from outlining label text */
+  .node .label text, .node .label tspan,
+  .cluster-label text, .cluster-label tspan { fill: #1e293b !important; stroke: none !important; }
+  .edgeLabel text, .edgeLabel tspan { fill: #1e293b !important; stroke: none !important; }
+
+  /* Sequence diagram actors & activations */
+  .sequenceNumber { stroke: #eee !important; }
+  #sequencenumber circle { r: 9px; }
+  .actor { stroke: #1e293b !important; fill: #e2e8f0 !important; }
+  text.actor > tspan { fill: #1e293b !important; stroke: none !important; }
+  .actor-line { stroke: #1e293b !important; }
+  .actor-man line { fill: #e2e8f0 !important; stroke: #94a3b8 !important; }
+  .actor-man circle { fill: #e2e8f0 !important; stroke: #94a3b8 !important; }
+  .activation0 { fill: #e2e8f0 !important; stroke: #94a3b8 !important; }
+
+  /* Flowchart nodes */
+  .node :is(rect, circle, ellipse, polygon, path) { stroke: #1e293b !important; fill: #e2e8f0 !important; }
+
+  /* Edge label pill: SSR positions the background rect for y=-10.1 but tspan dy="1.1em"
+     renders ~16px lower. translateY corrects the vertical offset; rx/ry round the corners. */
+  .edgeLabel rect {
+    transform: translateY(16px) !important;
+    fill: rgba(226, 232, 240, 0.8) !important;
+    stroke: none !important;
+    rx: 4px; ry: 4px;
+  }
+
+  /* Cluster fills from `style X fill:#color` directives — the remark plugin strips
+     !important and adds data-fill-color so CSS can override per theme. Add rules here
+     for any fill colors used in your diagrams. */
+  .cluster > rect[data-fill-color="#999"] { fill: rgba(148, 163, 184, 0.15) !important; }
+  .cluster > rect[data-fill-color="#944"] { fill: rgba(239, 68, 68, 0.1) !important; }
+}
+
+/* --- Dark mode (requires .dark on an ancestor element) --- */
+.dark [id^="mermaid-"] {
+  > * { stroke: #94a3b8 !important; }
+  line { stroke: #64748b !important; fill: #64748b !important; }
+  .cluster > rect { fill: none !important; stroke: #475569 !important; }
+
+  /* Lines & arrow markers */
+  .marker { fill: #e2e8f0 !important; stroke: #e2e8f0 !important; }
+  .messageLine0, .messageLine1 { stroke: #e2e8f0 !important; }
+  .flowchart-link { stroke: #e2e8f0 !important; }
+  .arrowMarkerPath { fill: #e2e8f0 !important; stroke: none !important; }
+  [id$="-arrowhead"] path, [id$="-filled-head"] path,
+  [id$="-solidTopArrowHead"] path, [id$="-solidBottomArrowHead"] path { fill: #e2e8f0 !important; stroke: none !important; }
+  [id$="-crosshead"] path,
+  [id$="-stickTopArrowHead"] path, [id$="-stickBottomArrowHead"] path { fill: none !important; stroke: #e2e8f0 !important; }
+
+  /* Text */
+  .messageText, .labelText, .labelText > tspan { fill: #f8fafc !important; stroke: none !important; }
+  .noteText, .noteText > tspan { fill: #f1f5f9 !important; stroke: none !important; }
+  .labelBox, .loopLine, .note { fill: #3730a3 !important; stroke: #818cf8 !important; }
+  .nodeLabel p { color: #FFF !important; }
+  .edgeLabel p { background-color: #1e293b !important; color: #FFF !important; }
+  .node .label text, .node .label tspan,
+  .cluster-label text, .cluster-label tspan { fill: #f8fafc !important; stroke: none !important; }
+  .edgeLabel text, .edgeLabel tspan { fill: #f8fafc !important; stroke: none !important; }
+
+  /* Sequence diagram actors & activations */
+  .sequenceNumber { fill: #334155 !important; }
+  .actor { stroke: #94a3b8 !important; fill: #1e293b !important; }
+  text.actor > tspan { fill: #f8fafc !important; stroke: none !important; }
+  .actor-line { stroke: #94a3b8 !important; }
+  .actor-man circle { fill: #1e293b !important; stroke: #94a3b8 !important; }
+  .activation0 { fill: #1e293b !important; stroke: #94a3b8 !important; }
+
+  /* Flowchart nodes */
+  .node :is(rect, circle, ellipse, polygon, path) { stroke: #94a3b8 !important; fill: #1e293b !important; }
+
+  /* Edge label pill */
+  .edgeLabel rect {
+    transform: translateY(16px) !important;
+    fill: rgba(30, 41, 59, 0.85) !important;
+    stroke: none !important;
+    opacity: 1 !important;
+    rx: 4px; ry: 4px;
+  }
+
+  /* Cluster fills — purple tint for neutral groups, red for error/external groups */
+  .cluster > rect[data-fill-color="#999"] { fill: rgba(139, 92, 246, 0.18) !important; }
+  .cluster > rect[data-fill-color="#944"] { fill: rgba(239, 68, 68, 0.2) !important; }
+}