@docspack/sheaf-astro 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 docspack contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# @docspack/sheaf-astro
+
+Renders a [Sheaf](../sheaf) content graph with Astro's own Markdown pipeline.
+
+```ts
+import { graphFromSources } from "@docspack/sheaf";
+import { createPageRenderer } from "@docspack/sheaf-astro";
+
+const renderPage = createPageRenderer({ syntaxHighlight: false });
+
+const { html, headings } = await renderPage(page);
+```
+
+## Why a binding rather than a renderer
+
+`createPageRenderer` wraps `@astrojs/markdown-remark` — the same processor Astro uses for a
+`.md` file in `src/pages`. Your Markdown configuration keeps applying, and a document reaches
+a reader through one pipeline whichever route served it.
+
+## 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.
+
+## Options
+
+| | |
+| --- | --- |
+| `syntaxHighlight` | `false`, `"shiki"` or `"prism"`. Turn it off if your site paints its own code blocks. |
+| `gfm` | GitHub-flavoured Markdown. On by default. |
+
+MIT © docspack

package/dist/index.d.ts

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

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

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

package/dist/index.js.map

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

package/dist/render.d.ts

@@ -0,0 +1,43 @@
+import type { Heading, Page } from "@docspack/sheaf";
+/**
+ * Rendering a graph's pages with Astro's own Markdown pipeline.
+ *
+ * This is the layer that owns rendering, and it is deliberately the *host's* renderer rather
+ * than one of ours: it is the same processor that renders a `.md` file in `src/pages`, so a
+ * document reaches a reader through one pipeline no matter which route served it. Sheaf's
+ * graph carries no HTML precisely so this choice stays the host's.
+ *
+ * The seam this package is responsible for is heading ids. The graph's slugs drive a table of
+ * contents; the ids in this HTML are what a browser scrolls to. They are produced by different
+ * code, and a mismatch fails silently — a bad fragment scrolls to the top rather than erroring.
+ * `tests/render.test.ts` asserts they agree for the whole corpus.
+ */
+export interface RenderedPage {
+    readonly html: string;
+    /**
+     * The headings the renderer found, which is what actually got an `id`.
+     *
+     * Prefer the graph's `page.headings` for a table of contents — it is available without
+     * rendering. This is here so a caller can assert the two agree, and so a host that wants the
+     * renderer's typographic text (`It’s` rather than `It's`) can reach it.
+     */
+    readonly headings: readonly Heading[];
+}
+/** 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.
+     */
+    readonly syntaxHighlight?: false | "shiki" | "prism";
+    readonly gfm?: boolean;
+}
+export type PageRenderer = (page: Page) => Promise<RenderedPage>;
+/**
+ * Builds one processor and returns a function that renders pages with it.
+ *
+ * Building a processor compiles a plugin pipeline, which is slow enough that doing it per page
+ * is noticeable on a corpus of any size — so it is built once, lazily, and shared.
+ */
+export declare function createPageRenderer(options?: RendererOptions): PageRenderer;
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +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"}

package/dist/render.js

@@ -0,0 +1,26 @@
+import { createMarkdownProcessor } from "@astrojs/markdown-remark";
+/**
+ * Builds one processor and returns a function that renders pages with it.
+ *
+ * Building a processor compiles a plugin pipeline, which is slow enough that doing it per page
+ * is noticeable on a corpus of any size — so it is built once, lazily, and shared.
+ */
+export function createPageRenderer(options = {}) {
+    let pending;
+    const renderer = () => {
+        pending ??= createMarkdownProcessor({
+            gfm: options.gfm ?? true,
+            ...(options.syntaxHighlight === undefined
+                ? {}
+                : { syntaxHighlight: options.syntaxHighlight }),
+        });
+        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 { html: code, headings: metadata.headings };
+    };
+}
+//# sourceMappingURL=render.js.map

package/dist/render.js.map

@@ -0,0 +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"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@docspack/sheaf-astro",
+  "version": "0.0.1",
+  "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",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/docspack/docspack.git",
+    "directory": "packages/sheaf-astro"
+  },
+  "dependencies": {
+    "@astrojs/markdown-remark": "7.2.0",
+    "@docspack/sheaf": "^0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "26.2.0",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10",
+    "@docspack/config": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "sheaf",
+    "docspack",
+    "astro",
+    "documentation",
+    "markdown"
+  ],
+  "homepage": "https://docspack.dev",
+  "bugs": "https://github.com/docspack/docspack/issues",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check-types": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
+    "test": "vitest run"
+  }
+}

package/src/index.ts

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

package/src/render.ts

@@ -0,0 +1,68 @@
+import { createMarkdownProcessor, type MarkdownRenderer } from "@astrojs/markdown-remark";
+import type { Heading, Page } from "@docspack/sheaf";
+
+/**
+ * Rendering a graph's pages with Astro's own Markdown pipeline.
+ *
+ * This is the layer that owns rendering, and it is deliberately the *host's* renderer rather
+ * than one of ours: it is the same processor that renders a `.md` file in `src/pages`, so a
+ * document reaches a reader through one pipeline no matter which route served it. Sheaf's
+ * graph carries no HTML precisely so this choice stays the host's.
+ *
+ * The seam this package is responsible for is heading ids. The graph's slugs drive a table of
+ * contents; the ids in this HTML are what a browser scrolls to. They are produced by different
+ * code, and a mismatch fails silently — a bad fragment scrolls to the top rather than erroring.
+ * `tests/render.test.ts` asserts they agree for the whole corpus.
+ */
+
+export interface RenderedPage {
+  readonly html: string;
+  /**
+   * The headings the renderer found, which is what actually got an `id`.
+   *
+   * Prefer the graph's `page.headings` for a table of contents — it is available without
+   * rendering. This is here so a caller can assert the two agree, and so a host that wants the
+   * renderer's typographic text (`It’s` rather than `It's`) can reach it.
+   */
+  readonly headings: readonly Heading[];
+}
+
+/** 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.
+   */
+  readonly syntaxHighlight?: false | "shiki" | "prism";
+  readonly gfm?: boolean;
+}
+
+export type PageRenderer = (page: Page) => Promise<RenderedPage>;
+
+/**
+ * Builds one processor and returns a function that renders pages with it.
+ *
+ * Building a processor compiles a plugin pipeline, which is slow enough that doing it per page
+ * is noticeable on a corpus of any size — so it is built once, lazily, and shared.
+ */
+export function createPageRenderer(options: RendererOptions = {}): PageRenderer {
+  let pending: Promise<MarkdownRenderer> | undefined;
+
+  const renderer = (): Promise<MarkdownRenderer> => {
+    pending ??= createMarkdownProcessor({
+      gfm: options.gfm ?? true,
+      ...(options.syntaxHighlight === undefined
+        ? {}
+        : { syntaxHighlight: options.syntaxHighlight }),
+    });
+    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 { html: code, headings: metadata.headings };
+  };
+}