create-eziwiki 0.1.1 → 0.3.0

package/template/lib/content/excerpt.ts

@@ -0,0 +1,142 @@
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import { visit } from 'unist-util-visit';
+import type { Root, RootContent } from 'mdast';
+import { toString as mdastToString } from 'mdast-util-to-string';
+import { getDoc } from './registry';
+import { CACHE_DERIVED_CONTENT } from '../cache';
+
+/**
+ * Short plain-text summaries of documents.
+ *
+ * Used for the card that appears when a reader hovers a wiki link. Deriving it
+ * from Markdown rather than from the rendered HTML keeps markup, syntax
+ * highlighting, and the `ezw-` wrappers out of what is meant to be one or two
+ * readable sentences.
+ *
+ * Server-only.
+ */
+
+/** How much of a document the card shows before trailing off. */
+const MAX_LENGTH = 180;
+
+/** Parser used only to reach the text; no rendering plugins. */
+const parser = unified().use(remarkParse).use(remarkGfm);
+
+/**
+ * Node types that carry no prose worth previewing.
+ *
+ * A page opening with a diagram or a command should preview as the sentence
+ * underneath it, not as an empty string or a line of shell.
+ */
+const SKIPPED = new Set(['code', 'thematicBreak', 'image', 'html', 'table', 'math']);
+
+/**
+ * Whether a node is the document's own title heading.
+ *
+ * The card shows the title separately, so repeating it as the first line of the
+ * body wastes the little space there is.
+ */
+function isTitleHeading(node: RootContent): boolean {
+  return node.type === 'heading' && node.depth === 1;
+}
+
+/**
+ * Collapses a node's text into a single line.
+ */
+function flatten(node: RootContent): string {
+  // An image alt is not prose; strip it so a paragraph that is only a figure
+  // does not preview as its alt text.
+  const clone: Root = { type: 'root', children: [structuredClone(node)] };
+  visit(clone, 'image', (_image, index, parent) => {
+    if (parent && index !== undefined) parent.children.splice(index, 1);
+    return index;
+  });
+
+  return mdastToString(clone).replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Builds a one-or-two sentence summary of a Markdown document.
+ *
+ * Prefers the frontmatter description, which an author wrote deliberately.
+ * Otherwise takes prose from the top of the document, skipping the title and
+ * anything that is not text, and stops at a word boundary so the card never
+ * cuts mid-word.
+ *
+ * @param markdown - Document body, with frontmatter already stripped
+ * @param description - `description` from the frontmatter, when present
+ * @returns The summary, or an empty string when the document has no prose
+ *
+ * @example
+ * ```typescript
+ * buildExcerpt('# Title\n\nThe first sentence.'); // 'The first sentence.'
+ * buildExcerpt('# Title\n\nIgnored.', 'From the frontmatter'); // 'From the frontmatter'
+ * ```
+ */
+export function buildExcerpt(markdown: string, description?: string): string {
+  if (description?.trim()) return truncate(description.trim());
+
+  const tree = parser.parse(markdown) as Root;
+  const parts: string[] = [];
+
+  for (const node of tree.children) {
+    if (isTitleHeading(node) || SKIPPED.has(node.type)) continue;
+
+    const text = flatten(node);
+    if (!text) continue;
+
+    parts.push(text);
+    if (parts.join(' ').length >= MAX_LENGTH) break;
+  }
+
+  return truncate(parts.join(' '));
+}
+
+const cache = new Map<string, string>();
+
+/**
+ * Returns a document's summary, memoised by path.
+ *
+ * A popular page is linked from dozens of others, and each of those links asks
+ * for the same summary while its page is rendered. Parsing the target once per
+ * build rather than once per link keeps that from showing up in build time.
+ *
+ * @param docPath - Content-relative path without extension
+ * @returns The summary, or an empty string when there is no such document
+ *
+ * @example
+ * ```typescript
+ * getExcerpt('getting-started/quick-start'); // 'Get a wiki running in…'
+ * ```
+ */
+export function getExcerpt(docPath: string): string {
+  // Checked through the map rather than `cached()`, because an empty summary is
+  // a legitimate result and would otherwise be indistinguishable from a miss.
+  if (CACHE_DERIVED_CONTENT) {
+    const hit = cache.get(docPath);
+    if (hit !== undefined) return hit;
+  }
+
+  const doc = getDoc(docPath);
+  const excerpt = doc ? buildExcerpt(doc.content, doc.description) : '';
+
+  cache.set(docPath, excerpt);
+  return excerpt;
+}
+
+/**
+ * Shortens text to the preview length, breaking at a space.
+ *
+ * @param text - Text to shorten
+ * @returns The text, with an ellipsis when it was cut
+ */
+function truncate(text: string): string {
+  if (text.length <= MAX_LENGTH) return text;
+
+  const cut = text.slice(0, MAX_LENGTH);
+  const lastSpace = cut.lastIndexOf(' ');
+
+  return `${(lastSpace > MAX_LENGTH / 2 ? cut.slice(0, lastSpace) : cut).trimEnd()}…`;
+}

package/template/lib/content/registry.ts

@@ -25,6 +25,13 @@ export interface ContentDoc {
   order: number;
   /** Excluded from navigation, but still reachable by direct URL */
   hidden: boolean;
+  /**
+   * Paths this document used to live at.
+   *
+   * A wiki moves pages; without these, every published link to the old
+   * location breaks silently the moment a file is renamed.
+   */
+  aliases: string[];
   /** Full parsed frontmatter, for consumers that need custom fields */
   frontmatter: Record<string, unknown>;
   /** Markdown body with frontmatter stripped */
@@ -107,6 +114,29 @@ function readBoolean(value: unknown): boolean {
   return false;
 }
 
+/**
+ * Reads the `aliases` frontmatter into a list of content paths.
+ *
+ * Accepts a single string or a list, since an author moving one page writes
+ * one path and should not have to remember which form is required. Leading and
+ * trailing slashes and a `.md` suffix are tolerated: the value looks like a
+ * path, and being strict about its punctuation would only produce silent
+ * misses.
+ *
+ * @param value - The raw frontmatter value
+ * @returns Normalised content paths, without duplicates
+ */
+function readAliases(value: unknown): string[] {
+  const raw = typeof value === 'string' ? [value] : Array.isArray(value) ? value : [];
+
+  const paths = raw
+    .filter((entry): entry is string => typeof entry === 'string')
+    .map((entry) => entry.trim().replace(/^\/+/, '').replace(/\.md$/i, '').replace(/\/+$/, ''))
+    .filter(Boolean);
+
+  return [...new Set(paths)];
+}
+
 /**
  * Reads the optional `_meta.json` for a content subdirectory.
  *
@@ -198,6 +228,7 @@ function readDoc(filePath: string): ContentDoc | null {
     description: typeof frontmatter.description === 'string' ? frontmatter.description : undefined,
     order: readOrder(frontmatter.order),
     hidden: readBoolean(frontmatter.hidden) || frontmatter.nav === false,
+    aliases: readAliases(frontmatter.aliases),
     frontmatter,
     content,
     filePath,

package/template/lib/graph/build.ts

@@ -6,6 +6,7 @@ import type { Root, Link, Text } from 'mdast';
 import { getContentRegistry, type ContentDoc } from '../content/registry';
 import { resolveTarget } from '../content/resolver';
 import { findWikiLinks } from '../markdown/wikilink';
+import { resolveAsset } from '../content/assets';
 import { getSite } from '../site';
 import { cached } from '../cache';
 
@@ -117,6 +118,12 @@ function scanDoc(doc: ContentDoc): { targets: Set<string>; broken: BrokenLink[]
       // An anchor-only link stays within the page and is not an edge.
       if (!link.target) continue;
 
+      // `![[diagram.png]]` embeds a file. It is neither an edge between pages
+      // nor a broken reference, so it leaves the graph here. An embed that
+      // names no such file falls through, matching the renderer, which treats
+      // it as a link to a document.
+      if (link.embed && resolveAsset(link.target)) continue;
+
       const resolution = resolveTarget(link.target);
 
       if (resolution.doc) {
@@ -197,6 +204,54 @@ export function getLinkGraph(): LinkGraph {
   return memo;
 }
 
+/** A page and everything one link away from it. */
+export interface LocalGraph {
+  /** The page itself, plus its immediate neighbours */
+  nodes: GraphNode[];
+  /** Links among those nodes, including ones not touching the page */
+  edges: GraphEdge[];
+}
+
+/**
+ * Returns the neighbourhood around a page.
+ *
+ * The whole-site graph answers "how is this wiki shaped"; past a few dozen
+ * pages it stops answering "what is near this one", which is the question a
+ * reader has while reading. This is that view: the page, everything it links
+ * to, everything linking to it, and the links among them — the last so the
+ * neighbours read as a cluster rather than a fan of unconnected dots.
+ *
+ * Direction is deliberately not distinguished. A reader looking for related
+ * pages cares that two are connected, not which one did the linking; the
+ * backlinks list already says that for the pages that point here.
+ *
+ * @param path - Content path of the page at the centre
+ * @returns The neighbourhood, or empty when the page has no links either way
+ *
+ * @example
+ * ```typescript
+ * const { nodes, edges } = getLocalGraph('features/wiki-links');
+ * nodes.length; // the page plus its neighbours
+ * ```
+ */
+export function getLocalGraph(path: string): LocalGraph {
+  const graph = getLinkGraph();
+
+  const neighbours = new Set<string>([
+    ...(graph.outbound.get(path) ?? []),
+    ...(graph.backlinks.get(path) ?? []),
+  ]);
+
+  if (neighbours.size === 0) return { nodes: [], edges: [] };
+
+  const included = new Set<string>([path, ...neighbours]);
+
+  return {
+    nodes: graph.nodes.filter((node) => included.has(node.path)),
+    edges: graph.edges.filter((edge) => included.has(edge.from) && included.has(edge.to)),
+  };
+}
+
 /**
  * Returns the documents that link to a given page.
  *

package/template/lib/graph/health.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from 'vitest';
+import { getWikiHealth } from './health';
+import { getLinkGraph } from './build';
+import { getReadingOrder } from '../navigation/sequence';
+
+describe('getWikiHealth', () => {
+  it('finds pages nothing links to', () => {
+    const graph = getLinkGraph();
+
+    for (const page of getWikiHealth().orphans) {
+      expect(graph.backlinks.get(page.path) ?? []).toHaveLength(0);
+    }
+  });
+
+  it('finds pages with no links out', () => {
+    const graph = getLinkGraph();
+
+    for (const page of getWikiHealth().deadEnds) {
+      expect(graph.outbound.get(page.path) ?? []).toHaveLength(0);
+    }
+  });
+
+  // Where a reader starts needs nothing pointing at it. Reporting it on every
+  // build would teach everyone to ignore the report.
+  it('never calls the entry page an orphan', () => {
+    const [entry] = getReadingOrder();
+
+    expect(getWikiHealth().orphans.map((page) => page.path)).not.toContain(entry);
+  });
+
+  it('reports only pages that are in the graph', () => {
+    const paths = new Set(getLinkGraph().nodes.map((node) => node.path));
+    const { orphans, deadEnds } = getWikiHealth();
+
+    for (const page of [...orphans, ...deadEnds]) {
+      expect(paths.has(page.path)).toBe(true);
+    }
+  });
+
+  // Hidden pages are absent from the graph entirely, so an unlisted page is
+  // not reported as disconnected — it is unlisted on purpose.
+  it('says nothing about hidden pages', () => {
+    const { orphans, deadEnds } = getWikiHealth();
+    const reported = [...orphans, ...deadEnds].map((page) => page.path);
+    const visible = new Set(getLinkGraph().nodes.map((node) => node.path));
+
+    for (const path of reported) {
+      expect(visible.has(path)).toBe(true);
+    }
+  });
+
+  it('gives every reported page a title and a link', () => {
+    const { orphans, deadEnds } = getWikiHealth();
+
+    for (const page of [...orphans, ...deadEnds]) {
+      expect(page.title).toBeTruthy();
+      expect(page.url).toBeTruthy();
+    }
+  });
+});

package/template/lib/graph/health.ts

@@ -0,0 +1,58 @@
+import { getLinkGraph, type GraphNode } from './build';
+import { getReadingOrder } from '../navigation/sequence';
+import { cached } from '../cache';
+
+/**
+ * What the link graph says about the state of the wiki.
+ *
+ * A broken link is an error and already reported. These are not errors — a
+ * wiki can be perfectly correct and still have them — but they are the shapes
+ * a collection of documents falls into when it stops being a wiki: pages
+ * nothing leads to, and pages nothing leads on from. Neither is visible from
+ * inside a single document, and neither shows up in a link check, which only
+ * asks whether the links that exist resolve.
+ *
+ * Server-only.
+ */
+
+/** Pages the graph flags as worth a second look. */
+export interface WikiHealth {
+  /** Pages nothing links to, so a reader can only arrive through the sidebar */
+  orphans: GraphNode[];
+  /** Pages with no links out, where a reader arrives and has nowhere to go */
+  deadEnds: GraphNode[];
+}
+
+let memo: WikiHealth | null = null;
+
+/**
+ * Finds pages that are disconnected from the rest of the wiki.
+ *
+ * The first page in reading order is never an orphan. It is where a reader
+ * starts, so nothing needs to point at it, and reporting it every build would
+ * teach everyone to ignore the report.
+ *
+ * @returns The pages worth looking at
+ *
+ * @example
+ * ```typescript
+ * const { orphans, deadEnds } = getWikiHealth();
+ * orphans.map((page) => page.path); // ['examples/api-docs', …]
+ * ```
+ */
+export function getWikiHealth(): WikiHealth {
+  const hit = cached(memo);
+  if (hit) return hit;
+
+  const graph = getLinkGraph();
+  const [entry] = getReadingOrder();
+
+  const orphans = graph.nodes.filter(
+    (node) => node.path !== entry && (graph.backlinks.get(node.path) ?? []).length === 0,
+  );
+
+  const deadEnds = graph.nodes.filter((node) => (graph.outbound.get(node.path) ?? []).length === 0);
+
+  memo = { orphans, deadEnds };
+  return memo;
+}

package/template/lib/markdown/callout.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect } from 'vitest';
+import { renderMarkdown } from './render';
+
+/** Renders a callout and reports what it became. */
+async function render(markdown: string) {
+  const { html } = await renderMarkdown(`${markdown}\n`);
+
+  return {
+    html,
+    kind: (html.match(/ezw-callout--(\w+)/) ?? [])[1] ?? null,
+    tag: (html.match(/<(details|div)[^>]*ezw-callout/) ?? [])[1] ?? null,
+    title: (html.match(/ezw-callout__title">([^<]*)/) ?? [])[1] ?? null,
+  };
+}
+
+describe('callouts', () => {
+  it('turns a marked blockquote into a callout', async () => {
+    const { kind, tag, title, html } = await render('> [!NOTE]\n> Useful information.');
+
+    expect(kind).toBe('note');
+    expect(tag).toBe('div');
+    expect(title).toBe('Note');
+    expect(html).toContain('Useful information.');
+  });
+
+  it('uses a title given on the marker line', async () => {
+    expect((await render('> [!WARNING] Mind the gap\n> Careful.')).title).toBe('Mind the gap');
+  });
+
+  it('recognises the kinds case-insensitively', async () => {
+    expect((await render('> [!note]\n> x')).kind).toBe('note');
+    expect((await render('> [!NoTe]\n> x')).kind).toBe('note');
+  });
+
+  // Obsidian defines more kinds than GitHub and vaults use them, so they map
+  // onto the nearest one instead of losing their formatting.
+  it('maps the extra Obsidian kinds onto the nearest one', async () => {
+    expect((await render('> [!danger]\n> x')).kind).toBe('caution');
+    expect((await render('> [!success]\n> x')).kind).toBe('tip');
+    expect((await render('> [!question]\n> x')).kind).toBe('important');
+  });
+
+  it('leaves an unknown kind as an ordinary quote', async () => {
+    const { kind, html } = await render('> [!nonsense]\n> x');
+
+    expect(kind).toBeNull();
+    expect(html).toContain('<blockquote>');
+  });
+
+  it('leaves a plain quote alone', async () => {
+    const { kind, html } = await render('> Just a quote.');
+
+    expect(kind).toBeNull();
+    expect(html).toContain('<blockquote>');
+  });
+
+  // `<details>` opens and closes without script, so a disclosure keeps working
+  // with JavaScript disabled.
+  it('folds with a trailing - or +', async () => {
+    const closed = await render('> [!TIP]- Optional\n> Hidden.');
+    const open = await render('> [!TIP]+ Shown\n> Visible.');
+
+    expect(closed.tag).toBe('details');
+    expect(closed.html).not.toMatch(/<details[^>]*\sopen/);
+    expect(open.tag).toBe('details');
+    expect(open.html).toMatch(/<details[^>]*\sopen/);
+  });
+
+  // The body passes through the rest of the pipeline, so nothing inside a
+  // callout behaves differently from the same text outside one.
+  it('renders links, wiki links and code inside the body', async () => {
+    // `intro` is the one page both this repository and a scaffolded project
+    // have, so the test travels with the engine.
+    const wiki = await render('> [!NOTE]\n> See [[intro]].');
+    const code = await render('> [!TIP]\n> Run `npm i`.');
+
+    expect(wiki.html).toContain('ezw-wikilink');
+    expect(code.html).toContain('<code');
+  });
+
+  it('keeps a multi-line body together', async () => {
+    const { html } = await render('> [!NOTE]\n> First line.\n> Second line.');
+
+    expect(html).toContain('First line.');
+    expect(html).toContain('Second line.');
+  });
+});

package/template/lib/markdown/mermaid.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest';
+import { renderMarkdown } from './render';
+
+/** Wraps a diagram in a fence tagged `mermaid`. */
+function fence(body: string): string {
+  return ['```mermaid', body, '```', ''].join('\n');
+}
+
+describe('mermaid diagrams', () => {
+  it('draws a fence as SVG during the build', async () => {
+    const { html } = await renderMarkdown(fence('flowchart TD\n  A[One] --> B[Two]'));
+
+    expect(html).toContain('class="ezw-mermaid"');
+    expect(html).toContain('<svg');
+    expect(html).toContain('One');
+  });
+
+  // The site self-hosts and subsets its fonts; the renderer inlines a Google
+  // Fonts import that would undo that on every page carrying a diagram.
+  it('carries no third-party request', async () => {
+    const { html } = await renderMarkdown(fence('flowchart TD\n  A --> B'));
+
+    expect(html).not.toContain('fonts.googleapis.com');
+    expect(html).not.toContain('@import');
+  });
+
+  // Fixed inline, the colours would survive a switch to dark; left to CSS, the
+  // diagram follows the theme like everything else.
+  it('leaves its colours to the stylesheet', async () => {
+    const { html } = await renderMarkdown(fence('flowchart TD\n  A --> B'));
+
+    expect(html).toMatch(/var\(--(bg|fg)\)/);
+    expect(html).not.toMatch(/<svg[^>]*style="[^"]*--bg/);
+  });
+
+  // Nothing is drawn in the browser, so a crawler and a reader without
+  // JavaScript see the same diagram everyone else does.
+  it('needs no script to appear', async () => {
+    const { html } = await renderMarkdown(fence('flowchart TD\n  A --> B'));
+
+    expect(html).not.toContain('<script');
+  });
+
+  it('draws the kinds a wiki actually uses', async () => {
+    const kinds = [
+      'sequenceDiagram\n  A->>B: hello',
+      'stateDiagram-v2\n  [*] --> Draft',
+      'classDiagram\n  class Page',
+      'erDiagram\n  PAGE ||--o{ LINK : has',
+    ];
+
+    for (const source of kinds) {
+      expect((await renderMarkdown(fence(source))).html).toContain('ezw-mermaid');
+    }
+  });
+
+  // A kind the renderer cannot draw leaves the reader exactly what they had
+  // before diagrams existed, rather than stopping the build.
+  it('falls back to a code block on an unsupported diagram', async () => {
+    const { html } = await renderMarkdown(fence('pie title X\n  "a" : 1'));
+
+    expect(html).not.toContain('ezw-mermaid');
+    expect(html).toContain('data-language="mermaid"');
+  });
+
+  it('leaves ordinary code fences alone', async () => {
+    const { html } = await renderMarkdown('```js\nconst a = 1;\n```\n');
+
+    expect(html).toContain('ezw-code');
+    expect(html).not.toContain('ezw-mermaid');
+  });
+});

package/template/lib/markdown/rehype-mermaid.ts

@@ -0,0 +1,133 @@
+import { visit } from 'unist-util-visit';
+import { toString } from 'hast-util-to-string';
+import type { Element, Root } from 'hast';
+
+/**
+ * Renders ```mermaid fences to SVG during the build.
+ *
+ * The usual way to put a diagram on a page is to ship Mermaid to the browser
+ * and let it draw one after load. That would be the largest thing this site
+ * downloads by a wide margin, it would move the page as the diagram appeared,
+ * and a crawler or a reader without JavaScript would see nothing. The diagram
+ * is fixed at build time, so it is drawn once, here, and arrives as markup.
+ *
+ * A fence that cannot be drawn is left alone, and goes on to be highlighted as
+ * an ordinary code block. Failing that way costs a reader nothing they had
+ * before, while stopping the build over one diagram would.
+ */
+
+/** Class Markdown gives a fence tagged `mermaid`. */
+const FENCE_CLASS = 'language-mermaid';
+
+/**
+ * The renderer, loaded on first use.
+ *
+ * `beautiful-mermaid` ships ESM only, with no CommonJS entry, so a static
+ * import fails in the build scripts that reach this module through `tsx`.
+ * Importing it dynamically works from either, and the promise is kept so the
+ * cost is paid once rather than per document.
+ */
+let rendererPromise: Promise<(text: string) => string> | null = null;
+
+/**
+ * Returns the SVG renderer.
+ */
+function getRenderer(): Promise<(text: string) => string> {
+  rendererPromise ??= import('beautiful-mermaid').then((module) => module.renderMermaidSVG);
+  return rendererPromise;
+}
+
+/**
+ * Pulls the web-font import out of the rendered SVG.
+ *
+ * The renderer inlines an `@import` for Google Fonts, which would be a
+ * third-party request on every page carrying a diagram — from a site that
+ * self-hosts and subsets its fonts precisely so there are none. The diagram
+ * inherits the page's font once the rule is gone.
+ */
+function stripFontImport(svg: string): string {
+  return svg.replace(/@import\s+url\([^)]*\);?/g, '');
+}
+
+/**
+ * Removes the colours the renderer fixes on the root element.
+ *
+ * It writes `--bg` and `--fg` into an inline `style`, where a stylesheet cannot
+ * reach them, which would leave every diagram in its light-theme colours after
+ * a reader switched to dark. Dropping them lets the site's own CSS supply the
+ * variables the SVG already refers to — the same arrangement the syntax
+ * highlighter uses.
+ */
+function stripInlineColours(svg: string): string {
+  return svg.replace(/(<svg[^>]*?)\sstyle="[^"]*"/, '$1');
+}
+
+/**
+ * Reads the fence's language from its class list.
+ */
+function isMermaidFence(node: Element): boolean {
+  const className = node.properties?.className;
+  const classes = Array.isArray(className) ? className.map(String) : [];
+
+  return classes.includes(FENCE_CLASS);
+}
+
+/**
+ * Rehype plugin factory.
+ *
+ * Must run before the code-block chrome and the highlighter, so that a fence it
+ * claims never becomes a code block, and one it declines still does.
+ *
+ * @example
+ * ```typescript
+ * unified().use(rehypeMermaid).use(rehypeCodeShell).use(rehypeShiki, options);
+ * ```
+ */
+export function rehypeMermaid() {
+  return async (tree: Root) => {
+    // Collected first, then rendered: `visit` is synchronous, and the renderer
+    // has to be awaited before any of it can be drawn.
+    const fences: Array<{ parent: Root | Element; index: number; source: string }> = [];
+
+    visit(tree, 'element', (node: Element, index, parent) => {
+      if (node.tagName !== 'pre' || !parent || index === undefined) return;
+
+      const code = node.children.find(
+        (child): child is Element => child.type === 'element' && child.tagName === 'code',
+      );
+
+      if (!code || !isMermaidFence(code)) return;
+
+      fences.push({ parent: parent as Root | Element, index, source: toString(code) });
+    });
+
+    if (fences.length === 0) return;
+
+    const render = await getRenderer();
+
+    for (const fence of fences) {
+      let svg: string;
+
+      try {
+        svg = render(fence.source);
+      } catch {
+        // Diagram kinds the renderer does not know, and syntax it cannot read,
+        // both land here. The fence stays as it was written and goes on to be
+        // highlighted as an ordinary code block.
+        continue;
+      }
+
+      fence.parent.children[fence.index] = {
+        type: 'element',
+        tagName: 'figure',
+        properties: { className: ['ezw-mermaid'] },
+        children: [
+          // Serialised verbatim: `rehype-stringify` is configured to pass raw
+          // through, and parsing the SVG back into a tree only to print it
+          // again would buy nothing.
+          { type: 'raw', value: stripInlineColours(stripFontImport(svg)) } as never,
+        ],
+      };
+    }
+  };
+}