@docspack/sheaf-astro 0.1.0 → 0.4.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/render.d.ts

@@ -1,5 +1,5 @@
 import { type RehypePlugins, type RemarkPlugins, type ShikiConfig } from "@astrojs/markdown-remark";
-import type { Heading, Page } from "@docspack/sheaf";
+import { type ContentGraph, type Heading, type LinkOptions, type Page } from "@docspack/sheaf";
 /**
  * Rendering a graph's pages with Astro's own Markdown pipeline.
  *
@@ -57,15 +57,29 @@ export interface RendererOptions {
      *
      * 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.
+     * 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>;
-/** Renders Markdown that is not a page. */
-export type SourceRenderer = (markdown: string) => Promise<RenderedPage>;
+/**
+ * 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.
  *

package/dist/render.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"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;AA+CD,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,CA+BpF;AAED,iDAAiD;AACjD,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,eAAoB,GAAG,YAAY,CAK9E"}

package/dist/render.js

@@ -1,4 +1,38 @@
 import { createMarkdownProcessor, rehypeHeadingIds, } from "@astrojs/markdown-remark";
+import { linkHref, } from "@docspack/sheaf";
+/**
+ * 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.
+ *
+ * A broken link is recorded against that frontmatter object rather than thrown. Astro catches
+ * anything a plugin throws, logs it and rethrows it prefixed `Failed to parse Markdown file
+ * "undefined":` — a page here has no file URL, and giving it one would switch on Astro's image
+ * collection, which rewrites every `<img>`. `render` throws the recorded error once Astro returns,
+ * with the message `linkHref` wrote.
+ */
+function rewritePageLinks(links, failures) {
+    return () => (tree, file) => {
+        const frontmatter = file.data.astro?.frontmatter;
+        const slug = frontmatter?.slug;
+        const from = links.graph.pages.find((page) => page.slug === slug);
+        if (from === undefined || frontmatter === 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);
+        };
+        try {
+            visit(tree);
+        }
+        catch (error) {
+            failures.set(frontmatter, error);
+        }
+    };
+}
 /**
  * Builds one processor and returns a function that renders Markdown with it.
  *
@@ -12,13 +46,17 @@ import { createMarkdownProcessor, rehypeHeadingIds, } from "@astrojs/markdown-re
  */
 export function createMarkdownRenderer(options = {}) {
     let pending;
+    const failures = new WeakMap();
     const renderer = () => {
         pending ??= createMarkdownProcessor({
             gfm: options.gfm ?? true,
             ...(options.syntaxHighlight === undefined
                 ? {}
                 : { syntaxHighlight: options.syntaxHighlight }),
-            ...(options.remarkPlugins === undefined ? {} : { remarkPlugins: options.remarkPlugins }),
+            remarkPlugins: [
+                ...(options.remarkPlugins ?? []),
+                ...(options.links === undefined ? [] : [rewritePageLinks(options.links, failures)]),
+            ],
             ...(options.rehypePlugins === undefined
                 ? {}
                 : { rehypePlugins: [rehypeHeadingIds, ...options.rehypePlugins] }),
@@ -26,8 +64,11 @@ export function createMarkdownRenderer(options = {}) {
         });
         return pending;
     };
-    return async (markdown) => {
-        const { code, metadata } = await (await renderer()).render(markdown);
+    return async (markdown, page) => {
+        const frontmatter = page === undefined ? undefined : { ...page.frontmatter, slug: page.slug };
+        const { code, metadata } = await (await renderer()).render(markdown, frontmatter === undefined ? undefined : { frontmatter });
+        if (frontmatter !== undefined && failures.has(frontmatter))
+            throw failures.get(frontmatter);
         return { html: code, headings: metadata.headings };
     };
 }
@@ -36,6 +77,6 @@ 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);
+    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,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"}
+{"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.1.0",
+  "version": "0.4.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,7 +28,7 @@
   },
   "dependencies": {
     "@astrojs/markdown-remark": "7.2.0",
-    "@docspack/sheaf": "^0.1.0"
+    "@docspack/sheaf": "^0.4.0"
   },
   "devDependencies": {
     "@docspack/config": "0.1.0",

package/src/render.ts

@@ -6,7 +6,13 @@ import {
   rehypeHeadingIds,
   type ShikiConfig,
 } from "@astrojs/markdown-remark";
-import type { Heading, Page } from "@docspack/sheaf";
+import {
+  type ContentGraph,
+  type Heading,
+  type LinkOptions,
+  linkHref,
+  type Page,
+} from "@docspack/sheaf";
 
 /**
  * Rendering a graph's pages with Astro's own Markdown pipeline.
@@ -67,17 +73,74 @@ export interface RendererOptions {
    *
    * 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.
+   * 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.
+ *
+ * A broken link is recorded against that frontmatter object rather than thrown. Astro catches
+ * anything a plugin throws, logs it and rethrows it prefixed `Failed to parse Markdown file
+ * "undefined":` — a page here has no file URL, and giving it one would switch on Astro's image
+ * collection, which rewrites every `<img>`. `render` throws the recorded error once Astro returns,
+ * with the message `linkHref` wrote.
+ */
+function rewritePageLinks(
+  links: NonNullable<RendererOptions["links"]>,
+  failures: WeakMap<object, unknown>,
+) {
+  return () => (tree: MdastNode, file: AstroFile) => {
+    const frontmatter = file.data.astro?.frontmatter;
+    const slug = frontmatter?.slug;
+    const from = links.graph.pages.find((page) => page.slug === slug);
+    if (from === undefined || frontmatter === 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);
+    };
+    try {
+      visit(tree);
+    } catch (error) {
+      failures.set(frontmatter, error);
+    }
+  };
 }
 
 export type PageRenderer = (page: Page) => Promise<RenderedPage>;
 
-/** Renders Markdown that is not a page. */
-export type SourceRenderer = (markdown: string) => Promise<RenderedPage>;
+/**
+ * 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.
@@ -92,6 +155,7 @@ export type SourceRenderer = (markdown: string) => Promise<RenderedPage>;
  */
 export function createMarkdownRenderer(options: RendererOptions = {}): SourceRenderer {
   let pending: Promise<MarkdownRenderer> | undefined;
+  const failures = new WeakMap<object, unknown>();
 
   const renderer = (): Promise<MarkdownRenderer> => {
     pending ??= createMarkdownProcessor({
@@ -99,7 +163,10 @@ export function createMarkdownRenderer(options: RendererOptions = {}): SourceRen
       ...(options.syntaxHighlight === undefined
         ? {}
         : { syntaxHighlight: options.syntaxHighlight }),
-      ...(options.remarkPlugins === undefined ? {} : { remarkPlugins: options.remarkPlugins }),
+      remarkPlugins: [
+        ...(options.remarkPlugins ?? []),
+        ...(options.links === undefined ? [] : [rewritePageLinks(options.links, failures)]),
+      ],
       ...(options.rehypePlugins === undefined
         ? {}
         : { rehypePlugins: [rehypeHeadingIds, ...options.rehypePlugins] }),
@@ -108,8 +175,13 @@ export function createMarkdownRenderer(options: RendererOptions = {}): SourceRen
     return pending;
   };
 
-  return async (markdown) => {
-    const { code, metadata } = await (await renderer()).render(markdown);
+  return async (markdown, page) => {
+    const frontmatter = page === undefined ? undefined : { ...page.frontmatter, slug: page.slug };
+    const { code, metadata } = await (await renderer()).render(
+      markdown,
+      frontmatter === undefined ? undefined : { frontmatter },
+    );
+    if (frontmatter !== undefined && failures.has(frontmatter)) throw failures.get(frontmatter);
     return { html: code, headings: metadata.headings };
   };
 }
@@ -119,5 +191,5 @@ 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);
+  return (page) => render(page.content, page);
 }