@docspack/sheaf-astro 0.0.1 → 0.1.0

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,3 +1,4 @@
+import { type RehypePlugins, type RemarkPlugins, type ShikiConfig } from "@astrojs/markdown-remark";
 import type { Heading, Page } from "@docspack/sheaf";
 /**
  * Rendering a graph's pages with Astro's own Markdown pipeline.
@@ -26,18 +27,57 @@ 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. `remark-directive` belongs on both sides —
+     * `@docspack/sheaf-emit` parses with it too — because a block that one half understands and
+     * the other reads as literal text is a page and a chunk describing different documentation.
+     */
+    readonly remarkPlugins?: RemarkPlugins;
 }
 export type PageRenderer = (page: Page) => Promise<RenderedPage>;
+/** Renders Markdown that is not a page. */
+export type SourceRenderer = (markdown: string) => Promise<RenderedPage>;
 /**
- * Builds one processor and returns a function that renders pages with it.
+ * 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,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;;;;;;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;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;CACxC;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAEjE,2CAA2C;AAC3C,MAAM,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAEzE;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,eAAoB,GAAG,cAAc,CAsBpF;AAED,iDAAiD;AACjD,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,eAAoB,GAAG,YAAY,CAK9E"}

package/dist/render.js

@@ -1,11 +1,16 @@
-import { createMarkdownProcessor } from "@astrojs/markdown-remark";
+import { createMarkdownProcessor, rehypeHeadingIds, } from "@astrojs/markdown-remark";
 /**
- * Builds one processor and returns a function that renders pages with it.
+ * 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 = {}) {
+export function createMarkdownRenderer(options = {}) {
     let pending;
     const renderer = () => {
         pending ??= createMarkdownProcessor({
@@ -13,14 +18,24 @@ export function createPageRenderer(options = {}) {
             ...(options.syntaxHighlight === undefined
                 ? {}
                 : { syntaxHighlight: options.syntaxHighlight }),
+            ...(options.remarkPlugins === undefined ? {} : { remarkPlugins: options.remarkPlugins }),
+            ...(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) => {
+        const { code, metadata } = await (await renderer()).render(markdown);
         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);
+}
 //# 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":"AAAA,OAAO,EACL,uBAAuB,EAIvB,gBAAgB,GAEjB,MAAM,0BAA0B,CAAC;AA0ElC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CAAC,UAA2B,EAAE;IAClE,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;YACjD,GAAG,CAAC,OAAO,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC;YACxF,GAAG,CAAC,OAAO,CAAC,aAAa,KAAK,SAAS;gBACrC,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,gBAAgB,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;YACpE,GAAG,CAAC,OAAO,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC;SACnF,CAAC,CAAC;QACH,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC;IAEF,OAAO,KAAK,EAAE,QAAQ,EAAE,EAAE;QACxB,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC,MAAM,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACrE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC;IACrD,CAAC,CAAC;AACJ,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,kBAAkB,CAAC,UAA2B,EAAE;IAC9D,MAAM,MAAM,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAC/C,kGAAkG;IAClG,8DAA8D;IAC9D,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACxC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docspack/sheaf-astro",
-  "version": "0.0.1",
+  "version": "0.1.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.1.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,4 +1,11 @@
-import { createMarkdownProcessor, type MarkdownRenderer } from "@astrojs/markdown-remark";
+import {
+  createMarkdownProcessor,
+  type MarkdownRenderer,
+  type RehypePlugins,
+  type RemarkPlugins,
+  rehypeHeadingIds,
+  type ShikiConfig,
+} from "@astrojs/markdown-remark";
 import type { Heading, Page } from "@docspack/sheaf";
 
 /**
@@ -30,22 +37,60 @@ 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. `remark-directive` belongs on both sides —
+   * `@docspack/sheaf-emit` parses with it too — because a block that one half understands and
+   * the other reads as literal text is a page and a chunk describing different documentation.
+   */
+  readonly remarkPlugins?: RemarkPlugins;
 }
 
 export type PageRenderer = (page: Page) => Promise<RenderedPage>;
 
+/** Renders Markdown that is not a page. */
+export type SourceRenderer = (markdown: string) => Promise<RenderedPage>;
+
 /**
- * Builds one processor and returns a function that renders pages with it.
+ * 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: RendererOptions = {}): PageRenderer {
+export function createMarkdownRenderer(options: RendererOptions = {}): SourceRenderer {
   let pending: Promise<MarkdownRenderer> | undefined;
 
   const renderer = (): Promise<MarkdownRenderer> => {
@@ -54,15 +99,25 @@ export function createPageRenderer(options: RendererOptions = {}): PageRenderer
       ...(options.syntaxHighlight === undefined
         ? {}
         : { syntaxHighlight: options.syntaxHighlight }),
+      ...(options.remarkPlugins === undefined ? {} : { remarkPlugins: options.remarkPlugins }),
+      ...(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) => {
+    const { code, metadata } = await (await renderer()).render(markdown);
     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);
+}