Add Mermaid to Unified stack

Author: webstackdev

.cache/pages.json

@@ -22,16 +22,10 @@
   "contact",
   "offline",
   {
-    "privacy": [
-      "my-data"
-    ]
+    "privacy": ["my-data"]
   },
   {
-    "services": [
-      "consulting",
-      "overview",
-      "web-development"
-    ]
+    "services": ["consulting", "overview", "web-development"]
   },
   {
     "tags": [
@@ -46,4 +40,4 @@
       "typescript"
     ]
   }
-]
+]

_TODO.md

@@ -163,25 +163,6 @@ Needs to add real API key and test
 - (Optional) Set up Bridgy for social media
 - Test with sample webmentions
 
-## "Add to Calendar" button
-
-Google Calendar, Apple Calendar,  Yahoo Calender,  Microsoft 365, Outlook, and Teams, and generate iCal/ics files (for all other calendars and cases).
-
-`https://github.com/add2cal/add-to-calendar-button`
-`https://add-to-calendar-button.com/`
-
-## Astro wrapper for the `@github/clipboard-copy-element` web component. Copies element text content or input values to the clipboard
-
-[`clipboard-copy`](https://github.com/BryceRussell/astro-github-elements/tree/main/packages/clipboard-copy#astro-github-elementsclipboard-copy)
-
-## Astro wrapper for GitHub's relative time web component. Translates dates to past or future time phrases, like "*4 hours from now*" or "*20 days ago*"
-
-[Relative Time](https://github.com/BryceRussell/astro-github-elements/tree/main/packages/time#readme)
-
-## Display text in a circular layout
-
-[TextCircle](https://github.com/LoStisWorld/astro-textcircle#astro-textcircle)
-
 ## Custom Directives
 
 [`astro-directives`](https://github.com/QuentinDutot/astro-directives)
@@ -229,6 +210,27 @@ You can then opt-out of prefetching for individual links by setting data-astro-p
 <a href="/about" data-astro-prefetch="false">About</a>
 ```
 
+## Astro Components to Add
+
+### "Add to Calendar" button
+
+Google Calendar, Apple Calendar,  Yahoo Calender,  Microsoft 365, Outlook, and Teams, and generate iCal/ics files (for all other calendars and cases).
+
+`https://github.com/add2cal/add-to-calendar-button`
+`https://add-to-calendar-button.com/`
+
+### Astro wrapper for the `@github/clipboard-copy-element` web component. Copies element text content or input values to the clipboard
+
+[`clipboard-copy`](https://github.com/BryceRussell/astro-github-elements/tree/main/packages/clipboard-copy#astro-github-elementsclipboard-copy)
+
+### Astro wrapper for GitHub's relative time web component. Translates dates to past or future time phrases, like "*4 hours from now*" or "*20 days ago*"
+
+[Relative Time](https://github.com/BryceRussell/astro-github-elements/tree/main/packages/time#readme)
+
+### Display text in a circular layout
+
+[TextCircle](https://github.com/LoStisWorld/astro-textcircle#astro-textcircle)
+
 ## Markdown
 
 ## Code Block and Highlighting
@@ -275,19 +277,3 @@ const markdownCodeCopyConfig = {
   attachText: ``,
 }
 ```
-
-Next I'd like to setup the rehype-mermaid package. I've installed it already.
-1. Use the 'inline-svg' strategy
-2. Point the 'css' option key to a file src/styles/vendor/mermaid.css
-3. In the 'errorFallback' add a function that rethrows the error as a BuildError with descriptive text that Mermaid has encountered something it can't graph
-4. Evaluate whether we can set fontFamily in the mermaidConfig option property to use one of our fonts in public/fonts. The docs mention "You need to call mermaid.initialize() manually", I'm not sure if we can do this.
-
-### rehype-mermaid
-
-```mermaid
-graph TD
-    A[Start] --> B{Is it working?}
-    B -->|Yes| C[Great!]
-    B -->|No| D[Debug]
-    D --> B
-```

src/content/articles/demo/index.mdx

@@ -529,6 +529,26 @@ There is a doc listing all available emojis in the /docs directory.
 
 :rocket:
 
+### rehype-mermaid
+
+With Mermaid markup like this in a code block with "mermaid" set as the language:
+
+```text
+graph TD
+    A[Start ] --> B{Is it working? }
+    B -->|Yes | C[Great!]
+    B -->|No | D[Debug ]
+    D --> B
+```
+
+```mermaid
+graph TD
+    A[Start ] --> B{Is it working? }
+    B -->|Yes | C[Great! ]
+    B -->|No | D[Debug ]
+    D --> B
+```
+
 ### remark-align
 
 This custom plugin parses custom Markdown syntax to center- or right-align elements. Alignment is done by wrapping something in shortcode-style tags, applying Tailwind `text-right` or `text-center` classes:

src/content/test-fixtures/markdown/index.mdx

@@ -110,6 +110,16 @@ $$
 E = mc^2
 $$
 
+## Mermaid (rehype-mermaid)
+
+```mermaid
+graph TD
+	A --> B
+	A --> C
+	B --> D
+	C --> D
+```
+
 ## Captions (remark-captions)
 
 > Do it or do it not, there is no try

src/lib/config/markdown.ts

@@ -28,6 +28,9 @@ Object.defineProperty(rehypeAccessibleEmojis, 'name', { value: 'rehypeAccessible
 import rehypeMathjax from 'rehype-mathjax'
 Object.defineProperty(rehypeMathjax, 'name', { value: 'rehypeMathjax' })
 
+import rehypeMermaid from 'rehype-mermaid'
+Object.defineProperty(rehypeMermaid, 'name', { value: 'rehypeMermaid' })
+
 import type { Options as RehypeAutolinkHeadingsOptions } from 'rehype-autolink-headings'
 import rehypeAutolinkHeadings from 'rehype-autolink-headings'
 Object.defineProperty(rehypeAutolinkHeadings, 'name', { value: 'rehypeAutolinkHeadings' })
@@ -123,6 +126,8 @@ Object.defineProperty(remarkSmartypants, 'name', { value: 'remarkSmartypants' })
 import { rehypeTailwindClasses } from '../markdown/plugins/rehype-tailwind'
 Object.defineProperty(rehypeTailwindClasses, 'name', { value: 'rehypeTailwindClasses' })
 
+import { BuildError } from '../errors/BuildError'
+
 /**
  * ==============================================================
  *
@@ -146,6 +151,25 @@ Object.defineProperty(remarkLinkifyRegexUrls, 'name', { value: 'remarkLinkifyReg
 /** remark-attributes plugin */
 export const remarkAttributesConfig = { scope: 'permissive' } as const
 
+/** rehype-mermaid plugin */
+export const rehypeMermaidConfig = {
+  strategy: 'inline-svg',
+  css: new URL('../../styles/vendor/mermaid.css', import.meta.url),
+  mermaidConfig: {
+    fontFamily: '"Onest Regular", arial, sans-serif',
+  },
+  errorFallback: (_element: unknown, _diagram: string, error: unknown, file: unknown) => {
+    const filePath =
+      typeof (file as { path?: unknown } | null)?.path === 'string' ? ((file as { path: string }).path as string) : undefined
+
+    throw new BuildError(new Error("Mermaid couldn't graph this diagram.", { cause: error }), {
+      phase: 'compilation',
+      tool: 'mermaid',
+      filePath,
+    })
+  },
+} as const
+
 /** rehype-autolink-headings plugin */
 export const rehypeAutolinkHeadingsConfig: RehypeAutolinkHeadingsOptions = {
   content: {
@@ -401,6 +425,8 @@ export const markdownConfig: Partial<MdxOptions> = {
      * replaced with <mjx-container> before Tailwind class injection.
      */
     rehypeMathjax,
+    /** Render Mermaid diagrams to inline SVG at build-time */
+    [rehypeMermaid, rehypeMermaidConfig],
     /**
      * Automatically add Tailwind classes to markdown elements as
      * specified in src/lib/markdown/rehype-tailwind-classes.ts

src/lib/markdown/__tests__/e2e/rehype-mermaid.spec.tsx

@@ -0,0 +1,20 @@
+// @vitest-environment node
+
+import { describe, it, expect, beforeAll } from 'vitest'
+
+import { processWithFullPipeline } from '@lib/markdown/helpers/processors'
+
+let html: string
+
+beforeAll(async () => {
+  const markdown = ['```mermaid', 'graph TD;', '  A-->B;', '```'].join('\n')
+  html = await processWithFullPipeline(markdown)
+})
+
+describe('Layer 3: E2E - rehypeMermaid', () => {
+  it('should render Mermaid diagrams as inline SVG', () => {
+    expect(html).toContain('<svg')
+    expect(html).toMatch(/id="mermaid-\d+"/)
+    expect(html).not.toContain('language-mermaid')
+  })
+})

src/lib/markdown/__tests__/integration/rehype-mermaid-astro.spec.ts

@@ -0,0 +1,22 @@
+import { describe, it, expect } from 'vitest'
+import rehypeMermaid from 'rehype-mermaid'
+
+import { rehypeMermaidConfig } from '@lib/config/markdown'
+import { processWithAstroSettings } from '@lib/markdown/helpers/processors'
+
+describe('rehype-mermaid (Layer 2: With Astro Pipeline)', () => {
+  it('should render Mermaid code blocks to inline SVG', async () => {
+    const markdown = ['```mermaid', 'graph TD;', '  A-->B;', '```'].join('\n')
+
+    const html = await processWithAstroSettings({
+      markdown,
+      plugin: rehypeMermaid,
+      pluginOptions: rehypeMermaidConfig,
+      stage: 'rehype',
+    })
+
+    expect(html).toContain('<svg')
+    expect(html).toMatch(/id="mermaid-\d+"/)
+    expect(html).not.toContain('language-mermaid')
+  })
+})

src/lib/markdown/__tests__/units/rehype-mermaid.spec.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest'
+import rehypeMermaid from 'rehype-mermaid'
+
+import { BuildError } from '@lib/errors/BuildError'
+import { rehypeMermaidConfig } from '@lib/config/markdown'
+import { processIsolated } from '@lib/markdown/helpers/processors'
+
+describe('rehype-mermaid (Layer 1: Isolated)', () => {
+  it('should use inline-svg strategy and a local CSS file', () => {
+    expect(rehypeMermaidConfig.strategy).toBe('inline-svg')
+    expect(String(rehypeMermaidConfig.css)).toContain('/src/styles/vendor/mermaid.css')
+  })
+
+  it('should throw BuildError from errorFallback', () => {
+    const element = { type: 'element', tagName: 'code', properties: {}, children: [] }
+    const diagram = 'graph TD\n  A --> B\n'
+    const error = new Error('boom')
+    const file = { path: '/fake/file.mdx' }
+
+    expect(() => rehypeMermaidConfig.errorFallback(element, diagram, error, file)).toThrow(BuildError)
+  })
+
+  it('should render Mermaid code blocks to inline SVG', async () => {
+    const markdown = ['```mermaid', 'graph TD;', '  A-->B;', '```'].join('\n')
+
+    const html = await processIsolated({
+      markdown,
+      plugin: rehypeMermaid,
+      pluginOptions: rehypeMermaidConfig,
+      stage: 'rehype',
+    })
+
+    expect(html).toContain('<svg')
+    expect(html).toMatch(/id="mermaid-\d+"/)
+    expect(html).not.toContain('language-mermaid')
+  })
+})

src/styles/vendor/mermaid.css

@@ -2,3 +2,19 @@
  * Styles for Playwright to use when rendering Mermaid diagrams in Markdown files.
  * This file is only used during the build process and is not included in the final site CSS.
  */
+
+@font-face {
+	font-display: swap;
+	font-family: "Onest Regular";
+	font-style: normal;
+	font-weight: normal;
+	src: url("../../../public/fonts/OnestRegular1602-hint.woff2") format("woff2");
+}
+
+body {
+	font-family: "Onest Regular", arial, sans-serif;
+}
+
+svg {
+	font-family: "Onest Regular", arial, sans-serif;
+}

test/e2e/specs/04-components/markdown.spec.ts

@@ -216,6 +216,18 @@ test.describe('Markdown (MDX) fixture page', () => {
     })
   })
 
+  test.describe('Mermaid (rehype-mermaid)', () => {
+    test('renders Mermaid as inline SVG at build-time', async () => {
+      await expect(markdownPage.heading('Mermaid (rehype-mermaid)', 2)).toBeVisible()
+
+      const diagramSvg = markdownPage.prose.locator('svg[id^="mermaid-"]').first()
+      await expect(diagramSvg).toBeVisible()
+
+      await expect(markdownPage.prose.locator('code.language-mermaid')).toHaveCount(0)
+      await expect(markdownPage.prose.locator('pre.mermaid')).toHaveCount(0)
+    })
+  })
+
   test.describe('Math (remark-math + rehype-mathjax)', () => {
     test('renders TeX as SVG at build-time (no client-side MathJax)', async ({ page }) => {
       await expect(markdownPage.heading('Math (remark-math + rehype-mathjax)', 2)).toBeVisible()