create-eziwiki 0.2.0 → 0.3.0

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,
+        ],
+      };
+    }
+  };
+}

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

@@ -68,6 +68,51 @@ export function rehypeCollectHeadings() {
   };
 }
 
+/** Heading levels that get a link to themselves. */
+const ANCHORED_LEVELS = new Set(['h2', 'h3', 'h4', 'h5', 'h6']);
+
+/**
+ * Appends a link to each heading pointing at itself.
+ *
+ * A reader who wants to send someone to one section of a long page otherwise
+ * has to read the id out of the address bar, or link the whole page and say
+ * "scroll down". Every documentation site solves this the same way, and the
+ * anchor is a real link — focusable, copyable, and working without script.
+ *
+ * `h1` is skipped: it names the page, which the page URL already addresses.
+ * Transcluded headings are skipped too, since their `id` belongs to the
+ * document they came from and linking here would send a reader to a copy.
+ */
+export function rehypeHeadingAnchors() {
+  return (tree: Root) => {
+    visit(tree, 'element', (node: Element) => {
+      if (!ANCHORED_LEVELS.has(node.tagName)) return;
+      if (node.properties?.dataTranscluded) return;
+
+      const id = node.properties?.id;
+      if (typeof id !== 'string' || !id) return;
+
+      node.properties.className = [
+        ...(Array.isArray(node.properties.className) ? node.properties.className.map(String) : []),
+        'ezw-heading',
+      ];
+
+      node.children.push({
+        type: 'element',
+        tagName: 'a',
+        properties: {
+          href: `#${id}`,
+          className: ['ezw-heading__anchor'],
+          // The heading's own text already names the destination; without this
+          // a screen reader hears every heading followed by a stray "#".
+          'aria-label': `Link to this section: ${toString(node)}`,
+        },
+        children: [{ type: 'text', value: '#' }],
+      });
+    });
+  };
+}
+
 /**
  * Determines whether an href points outside the site.
  */

package/template/lib/markdown/remark-callout.ts

@@ -0,0 +1,173 @@
+import { visit } from 'unist-util-visit';
+import type { Root, Blockquote, PhrasingContent, BlockContent } from 'mdast';
+
+/**
+ * Turns `> [!NOTE]` blockquotes into callouts.
+ *
+ * The syntax is GitHub's and Obsidian's alike, which is the reason for
+ * choosing it: a document written for either renders here, and one written
+ * here still reads as an ordinary blockquote anywhere that does not know the
+ * convention. Nothing is invented.
+ *
+ * Runs on the Markdown AST so the body passes through the rest of the pipeline
+ * unchanged — links, code and wiki links inside a callout behave exactly as
+ * they do outside one.
+ */
+
+/**
+ * Marker opening a callout: the kind, an optional fold hint, and an optional
+ * title on the same line.
+ */
+const MARKER = /^\[!([A-Za-z]+)\]([-+])?\s*(.*)$/;
+
+/**
+ * Callout kinds, and the ones that are the same thing under another name.
+ *
+ * GitHub defines five; Obsidian defines more and its vaults use them, so the
+ * extra names map onto the nearest kind rather than falling back to a plain
+ * quote. A vault should not lose its formatting on the way in.
+ */
+const KINDS: Record<string, string> = {
+  note: 'note',
+  info: 'note',
+  abstract: 'note',
+  summary: 'note',
+  tip: 'tip',
+  hint: 'tip',
+  success: 'tip',
+  check: 'tip',
+  done: 'tip',
+  important: 'important',
+  example: 'important',
+  question: 'important',
+  help: 'important',
+  faq: 'important',
+  warning: 'warning',
+  attention: 'warning',
+  todo: 'warning',
+  caution: 'caution',
+  danger: 'caution',
+  error: 'caution',
+  failure: 'caution',
+  fail: 'caution',
+  bug: 'caution',
+};
+
+/** What a callout marker said. */
+interface Marker {
+  /** Normalised kind, one of the values in {@link KINDS} */
+  kind: string;
+  /** Heading text, defaulting to the kind when the author gave none */
+  title: PhrasingContent[];
+  /** Whether the body folds away, and whether it starts open */
+  fold: 'none' | 'open' | 'closed';
+}
+
+/**
+ * Reads the marker from the first line of a blockquote.
+ *
+ * @param node - The blockquote to inspect
+ * @returns The marker, or null when this is an ordinary quote
+ */
+function readMarker(node: Blockquote): Marker | null {
+  const [first] = node.children;
+  if (!first || first.type !== 'paragraph') return null;
+
+  const [lead] = first.children;
+  if (!lead || lead.type !== 'text') return null;
+
+  // Only the first line carries the marker; the rest of the paragraph is body.
+  const newline = lead.value.indexOf('\n');
+  const head = newline === -1 ? lead.value : lead.value.slice(0, newline);
+
+  const match = MARKER.exec(head.trim());
+  if (!match) return null;
+
+  const kind = KINDS[match[1].toLowerCase()];
+  if (!kind) return null;
+
+  const rest = newline === -1 ? '' : lead.value.slice(newline + 1);
+  const heading = match[3].trim();
+
+  // Everything after the marker line stays in the body, including any inline
+  // nodes that followed the opening text.
+  const body: PhrasingContent[] = [
+    ...(rest ? [{ type: 'text' as const, value: rest }] : []),
+    ...first.children.slice(1),
+  ];
+
+  node.children = [
+    ...(body.length ? [{ type: 'paragraph' as const, children: body }] : []),
+    ...node.children.slice(1),
+  ];
+
+  return {
+    kind,
+    title: [{ type: 'text', value: heading || titleFor(kind) }],
+    fold: match[2] === '-' ? 'closed' : match[2] === '+' ? 'open' : 'none',
+  };
+}
+
+/** Default heading for a kind, when the author supplied none. */
+function titleFor(kind: string): string {
+  return kind.charAt(0).toUpperCase() + kind.slice(1);
+}
+
+/**
+ * Builds the callout node.
+ *
+ * A foldable callout becomes `<details>`, which opens and closes without any
+ * script — the browser already knows how to do this, and a disclosure that
+ * depends on JavaScript is one that fails with it disabled.
+ */
+function toCallout(node: Blockquote, marker: Marker): Blockquote {
+  const foldable = marker.fold !== 'none';
+
+  const heading: BlockContent = {
+    type: 'paragraph',
+    data: {
+      hName: foldable ? 'summary' : 'p',
+      hProperties: { className: ['ezw-callout__title'] },
+    },
+    children: marker.title,
+  };
+
+  return {
+    type: 'blockquote',
+    data: {
+      hName: foldable ? 'details' : 'div',
+      hProperties: {
+        className: ['ezw-callout', `ezw-callout--${marker.kind}`],
+        ...(marker.fold === 'open' ? { open: true } : {}),
+      },
+    },
+    children: [heading, ...node.children],
+  };
+}
+
+/**
+ * Remark plugin factory.
+ *
+ * @example
+ * ```typescript
+ * unified().use(remarkParse).use(remarkCallouts);
+ * // > [!WARNING] Mind the gap
+ * // > Body text.
+ * ```
+ */
+export function remarkCallouts() {
+  return (tree: Root) => {
+    visit(tree, 'blockquote', (node: Blockquote, index, parent) => {
+      if (!parent || index === undefined) return;
+
+      const marker = readMarker(node);
+      if (!marker) return;
+
+      parent.children[index] = toCallout(node, marker);
+
+      // Skip the node just written: its children have already been read, and
+      // revisiting would look at a blockquote that is now a callout.
+      return index + 1;
+    });
+  };
+}

package/template/lib/markdown/render.ts

@@ -14,11 +14,14 @@ import {
   rehypeBasePath,
   rehypeCodeShell,
   rehypeCollectHeadings,
+  rehypeHeadingAnchors,
   rehypeImages,
   rehypeInternalLinks,
   type Heading,
 } from './rehype-plugins';
 import { remarkWikiLinks, type WikiLinkTarget, type TranscludeTarget } from './remark-wikilink';
+import { remarkCallouts } from './remark-callout';
+import { rehypeMermaid } from './rehype-mermaid';
 import { getUsedLanguages } from './languages';
 import { cached } from '../cache';
 import { BASE_PATH } from '../basePath';
@@ -171,11 +174,19 @@ function resolveWikiTransclusion(target: string, anchor?: string): TranscludeTar
  * Builds the shared unified processor.
  *
  * Plugin order is load-bearing:
+ * - `remarkCallouts` must run before the wiki-link pass, so that a link written
+ *   inside a callout is resolved like any other rather than being left in the
+ *   text the marker was read from.
  * - `remarkWikiLinks` must run while the tree is still Markdown, so the links
  *   it produces are processed like any other link downstream.
  * - `rehype-raw` must follow `remark-rehype` with `allowDangerousHtml`, so that
  *   inline HTML in Markdown is parsed rather than escaped.
- * - `rehype-slug` must precede heading collection, which reads the ids it adds.
+ * - `rehype-slug` must precede heading collection and the heading anchors,
+ *   both of which read the ids it adds.
+ * - `rehypeHeadingAnchors` must follow heading collection, or the anchor's own
+ *   text would be gathered into the contents rail.
+ * - `rehypeMermaid` must precede both, so a diagram fence never becomes a code
+ *   block, and one it cannot draw still does.
  * - `rehypeCodeShell` must precede the highlighter, since it reads the
  *   `language-*` class that highlighting replaces.
  * - `rehypeBasePath` runs last among the link plugins, so it prefixes the
@@ -186,6 +197,7 @@ function createProcessor(): Processor {
     .use(remarkParse)
     .use(remarkGfm)
     .use(remarkMath)
+    .use(remarkCallouts)
     .use(remarkWikiLinks, {
       link: resolveWikiLink,
       embed: resolveWikiEmbed,
@@ -195,9 +207,11 @@ function createProcessor(): Processor {
     .use(rehypeRaw)
     .use(rehypeSlug)
     .use(rehypeCollectHeadings)
+    .use(rehypeHeadingAnchors)
     .use(rehypeKatex)
     .use(rehypeInternalLinks, getUrlMap())
     .use(rehypeImages)
+    .use(rehypeMermaid)
     .use(rehypeCodeShell)
     .use(rehypeShiki, {
       themes: SHIKI_THEMES,

package/template/lib/navigation/sequence.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'vitest';
+import { getAdjacentPages } from './sequence';
+import { getSite } from '../site';
+import { extractAllPaths, filterHiddenItems } from './builder';
+
+/** The reading order, as the sidebar presents it. */
+function order(): string[] {
+  return extractAllPaths(filterHiddenItems(getSite().navigation));
+}
+
+describe('getAdjacentPages', () => {
+  // Written against however many pages there are: a scaffolded project starts
+  // with two, and indexing past them would fail there rather than here.
+  it('follows the order the sidebar shows', () => {
+    const sequence = order();
+
+    for (let i = 0; i < sequence.length; i++) {
+      const { previous, next } = getAdjacentPages(sequence[i]);
+
+      if (i > 0) expect(previous?.url).toContain(sequence[i - 1]);
+      if (i < sequence.length - 1) expect(next?.url).toContain(sequence[i + 1]);
+    }
+  });
+
+  it('gives the first page no predecessor', () => {
+    expect(getAdjacentPages(order()[0]).previous).toBeNull();
+  });
+
+  it('gives the last page no successor', () => {
+    const sequence = order();
+
+    expect(getAdjacentPages(sequence[sequence.length - 1]).next).toBeNull();
+  });
+
+  it('titles each neighbour', () => {
+    const sequence = order();
+    // Skipped rather than failed on a one-page wiki, which has no neighbours
+    // to title.
+    if (sequence.length < 2) return;
+
+    const { next } = getAdjacentPages(sequence[0]);
+
+    expect(next?.title).toBeTruthy();
+    expect(next?.title).not.toBe(next?.url);
+  });
+
+  // Stepping through a guide should not land on a page deliberately kept out
+  // of the sidebar.
+  it('leaves hidden pages out of the sequence', () => {
+    const { hiddenPaths } = getSite();
+    const sequence = order();
+
+    for (const hidden of hiddenPaths) {
+      expect(sequence).not.toContain(hidden);
+    }
+  });
+
+  it('offers nothing for a page outside the sequence', () => {
+    expect(getAdjacentPages('no/such/page')).toEqual({ previous: null, next: null });
+  });
+
+  // Every URL it produces is the trailing-slash form the export serves, or the
+  // links here would redirect like the ones fixed elsewhere.
+  it('emits URLs in the form the export serves', () => {
+    for (const path of order()) {
+      const { previous, next } = getAdjacentPages(path);
+
+      for (const page of [previous, next]) {
+        if (page) expect(page.url).toMatch(/^\/.*\/$/);
+      }
+    }
+  });
+});

package/template/lib/navigation/sequence.ts

@@ -0,0 +1,100 @@
+import { getSite } from '../site';
+import { extractAllPaths, filterHiddenItems } from './builder';
+import { docPathToUrl } from './url';
+import { getDoc } from '../content/registry';
+import { cached } from '../cache';
+
+/**
+ * The order pages are meant to be read in.
+ *
+ * The sidebar already answers this: sections come from the content tree, order
+ * from `_meta.json` and frontmatter, and reading it top to bottom is how a
+ * reader works through a guide. Flattening that same tree gives the sequence,
+ * so the two can never disagree — a separate ordering would be one more thing
+ * to keep in step.
+ *
+ * Server-only.
+ */
+
+/** A page next to another in reading order. */
+export interface AdjacentPage {
+  /** Display title */
+  title: string;
+  /** Href, in the site's configured URL form */
+  url: string;
+}
+
+/** What comes before and after a page. */
+export interface Adjacent {
+  previous: AdjacentPage | null;
+  next: AdjacentPage | null;
+}
+
+let memo: string[] | null = null;
+
+/**
+ * Every page in reading order, hidden ones excluded.
+ *
+ * Hidden pages are reachable by direct link but are not part of the sequence:
+ * stepping through a guide should not land on something deliberately unlisted.
+ *
+ * @returns Content paths, in the order the sidebar shows them
+ *
+ * @example
+ * ```typescript
+ * getReadingOrder()[0]; // the page a reader starts at
+ * ```
+ */
+export function getReadingOrder(): string[] {
+  const hit = cached(memo);
+  if (hit) return hit;
+
+  const { navigation } = getSite();
+
+  // Sections that only group pages carry no path of their own and drop out
+  // here, leaving just the readable pages.
+  memo = extractAllPaths(filterHiddenItems(navigation));
+  return memo;
+}
+
+/**
+ * Finds the pages either side of one in reading order.
+ *
+ * @param path - Content path of the current page
+ * @returns The neighbours, each null at the ends of the sequence
+ *
+ * @example
+ * ```typescript
+ * const { previous, next } = getAdjacentPages('getting-started/installation');
+ * next?.title; // 'Your First Wiki'
+ * ```
+ */
+export function getAdjacentPages(path: string): Adjacent {
+  const sequence = getReadingOrder();
+  const index = sequence.indexOf(path);
+
+  // A hidden page, or one reached by a URL that navigation does not cover, has
+  // no place in the sequence and so no neighbours to offer.
+  if (index === -1) return { previous: null, next: null };
+
+  return {
+    previous: toAdjacent(sequence[index - 1]),
+    next: toAdjacent(sequence[index + 1]),
+  };
+}
+
+/**
+ * Resolves a content path to the title and href a link needs.
+ *
+ * @param path - Content path, or undefined at either end of the sequence
+ * @returns The page, or null when there is none
+ */
+function toAdjacent(path: string | undefined): AdjacentPage | null {
+  if (!path) return null;
+
+  const { urlMap } = getSite();
+  const url = docPathToUrl(urlMap, path);
+  if (!url) return null;
+
+  return { title: getDoc(path)?.title ?? path, url: `/${url}/` };
+}