@docspack/sheaf-astro 0.0.1 → 0.3.0

package/README.md

@@ -17,17 +17,47 @@ const { html, headings } = await renderPage(page);
 `.md` file in `src/pages`. Your Markdown configuration keeps applying, and a document reaches
 a reader through one pipeline whichever route served it.
 
+A site that is not Astro should use [`@docspack/sheaf-html`](../sheaf-html) instead: the same
+API on a plain unified pipeline, without Astro's renderer and its dependencies.
+
 ## The part that matters
 
 A table of contents is built from the graph's heading slugs; the anchors it links to are the
 `id`s this renderer stamps. When those disagree the failure is silent — the browser scrolls to
 the top instead of erroring. This package asserts they agree for every page it renders.
 
+## Stability
+
+Sheaf's packages are `0.x` and release together, as one version (see the repository's
+*Releasing* section). Until 1.0, a breaking change to anything listed as stable below lands only in
+a minor release, and its changeset says **Breaking** and what to change. A patch release never
+breaks.
+
+**Stable:** `createPageRenderer`, `createMarkdownRenderer`, the `RenderedPage` shape, and the
+rule that a heading's `id` is the graph's slug for it. **Not yet stable:** the `links` option.
+
 ## Options
 
 | | |
 | --- | --- |
 | `syntaxHighlight` | `false`, `"shiki"` or `"prism"`. Turn it off if your site paints its own code blocks. |
+| `shikiConfig` | Passed to Astro's Shiki integration: a theme, languages, transformers. |
 | `gfm` | GitHub-flavoured Markdown. On by default. |
+| `remarkPlugins` | Run over the parsed page. Pass `sheafDirectives` from `@docspack/sheaf-emit` here for `:::` blocks, in place of `remark-directive`. |
+| `rehypePlugins` | Run over the HTML tree, after heading ids are set. |
+| `links` | `{ graph, target, resolve? }`. Rewrites links between pages to `target(page, "site")`, fragment checked; other relative paths go to `resolve`. A broken link fails the render. |
+
+```ts
+const render = createPageRenderer({
+  links: {
+    graph,
+    target: (page) => `/docs/${page.slug}`,
+    resolve: (path) => `https://github.com/acme/repo/blob/main/docs/${path}`,
+  },
+});
+```
+
+`createMarkdownRenderer(options)` returns the same processor for Markdown that is not a page;
+pass the page as a second argument when the Markdown is part of one, so its links resolve from it.
 
 MIT © docspack

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { createPageRenderer, type PageRenderer, type RenderedPage, type RendererOptions, } from "./render.js";
+export { createMarkdownRenderer, createPageRenderer, type PageRenderer, type RenderedPage, type RendererOptions, type SourceRenderer, } from "./render.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { createPageRenderer, } from "./render.js";
+export { createMarkdownRenderer, createPageRenderer, } from "./render.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,GAInB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,kBAAkB,GAKnB,MAAM,aAAa,CAAC"}

package/dist/render.d.ts

@@ -1,4 +1,5 @@
-import type { Heading, Page } from "@docspack/sheaf";
+import { type RehypePlugins, type RemarkPlugins, type ShikiConfig } from "@astrojs/markdown-remark";
+import { type ContentGraph, type Heading, type LinkOptions, type Page } from "@docspack/sheaf";
 /**
  * Rendering a graph's pages with Astro's own Markdown pipeline.
  *
@@ -26,18 +27,71 @@ export interface RenderedPage {
 /** Options passed through to Astro's processor. */
 export interface RendererOptions {
     /**
-     * Astro highlights code by default. A site that paints its own code-block style should turn
-     * this off, or it ships a second theme's colours over the top of its own.
+     * Astro highlights code by default, in its own theme's colours.
+     *
+     * A site with a code-block palette of its own has a better option than turning this off:
+     * Shiki takes a theme whose colours are arbitrary CSS strings, `var(--…)` included, so the
+     * host can hand it the same custom properties the rest of the page reads. See `shikiConfig`.
      */
     readonly syntaxHighlight?: false | "shiki" | "prism";
+    /** Shiki's configuration, including the theme. Only read when `syntaxHighlight` is Shiki. */
+    readonly shikiConfig?: ShikiConfig;
     readonly gfm?: boolean;
+    /**
+     * Rehype plugins to run over the rendered tree.
+     *
+     * Passed through rather than curated here, because what a document's HTML needs is the
+     * host's decision — an anchor on every heading, a `tabindex` on a code block the host's CSS
+     * made scrollable. This package binds to the host's renderer; it does not have opinions
+     * about the host's markup.
+     *
+     * These run **after** heading ids exist. Astro stamps ids last, so a host plugin that wanted
+     * to work with one — the anchor case, which is most of why a docs site reaches for this —
+     * saw `undefined` and silently did nothing. This package exists for that seam, so it runs
+     * Astro's own `rehypeHeadingIds` first. Astro runs it again at the end and it is idempotent:
+     * an id already set is left alone.
+     */
+    readonly rehypePlugins?: RehypePlugins;
+    /**
+     * Remark plugins to run over the parsed document, before it becomes HTML.
+     *
+     * This is the seam a `:::` block needs, and the reason it is here rather than left to the
+     * host's `astro.config`: the graph's pages are rendered by *this* processor, so a plugin
+     * configured for `src/pages` never sees them. Pass `sheafDirectives` from
+     * `@docspack/sheaf-emit` here rather than `remark-directive`: it is the vocabulary that side
+     * parses with, so a block that one half understands and the other reads as literal text — or
+     * a `15:16:24` one half keeps and the other drops — cannot happen.
+     */
+    readonly remarkPlugins?: RemarkPlugins;
+    /**
+     * Rewrites relative links between pages — `./TOKENS.md#colors` — to `target(page, "site")`,
+     * fragment kept and checked against the target's headings, and any other relative path through
+     * `resolve`. A broken fragment or an unresolvable path fails the render, naming the page.
+     *
+     * Applies to pages only: Markdown rendered without a page has nothing to be relative to.
+     */
+    readonly links?: LinkOptions & {
+        readonly graph: ContentGraph;
+    };
 }
 export type PageRenderer = (page: Page) => Promise<RenderedPage>;
 /**
- * Builds one processor and returns a function that renders pages with it.
+ * Renders Markdown. Given the page it belongs to — a page's `content`, or a part of it — its
+ * relative links resolve from that page and its frontmatter reaches the plugins.
+ */
+export type SourceRenderer = (markdown: string, page?: Page) => Promise<RenderedPage>;
+/**
+ * Builds one processor and returns a function that renders Markdown with it.
+ *
+ * Not every piece of Markdown a documentation site renders is a page. An OpenAPI operation's
+ * `description` is Markdown, and so is a frontmatter lede; both have to go through *this*
+ * processor rather than a second one, or the site renders two dialects — a backtick that becomes a
+ * code chip on one route and stays a backtick on another.
  *
- * Building a processor compiles a plugin pipeline, which is slow enough that doing it per page
+ * Building a processor compiles a plugin pipeline, which is slow enough that doing it per document
  * is noticeable on a corpus of any size — so it is built once, lazily, and shared.
  */
+export declare function createMarkdownRenderer(options?: RendererOptions): SourceRenderer;
+/** The same processor, for the graph's pages. */
 export declare function createPageRenderer(options?: RendererOptions): PageRenderer;
 //# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;CACvC;AAED,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,OAAO,CAAC;IACrD,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAEjE;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,eAAoB,GAAG,YAAY,CAoB9E"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,aAAa,EAElB,KAAK,WAAW,EACjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,OAAO,EACZ,KAAK,WAAW,EAEhB,KAAK,IAAI,EACV,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;CACvC;AAED,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,OAAO,CAAC;IACrD,6FAA6F;IAC7F,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC;;;;;;;;;OASG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG;QAAE,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAA;KAAE,CAAC;CACjE;AAiCD,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAEjE;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,IAAI,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAEtF;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,eAAoB,GAAG,cAAc,CA4BpF;AAED,iDAAiD;AACjD,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,eAAoB,GAAG,YAAY,CAK9E"}

package/dist/render.js

@@ -1,11 +1,38 @@
-import { createMarkdownProcessor } from "@astrojs/markdown-remark";
+import { createMarkdownProcessor, rehypeHeadingIds, } from "@astrojs/markdown-remark";
+import { linkHref, } from "@docspack/sheaf";
 /**
- * Builds one processor and returns a function that renders pages with it.
+ * The remark side of `links`. The processor is shared by every page, so the page being rendered
+ * arrives the way Astro hands any document's metadata to a plugin: in its frontmatter, where
+ * `render` puts the page's slug.
+ */
+function rewritePageLinks(links) {
+    return () => (tree, file) => {
+        const slug = file.data.astro?.frontmatter?.slug;
+        const from = links.graph.pages.find((page) => page.slug === slug);
+        if (from === undefined)
+            return;
+        const visit = (node) => {
+            if ((node.type === "link" || node.type === "definition") && node.url) {
+                node.url = linkHref(links.graph, from, node.url, links, "site");
+            }
+            for (const child of node.children ?? [])
+                visit(child);
+        };
+        visit(tree);
+    };
+}
+/**
+ * Builds one processor and returns a function that renders Markdown with it.
+ *
+ * Not every piece of Markdown a documentation site renders is a page. An OpenAPI operation's
+ * `description` is Markdown, and so is a frontmatter lede; both have to go through *this*
+ * processor rather than a second one, or the site renders two dialects — a backtick that becomes a
+ * code chip on one route and stays a backtick on another.
  *
- * Building a processor compiles a plugin pipeline, which is slow enough that doing it per page
+ * Building a processor compiles a plugin pipeline, which is slow enough that doing it per document
  * is noticeable on a corpus of any size — so it is built once, lazily, and shared.
  */
-export function createPageRenderer(options = {}) {
+export function createMarkdownRenderer(options = {}) {
     let pending;
     const renderer = () => {
         pending ??= createMarkdownProcessor({
@@ -13,14 +40,27 @@ export function createPageRenderer(options = {}) {
             ...(options.syntaxHighlight === undefined
                 ? {}
                 : { syntaxHighlight: options.syntaxHighlight }),
+            remarkPlugins: [
+                ...(options.remarkPlugins ?? []),
+                ...(options.links === undefined ? [] : [rewritePageLinks(options.links)]),
+            ],
+            ...(options.rehypePlugins === undefined
+                ? {}
+                : { rehypePlugins: [rehypeHeadingIds, ...options.rehypePlugins] }),
+            ...(options.shikiConfig === undefined ? {} : { shikiConfig: options.shikiConfig }),
         });
         return pending;
     };
-    return async (page) => {
-        // `page.content` rather than `page.body`: the shell renders the title itself, and a second
-        // `<h1>` from the body would be a duplicate in the document outline.
-        const { code, metadata } = await (await renderer()).render(page.content);
+    return async (markdown, page) => {
+        const { code, metadata } = await (await renderer()).render(markdown, page === undefined ? undefined : { frontmatter: { ...page.frontmatter, slug: page.slug } });
         return { html: code, headings: metadata.headings };
     };
 }
+/** The same processor, for the graph's pages. */
+export function createPageRenderer(options = {}) {
+    const render = createMarkdownRenderer(options);
+    // `page.content` rather than `page.body`: the shell renders the title itself, and a second `<h1>`
+    // from the body would be a duplicate in the document outline.
+    return (page) => render(page.content, page);
+}
 //# sourceMappingURL=render.js.map

package/dist/render.js.map

@@ -1 +1 @@
-{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAyB,MAAM,0BAA0B,CAAC;AAyC1F;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAA2B,EAAE;IAC9D,IAAI,OAA8C,CAAC;IAEnD,MAAM,QAAQ,GAAG,GAA8B,EAAE;QAC/C,OAAO,KAAK,uBAAuB,CAAC;YAClC,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,IAAI;YACxB,GAAG,CAAC,OAAO,CAAC,eAAe,KAAK,SAAS;gBACvC,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,eAAe,EAAE,CAAC;SAClD,CAAC,CAAC;QACH,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC;IAEF,OAAO,KAAK,EAAE,IAAI,EAAE,EAAE;QACpB,2FAA2F;QAC3F,qEAAqE;QACrE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC,MAAM,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAEzE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC;IACrD,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docspack/sheaf-astro",
-  "version": "0.0.1",
+  "version": "0.3.0",
   "description": "Renders a Sheaf content graph with Astro's own Markdown pipeline, so a docs site and its agent index come from one parse.",
   "license": "MIT",
   "type": "module",
@@ -28,13 +28,13 @@
   },
   "dependencies": {
     "@astrojs/markdown-remark": "7.2.0",
-    "@docspack/sheaf": "^0.0.1"
+    "@docspack/sheaf": "^0.3.0"
   },
   "devDependencies": {
+    "@docspack/config": "0.1.0",
     "@types/node": "26.2.0",
     "typescript": "6.0.3",
-    "vitest": "4.1.10",
-    "@docspack/config": "0.1.0"
+    "vitest": "4.1.10"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -1,6 +1,8 @@
 export {
+  createMarkdownRenderer,
   createPageRenderer,
   type PageRenderer,
   type RenderedPage,
   type RendererOptions,
+  type SourceRenderer,
 } from "./render.js";

package/src/render.ts

@@ -1,5 +1,18 @@
-import { createMarkdownProcessor, type MarkdownRenderer } from "@astrojs/markdown-remark";
-import type { Heading, Page } from "@docspack/sheaf";
+import {
+  createMarkdownProcessor,
+  type MarkdownRenderer,
+  type RehypePlugins,
+  type RemarkPlugins,
+  rehypeHeadingIds,
+  type ShikiConfig,
+} from "@astrojs/markdown-remark";
+import {
+  type ContentGraph,
+  type Heading,
+  type LinkOptions,
+  linkHref,
+  type Page,
+} from "@docspack/sheaf";
 
 /**
  * Rendering a graph's pages with Astro's own Markdown pipeline.
@@ -30,22 +43,103 @@ export interface RenderedPage {
 /** Options passed through to Astro's processor. */
 export interface RendererOptions {
   /**
-   * Astro highlights code by default. A site that paints its own code-block style should turn
-   * this off, or it ships a second theme's colours over the top of its own.
+   * Astro highlights code by default, in its own theme's colours.
+   *
+   * A site with a code-block palette of its own has a better option than turning this off:
+   * Shiki takes a theme whose colours are arbitrary CSS strings, `var(--…)` included, so the
+   * host can hand it the same custom properties the rest of the page reads. See `shikiConfig`.
    */
   readonly syntaxHighlight?: false | "shiki" | "prism";
+  /** Shiki's configuration, including the theme. Only read when `syntaxHighlight` is Shiki. */
+  readonly shikiConfig?: ShikiConfig;
   readonly gfm?: boolean;
+  /**
+   * Rehype plugins to run over the rendered tree.
+   *
+   * Passed through rather than curated here, because what a document's HTML needs is the
+   * host's decision — an anchor on every heading, a `tabindex` on a code block the host's CSS
+   * made scrollable. This package binds to the host's renderer; it does not have opinions
+   * about the host's markup.
+   *
+   * These run **after** heading ids exist. Astro stamps ids last, so a host plugin that wanted
+   * to work with one — the anchor case, which is most of why a docs site reaches for this —
+   * saw `undefined` and silently did nothing. This package exists for that seam, so it runs
+   * Astro's own `rehypeHeadingIds` first. Astro runs it again at the end and it is idempotent:
+   * an id already set is left alone.
+   */
+  readonly rehypePlugins?: RehypePlugins;
+  /**
+   * Remark plugins to run over the parsed document, before it becomes HTML.
+   *
+   * This is the seam a `:::` block needs, and the reason it is here rather than left to the
+   * host's `astro.config`: the graph's pages are rendered by *this* processor, so a plugin
+   * configured for `src/pages` never sees them. Pass `sheafDirectives` from
+   * `@docspack/sheaf-emit` here rather than `remark-directive`: it is the vocabulary that side
+   * parses with, so a block that one half understands and the other reads as literal text — or
+   * a `15:16:24` one half keeps and the other drops — cannot happen.
+   */
+  readonly remarkPlugins?: RemarkPlugins;
+  /**
+   * Rewrites relative links between pages — `./TOKENS.md#colors` — to `target(page, "site")`,
+   * fragment kept and checked against the target's headings, and any other relative path through
+   * `resolve`. A broken fragment or an unresolvable path fails the render, naming the page.
+   *
+   * Applies to pages only: Markdown rendered without a page has nothing to be relative to.
+   */
+  readonly links?: LinkOptions & { readonly graph: ContentGraph };
+}
+
+interface MdastNode {
+  type: string;
+  url?: string;
+  children?: MdastNode[];
+}
+
+interface AstroFile {
+  readonly data: { readonly astro?: { readonly frontmatter?: Record<string, unknown> } };
+}
+
+/**
+ * The remark side of `links`. The processor is shared by every page, so the page being rendered
+ * arrives the way Astro hands any document's metadata to a plugin: in its frontmatter, where
+ * `render` puts the page's slug.
+ */
+function rewritePageLinks(links: NonNullable<RendererOptions["links"]>) {
+  return () => (tree: MdastNode, file: AstroFile) => {
+    const slug = file.data.astro?.frontmatter?.slug;
+    const from = links.graph.pages.find((page) => page.slug === slug);
+    if (from === undefined) return;
+
+    const visit = (node: MdastNode) => {
+      if ((node.type === "link" || node.type === "definition") && node.url) {
+        node.url = linkHref(links.graph, from, node.url, links, "site");
+      }
+      for (const child of node.children ?? []) visit(child);
+    };
+    visit(tree);
+  };
 }
 
 export type PageRenderer = (page: Page) => Promise<RenderedPage>;
 
 /**
- * Builds one processor and returns a function that renders pages with it.
+ * Renders Markdown. Given the page it belongs to — a page's `content`, or a part of it — its
+ * relative links resolve from that page and its frontmatter reaches the plugins.
+ */
+export type SourceRenderer = (markdown: string, page?: Page) => Promise<RenderedPage>;
+
+/**
+ * Builds one processor and returns a function that renders Markdown with it.
  *
- * Building a processor compiles a plugin pipeline, which is slow enough that doing it per page
+ * Not every piece of Markdown a documentation site renders is a page. An OpenAPI operation's
+ * `description` is Markdown, and so is a frontmatter lede; both have to go through *this*
+ * processor rather than a second one, or the site renders two dialects — a backtick that becomes a
+ * code chip on one route and stays a backtick on another.
+ *
+ * Building a processor compiles a plugin pipeline, which is slow enough that doing it per document
  * is noticeable on a corpus of any size — so it is built once, lazily, and shared.
  */
-export function createPageRenderer(options: RendererOptions = {}): PageRenderer {
+export function createMarkdownRenderer(options: RendererOptions = {}): SourceRenderer {
   let pending: Promise<MarkdownRenderer> | undefined;
 
   const renderer = (): Promise<MarkdownRenderer> => {
@@ -54,15 +148,31 @@ export function createPageRenderer(options: RendererOptions = {}): PageRenderer
       ...(options.syntaxHighlight === undefined
         ? {}
         : { syntaxHighlight: options.syntaxHighlight }),
+      remarkPlugins: [
+        ...(options.remarkPlugins ?? []),
+        ...(options.links === undefined ? [] : [rewritePageLinks(options.links)]),
+      ],
+      ...(options.rehypePlugins === undefined
+        ? {}
+        : { rehypePlugins: [rehypeHeadingIds, ...options.rehypePlugins] }),
+      ...(options.shikiConfig === undefined ? {} : { shikiConfig: options.shikiConfig }),
     });
     return pending;
   };
 
-  return async (page) => {
-    // `page.content` rather than `page.body`: the shell renders the title itself, and a second
-    // `<h1>` from the body would be a duplicate in the document outline.
-    const { code, metadata } = await (await renderer()).render(page.content);
-
+  return async (markdown, page) => {
+    const { code, metadata } = await (await renderer()).render(
+      markdown,
+      page === undefined ? undefined : { frontmatter: { ...page.frontmatter, slug: page.slug } },
+    );
     return { html: code, headings: metadata.headings };
   };
 }
+
+/** The same processor, for the graph's pages. */
+export function createPageRenderer(options: RendererOptions = {}): PageRenderer {
+  const render = createMarkdownRenderer(options);
+  // `page.content` rather than `page.body`: the shell renders the title itself, and a second `<h1>`
+  // from the body would be a duplicate in the document outline.
+  return (page) => render(page.content, page);
+}