create-eziwiki 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-eziwiki",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Scaffold a new eziwiki documentation site",
   "type": "module",
   "bin": {

package/template/app/[...slug]/page.tsx

@@ -3,7 +3,11 @@ import { PageTransition } from '@/components/markdown/PageTransition';
 import { TableOfContents } from '@/components/layout/TableOfContents';
 import { Backlinks } from '@/components/layout/Backlinks';
 import { LocalGraph } from '@/components/layout/LocalGraph';
+import { PageNavigation } from '@/components/layout/PageNavigation';
+import { MovedPage } from '@/components/layout/MovedPage';
 import { getBacklinks, getLocalGraph } from '@/lib/graph/build';
+import { getAdjacentPages } from '@/lib/navigation/sequence';
+import { getAliasMap, aliasUrl, resolveAliasUrl } from '@/lib/content/aliases';
 import { renderDoc } from '@/lib/markdown/render';
 import { getDoc, type ContentDoc } from '@/lib/content/registry';
 import { docPathToUrl, urlToDocPath } from '@/lib/navigation/url';
@@ -36,6 +40,25 @@ function resolveSlug(slug: string[]): { path: string; url: string } | null {
   return path ? { path, url } : null;
 }
 
+/**
+ * Resolves a slug that names a page's former address.
+ *
+ * Checked only after the live map misses, so a real page always wins over an
+ * alias — an alias shadowing a page is refused when the index is built, but
+ * order here makes the intent explicit.
+ *
+ * @param slug - Route segments captured by the catch-all route
+ * @returns The document that superseded the address, and its URL, or null
+ */
+function resolveMoved(slug: string[]): { path: string; url: string } | null {
+  const { urlMap } = getSite();
+  const path = resolveAliasUrl(slug.join('/'), urlMap.strategy);
+  if (!path) return null;
+
+  const url = docPathToUrl(urlMap, path);
+  return url ? { path, url } : null;
+}
+
 /**
  * Generates per-page metadata from the document's frontmatter.
  */
@@ -45,6 +68,21 @@ export async function generateMetadata({ params }: PageProps): Promise<Metadata>
   const doc = resolved ? getDoc(resolved.path) : undefined;
 
   if (!resolved || !doc) {
+    const moved = resolveMoved(params.slug);
+    const target = moved ? getDoc(moved.path) : undefined;
+
+    // A former address should not compete with the page it forwards to: it is
+    // kept out of the index, and points its canonical at the destination so any
+    // ranking the old URL earned transfers rather than being split.
+    if (moved && target) {
+      return {
+        title: target.title,
+        description: target.description || global.description,
+        alternates: { canonical: pageUrl(moved.url, global.baseUrl) },
+        robots: { index: false, follow: true },
+      };
+    }
+
     return { title: global.title, description: global.description };
   }
 
@@ -90,10 +128,18 @@ export async function generateMetadata({ params }: PageProps): Promise<Metadata>
 export async function generateStaticParams() {
   const { urlMap, docPaths } = getSite();
 
-  return docPaths.flatMap((path) => {
+  const pages = docPaths.flatMap((path) => {
     const url = docPathToUrl(urlMap, path);
     return url ? [{ slug: url.split('/') }] : [];
   });
+
+  // Former addresses are built too, each as a page that forwards. Without this
+  // there is nothing at the old URL for a static host to serve.
+  const moved = [...getAliasMap().keys()].map((alias) => ({
+    slug: aliasUrl(alias, urlMap.strategy).split('/'),
+  }));
+
+  return [...pages, ...moved];
 }
 
 /**
@@ -136,7 +182,14 @@ function ArticleSchema({ doc, url }: { doc: ContentDoc; url: string }) {
 export default async function ContentPage({ params }: PageProps) {
   const resolved = resolveSlug(params.slug);
 
-  if (!resolved) notFound();
+  if (!resolved) {
+    const moved = resolveMoved(params.slug);
+    const target = moved ? getDoc(moved.path) : undefined;
+
+    if (moved && target) return <MovedPage url={`/${moved.url}/`} title={target.title} />;
+
+    notFound();
+  }
 
   const doc = getDoc(resolved.path);
   const rendered = await renderDoc(resolved.path);
@@ -149,6 +202,7 @@ export default async function ContentPage({ params }: PageProps) {
         <article className="prose prose-slate min-w-0 max-w-none flex-1 dark:prose-invert">
           <ArticleSchema doc={doc} url={resolved.url} />
           <MarkdownContent html={rendered.html} />
+          <PageNavigation adjacent={getAdjacentPages(resolved.path)} />
           <Backlinks links={getBacklinks(resolved.path)} />
           <LocalGraph graph={getLocalGraph(resolved.path)} path={resolved.path} />
         </article>

package/template/components/layout/MovedPage.tsx

@@ -0,0 +1,45 @@
+import Link from 'next/link';
+import { asset } from '@/lib/basePath';
+
+/**
+ * Stands in for a page that has moved, and sends the reader on.
+ *
+ * A static export has no server to answer with a 301, so the redirect is a
+ * `meta refresh` in the document itself. Search engines treat that as a
+ * permanent move when the delay is zero, and the canonical link says the same
+ * thing again for anything that reads markup rather than following it.
+ *
+ * The visible text is not decoration. A reader whose browser blocks the refresh
+ * — or who arrives with scripting and meta refresh disabled — still needs a way
+ * through, so the link is real and focusable rather than a spinner.
+ *
+ * @param props - Component props
+ * @param props.url - Href of the page that superseded this address
+ * @param props.title - Title of that page
+ */
+export function MovedPage({ url, title }: { url: string; title: string }) {
+  return (
+    <>
+      <meta httpEquiv="refresh" content={`0; url=${asset(url)}`} />
+
+      <div className="mx-auto max-w-lg px-6 py-24 text-center">
+        <p className="text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400">
+          This page moved
+        </p>
+
+        <h1 className="mt-3 text-2xl font-semibold text-gray-900 dark:text-gray-100">{title}</h1>
+
+        <p className="mt-4 text-sm text-gray-600 dark:text-gray-400">
+          You are being taken there now. If nothing happens, follow the link.
+        </p>
+
+        <Link
+          href={url}
+          className="mt-6 inline-block rounded-md border border-gray-300 px-4 py-2 text-sm font-medium text-gray-900 no-underline transition-colors hover:bg-gray-50 dark:border-gray-700 dark:text-gray-100 dark:hover:bg-gray-800"
+        >
+          Continue to {title}
+        </Link>
+      </div>
+    </>
+  );
+}

package/template/components/layout/PageNavigation.tsx

@@ -0,0 +1,73 @@
+import Link from 'next/link';
+import { ChevronLeft, ChevronRight } from 'lucide-react';
+import type { Adjacent } from '@/lib/navigation/sequence';
+
+/**
+ * Links to the pages either side of this one in reading order.
+ *
+ * A guide is written to be read through, and until now the only way onwards was
+ * back to the sidebar to find where you had got to. The order is the sidebar's
+ * own, flattened, so the two cannot drift apart.
+ *
+ * `rel="prev"` and `rel="next"` say the same thing to a crawler, which is how a
+ * sequence of pages is declared to be one.
+ *
+ * @param props - Component props
+ * @param props.adjacent - Neighbours from `getAdjacentPages()`
+ */
+export function PageNavigation({ adjacent }: { adjacent: Adjacent }) {
+  const { previous, next } = adjacent;
+
+  // The first and last pages have one neighbour; a page outside the sequence
+  // has none, and gets nothing rather than an empty bar.
+  if (!previous && !next) return null;
+
+  return (
+    <nav
+      aria-label="Page navigation"
+      className="mt-12 flex items-stretch gap-4 border-t border-gray-200 pt-6 dark:border-gray-800"
+    >
+      {previous ? (
+        <Link
+          href={previous.url}
+          rel="prev"
+          className="group flex flex-1 items-center gap-3 rounded-lg border border-gray-200 p-4 no-underline transition-colors hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:hover:border-gray-700 dark:hover:bg-gray-800/50"
+        >
+          <ChevronLeft className="h-4 w-4 flex-shrink-0 text-gray-400 transition-transform group-hover:-translate-x-0.5" />
+          <span className="min-w-0">
+            <span className="block text-xs uppercase tracking-wide text-gray-500 dark:text-gray-400">
+              Previous
+            </span>
+            <span className="block truncate text-sm font-medium text-gray-900 dark:text-gray-100">
+              {previous.title}
+            </span>
+          </span>
+        </Link>
+      ) : (
+        // Holds the column so a lone "next" stays on the right, where it is
+        // when there is a pair.
+        <div className="flex-1" />
+      )}
+
+      {next ? (
+        <Link
+          href={next.url}
+          rel="next"
+          className="group flex flex-1 items-center justify-end gap-3 rounded-lg border border-gray-200 p-4 text-right no-underline transition-colors hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:hover:border-gray-700 dark:hover:bg-gray-800/50"
+        >
+          <span className="min-w-0">
+            <span className="block text-xs uppercase tracking-wide text-gray-500 dark:text-gray-400">
+              Next
+            </span>
+            <span className="block truncate text-sm font-medium text-gray-900 dark:text-gray-100">
+              {next.title}
+            </span>
+          </span>
+          <ChevronRight className="h-4 w-4 flex-shrink-0 text-gray-400 transition-transform group-hover:translate-x-0.5" />
+        </Link>
+      ) : (
+        <div className="flex-1" />
+      )}
+    </nav>
+  );
+}

package/template/lib/content/aliases.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest';
+import { getAliasMap, resolveAlias, aliasUrl, resolveAliasUrl } from './aliases';
+import { getContentRegistry } from './registry';
+
+describe('alias parsing', () => {
+  // An author moving one page writes one path; requiring a list would be a
+  // rule to remember for no gain.
+  it('accepts a single alias or a list', () => {
+    const { docs } = getContentRegistry();
+
+    for (const doc of docs) {
+      expect(Array.isArray(doc.aliases)).toBe(true);
+    }
+  });
+
+  it('leaves documents without aliases empty', () => {
+    const { byPath } = getContentRegistry();
+
+    expect(byPath.get('intro')?.aliases).toEqual([]);
+  });
+});
+
+describe('getAliasMap', () => {
+  it('maps a former path to the document that superseded it', () => {
+    const map = getAliasMap();
+
+    for (const [alias, target] of map) {
+      expect(alias).not.toBe(target);
+      expect(getContentRegistry().byPath.has(target)).toBe(true);
+    }
+  });
+
+  // An alias shadowing a live page would make that page unreachable, so it is
+  // a build error rather than something resolved by precedence.
+  it('never claims a path a page occupies', () => {
+    const { byPath } = getContentRegistry();
+
+    for (const alias of getAliasMap().keys()) {
+      expect(byPath.has(alias)).toBe(false);
+    }
+  });
+});
+
+describe('aliasUrl', () => {
+  it('is the path itself under the path strategy', () => {
+    expect(aliasUrl('guides/setup', 'path')).toBe('guides/setup');
+  });
+
+  // The old URL under `hash` was the digest of the old path, so reproducing it
+  // is what makes the address a reader still has keep working.
+  it('is the digest of the path under the hash strategy', () => {
+    const url = aliasUrl('guides/setup', 'hash');
+
+    expect(url).toMatch(/^[0-9a-f]{8}-[0-9a-f]{8}-[0-9a-f]{8}$/);
+    expect(aliasUrl('guides/setup', 'hash')).toBe(url);
+    expect(aliasUrl('guides/other', 'hash')).not.toBe(url);
+  });
+
+  it('tolerates surrounding slashes', () => {
+    expect(aliasUrl('/guides/setup/', 'path')).toBe('guides/setup');
+  });
+});
+
+describe('resolveAliasUrl', () => {
+  it('resolves a former URL back to the current document under both strategies', () => {
+    for (const [alias, target] of getAliasMap()) {
+      expect(resolveAliasUrl(aliasUrl(alias, 'path'), 'path')).toBe(target);
+      expect(resolveAliasUrl(aliasUrl(alias, 'hash'), 'hash')).toBe(target);
+    }
+  });
+
+  it('resolves nothing for an address no page ever had', () => {
+    expect(resolveAliasUrl('never/existed', 'path')).toBeNull();
+    expect(resolveAlias('never/existed')).toBeNull();
+  });
+});

package/template/lib/content/aliases.ts

@@ -0,0 +1,114 @@
+import { getContentRegistry } from './registry';
+import { cached } from '../cache';
+import { normalizeSlug, type UrlStrategy } from '../navigation/url';
+import { generatePathHash } from '../navigation/hash';
+
+/**
+ * Former locations of documents, and where they now live.
+ *
+ * URLs are derived from content paths, so moving `guides/setup.md` to
+ * `getting-started/setup.md` changes the published URL and every link, bookmark
+ * and search result pointing at the old one stops working. Wiki links survive
+ * the move — they resolve by name — but nothing arriving from outside does.
+ * Declaring the old path in frontmatter keeps it answering.
+ *
+ * Server-only: reads the content registry.
+ */
+
+/** Alias content path mapped to the document that superseded it. */
+export type AliasMap = Map<string, string>;
+
+let memo: AliasMap | null = null;
+
+/**
+ * Builds the alias index.
+ *
+ * Two kinds of clash are refused rather than resolved. An alias naming a real
+ * page would shadow it, making a live document unreachable; an alias claimed by
+ * two documents has no answer, and picking either would send readers somewhere
+ * arbitrary. Both are mistakes in the content, and both are cheaper to find at
+ * build time than as a wrong page in production.
+ *
+ * @returns Old path to current path
+ * @throws Error when an alias shadows a page or is claimed twice
+ *
+ * @example
+ * ```typescript
+ * getAliasMap().get('guides/setup'); // 'getting-started/setup'
+ * ```
+ */
+export function getAliasMap(): AliasMap {
+  const hit = cached(memo);
+  if (hit) return hit;
+
+  const { docs, byPath } = getContentRegistry();
+  const map: AliasMap = new Map();
+
+  for (const doc of docs) {
+    for (const alias of doc.aliases) {
+      if (byPath.has(alias)) {
+        throw new Error(
+          `Alias collision: '${alias}' in content/${doc.path}.md is also a page ` +
+            `(content/${alias}.md). An alias may only name a path no page occupies.`,
+        );
+      }
+
+      const claimed = map.get(alias);
+      if (claimed && claimed !== doc.path) {
+        throw new Error(
+          `Alias collision: '${alias}' is claimed by both content/${claimed}.md ` +
+            `and content/${doc.path}.md. Remove it from one of them.`,
+        );
+      }
+
+      map.set(alias, doc.path);
+    }
+  }
+
+  memo = map;
+  return memo;
+}
+
+/**
+ * Finds the document an old path now points to.
+ *
+ * @param path - Content path as it used to be written
+ * @returns The current content path, or null when nothing claims it
+ */
+export function resolveAlias(path: string): string | null {
+  return getAliasMap().get(path) ?? null;
+}
+
+/**
+ * The URL segment an alias answers on.
+ *
+ * Built with the same rule the live map uses, so the address a reader has
+ * really is the one that is served: under `path` the old content path, under
+ * `hash` the digest of it, which is exactly what the old URL was before the
+ * page moved.
+ *
+ * @param alias - Alias content path
+ * @param strategy - URL strategy in force
+ * @returns The segment, without leading or trailing slashes
+ */
+export function aliasUrl(alias: string, strategy: UrlStrategy): string {
+  const normalized = normalizeSlug(alias);
+  return strategy === 'hash' ? generatePathHash(normalized) : normalized;
+}
+
+/**
+ * Resolves a URL segment to the document that superseded it.
+ *
+ * @param url - URL segment as requested
+ * @param strategy - URL strategy in force
+ * @returns The current content path, or null when the segment is not an alias
+ */
+export function resolveAliasUrl(url: string, strategy: UrlStrategy): string | null {
+  const wanted = normalizeSlug(url);
+
+  for (const [alias, target] of getAliasMap()) {
+    if (aliasUrl(alias, strategy) === wanted) return target;
+  }
+
+  return null;
+}

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/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.');
+  });
+});