blume 2.0.1 → 2.0.3

package/src/markdown/base-links.ts

@@ -1,5 +1,11 @@
-import { isInternalPath, withComposedBasePath } from "../core/base-path.ts";
+import {
+  isInternalPath,
+  withAuthoredBasePath,
+  withBasePath,
+} from "../core/base-path.ts";
+import { servesRoute } from "../core/locale-links.ts";
 import type { MdastNode } from "./mdast.ts";
+import { routeSnapshotReader } from "./route-snapshot.ts";
 
 interface UrlNode extends MdastNode {
   url?: string | null;
@@ -14,47 +20,86 @@ interface MdastUrlContext {
   setProperty: (node: MdastNode, key: "url", value: string) => void;
 }
 
-/**
- * A path whose final segment carries a file extension (`/spec.pdf`, `/logo.svg`)
- * — treated as a public asset, which Blume serves from `public/` at the site
- * root and does *not* move under `basePath`. Bare page links (`/guide`) have no
- * extension. The rare dotted route (`/releases/v1.0`) is left un-based here; the
- * build-time link checker still resolves it against the route set.
- */
-const ASSET_PATH = /\.[a-z0-9]+$/iu;
-
-/** Strip any `#fragment`/`?query` so only the path is extension-tested. */
-const pathOf = (url: string): string => url.replace(/[#?].*$/u, "");
-
 /** Only a string URL can be rebased; MDAST allows null or absent urls. */
 const isUrl = (url: string | null | undefined): url is string =>
   typeof url === "string";
 
+export interface BaseLinksPluginOptions {
+  /**
+   * The `blume:data` JSON file, for an ejected app: with no CLI in the process
+   * to publish the snapshot, the plugin reads the file eject writes instead.
+   */
+  dataFile?: string;
+}
+
 /**
- * Satteri MDAST plugin that prepends the served-URL base — `deployment.base`
- * layered over the site-wide `basePath` — to root-relative internal page links
- * (`[x](/guide)` -> `/base/docs/guide`), so authors write links as if mounted
- * at root. Idempotent per layer (via `withComposedBasePath`, so a hand-written
- * `/docs/x` isn't double-prefixed) and inert for external URLs, fragments,
- * relative paths, images, and asset links. Only constructed when a base is set
- * (see `markdown/index.ts`).
+ * Satteri MDAST plugin that prepends the served-URL base to root-relative
+ * internal links, so authors write links as if mounted at root. A page link
+ * gains `deployment.base` layered over the site-wide `basePath` (`[x](/guide)`
+ * -> `/base/docs/guide`); a public asset — an image, or a link to a file like
+ * `/spec.pdf` (see `withAuthoredBasePath`) — gains `deployment.base` alone,
+ * since Astro serves `public/` under it but never under `basePath`.
+ * Idempotent per layer (a hand-written `/docs/x` isn't double-prefixed) and
+ * inert for external URLs, fragments, and relative paths. Only constructed
+ * when a base is set (see `markdown/index.ts`).
  */
-export const baseLinksPlugin = (deployBase: string, basePath: string) => {
-  const rebase = (node: UrlNode, ctx: MdastUrlContext): void => {
+export const baseLinksPlugin = (
+  deployBase: string,
+  basePath: string,
+  options: BaseLinksPluginOptions = {}
+) => {
+  const readSnapshot = routeSnapshotReader(options.dataFile);
+  // Parsed once per published snapshot, like the relative-links index.
+  let cached: { routes: Set<string>; text: string } | undefined;
+
+  /** Every route the site serves (base-prefixed), from the route snapshot. */
+  const servedRoutes = (): ReadonlySet<string> => {
+    const text = readSnapshot();
+    if (text === undefined) {
+      return new Set();
+    }
+    if (cached?.text !== text) {
+      const data: { routes: { path: string }[] } = JSON.parse(text);
+      cached = {
+        routes: new Set(data.routes.map((route) => route.path)),
+        text,
+      };
+    }
+    return cached.routes;
+  };
+
+  /** Whether a page is served at a based, fragment-less path. */
+  const servesPage = (route: string): boolean =>
+    servesRoute(servedRoutes(), route);
+
+  /** Record `based(url)` on the node when its root-relative URL changes. */
+  const rebase = (
+    node: UrlNode,
+    ctx: MdastUrlContext,
+    based: (url: string) => string
+  ): void => {
     const { url } = node;
-    if (isUrl(url) && isInternalPath(url) && !ASSET_PATH.test(pathOf(url))) {
-      const next = withComposedBasePath(deployBase, basePath, url);
+    if (isUrl(url) && isInternalPath(url)) {
+      const next = based(url);
       if (next !== url) {
         ctx.setProperty(node, "url", next);
       }
     }
   };
-  // `link` covers inline links; `definition` covers reference-style link
-  // definitions (`[x]: /guide`). `image` is intentionally excluded — images are
-  // public assets served at the site root, unaffected by `basePath`.
+  const rebaseLink = (node: UrlNode, ctx: MdastUrlContext): void =>
+    rebase(node, ctx, (url) =>
+      withAuthoredBasePath(deployBase, basePath, url, servesPage)
+    );
+  // An image is always a file, never a page: `public/` (or a generated asset
+  // endpoint), served under the deployment base but not `basePath`.
+  const rebaseImage = (node: UrlNode, ctx: MdastUrlContext): void =>
+    rebase(node, ctx, (url) => withBasePath(deployBase, url));
+  // `link` covers inline links; `definition` covers reference-style
+  // definitions (`[x]: /guide`), which a link or an image may cite.
   return {
-    definition: rebase,
-    link: rebase,
+    definition: rebaseLink,
+    image: rebaseImage,
+    link: rebaseLink,
     name: "blume-base-links",
   };
 };

package/src/markdown/directives.ts

@@ -3,15 +3,30 @@ import { toString as mdastToString } from "mdast-util-to-string";
 import { jsxAttribute, jsxFlowElement } from "./mdast.ts";
 import type { MdastNode, MdastVisitorContext } from "./mdast.ts";
 
-interface DirectiveNode extends MdastNode {
+export interface DirectiveNode extends MdastNode {
   attributes?: Record<string, string | null | undefined> | null;
   // Satteri gives an empty container directive (`:::note\n:::`) `children: null`.
   children?: MdastNode[] | null;
   name: string;
+  position?: {
+    start?: { offset?: number };
+    end?: { offset?: number };
+  };
+}
+
+/**
+ * The visitor-context slice the directive visitors use. `source` is the page
+ * the directive offsets index into; without it the literal fallback rebuilds
+ * a directive from its node instead. `parent` walks up to an enclosing
+ * container directive, which renders the directives inside it itself.
+ */
+interface DirectiveVisitorContext extends MdastVisitorContext {
+  parent?: (node: MdastNode) => MdastNode | undefined;
+  source?: string;
 }
 
 /** Directive names that map directly onto a Callout type. */
-const CALLOUT_TYPES = new Set([
+export const CALLOUT_TYPES: ReadonlySet<string> = new Set([
   "danger",
   "info",
   "note",
@@ -25,7 +40,7 @@ interface CalloutAliases {
   [alias: string]: string;
 }
 
-const ALIASES: CalloutAliases = {
+export const CALLOUT_ALIASES: Readonly<CalloutAliases> = {
   caution: "warning",
   error: "danger",
   important: "note",
@@ -38,48 +53,239 @@ export const calloutTypeFor = (name: string): string | null => {
   if (CALLOUT_TYPES.has(lower)) {
     return lower;
   }
-  return ALIASES[lower] ?? null;
+  return CALLOUT_ALIASES[lower] ?? null;
+};
+
+/** The markers that open a text (`:name`) and a leaf (`::name`) directive. */
+const LITERAL_MARKERS = new Map([
+  ["leafDirective", "::"],
+  ["textDirective", ":"],
+]);
+
+/** A directive's `[label]` rebuilt from its label's text, or nothing. */
+const labelSource = (label: MdastNode[]): string =>
+  label.length > 0
+    ? `[${mdastToString(label, { includeImageAlt: false })}]`
+    : "";
+
+/** A directive's `{attributes}` rebuilt from its node, or nothing. */
+const attributeSource = (node: DirectiveNode): string => {
+  const attributes = Object.entries(node.attributes ?? {}).map(
+    ([key, value]) => (value ? `${key}="${value}"` : key)
+  );
+  return attributes.length > 0 ? `{${attributes.join(" ")}}` : "";
+};
+
+/** The source a directive node spans, when its offsets point into `source`. */
+const spannedSource = (node: DirectiveNode, source: string): string | null => {
+  const start = node.position?.start?.offset;
+  const end = node.position?.end?.offset;
+  return start !== undefined && end !== undefined
+    ? source.slice(start, end)
+    : null;
 };
 
 /**
- * Satteri MDAST plugin mapping container directives (`:::note`, `:::warning`,
- * `:::tip`, …) onto Blume's `<Callout>` component. The title comes from a
- * `[label]` or a `{title="…"}` attribute; the body becomes the callout content.
- * Directive names that are not callouts are left untouched.
+ * A text or leaf directive exactly as the author wrote it. The slice by
+ * offsets is the exact text — `[label]` and `{attrs}` included — and is
+ * trusted only when it opens with the directive's own marker and name;
+ * content an `<include>` spliced in carries no offsets into this page, so it
+ * is rebuilt from the node instead.
  */
-export const directiveToCalloutPlugin = () => ({
-  containerDirective(node: DirectiveNode, ctx: MdastVisitorContext) {
-    const type = calloutTypeFor(node.name);
-    if (type === null) {
-      return;
+export const directiveSource = (
+  node: DirectiveNode,
+  marker: string,
+  source: string
+): string => {
+  const opening = `${marker}${node.name}`;
+  const slice = spannedSource(node, source);
+  if (slice?.startsWith(opening)) {
+    return slice;
+  }
+  return `${opening}${labelSource(node.children ?? [])}${attributeSource(node)}`;
+};
+
+/**
+ * The node a text or leaf directive renders as: its literal source, as text
+ * in place of a text directive and as a paragraph in place of a leaf one.
+ */
+const literalDirective = (
+  node: DirectiveNode,
+  marker: string,
+  source: string
+): MdastNode => {
+  const text = { type: "text", value: directiveSource(node, marker, source) };
+  return marker === ":" ? text : { children: [text], type: "paragraph" };
+};
+
+const FENCE = /^:{3,}/u;
+
+// The line that closes a container: a colon fence, after whatever quote or
+// list indentation the container sits in.
+const CLOSING_FENCE = /\n[\t >]*(?<fence>:{3,})\s*$/u;
+
+/** A paragraph holding one line of literal text. */
+const literalLine = (value: string): MdastNode => ({
+  children: [{ type: "text", value }],
+  type: "paragraph",
+});
+
+/**
+ * The fence lines of a container directive as the author wrote them — the
+ * opening one with its `[label]` and `{attrs}` — or, without offsets into
+ * this page (an `<include>`), rebuilt from the node. A container left
+ * unclosed runs to the end of its parent and has no closing line.
+ */
+const containerFences = (
+  node: DirectiveNode,
+  label: MdastNode | undefined,
+  source: string
+): string[] => {
+  const slice = spannedSource(node, source) ?? "";
+  const fence = FENCE.exec(slice)?.[0];
+  if (fence === undefined || !slice.startsWith(node.name, fence.length)) {
+    const labelText = labelSource(label ? [label] : []);
+    return [`:::${node.name}${labelText}${attributeSource(node)}`, ":::"];
+  }
+  const [opening = ""] = slice.split("\n", 1);
+  const closing = CLOSING_FENCE.exec(slice.slice(opening.length))?.groups
+    ?.fence;
+  // A shorter fence can't close the container; it is the body's last line.
+  return closing !== undefined && closing.length >= fence.length
+    ? [opening.trimEnd(), closing]
+    : [opening.trimEnd()];
+};
+
+/**
+ * What a container directive renders as. A callout name becomes a
+ * `<Callout>`: the title comes from a `[label]` or a `{title="…"}` attribute,
+ * and the body becomes the callout content. Blume has no other container, and
+ * dropping one would drop its body with it, so any other name — `:::details`,
+ * a `:::warnig` typo — renders its body between its fence lines, as written.
+ * The directives inside render here too, since Satteri reaches them only
+ * after this replacement has taken their original.
+ */
+const renderContainer = (
+  node: DirectiveNode,
+  source: string
+): MdastNode | MdastNode[] => {
+  const children = (node.children ?? []).flatMap((child) =>
+    // oxlint-disable-next-line no-use-before-define -- mutual recursion: a container's body holds directives, containers included
+    literalize(child, source)
+  );
+
+  // A leading `:::name[Label]` parses to a paragraph flagged `directiveLabel`.
+  // SAFETY: Satteri stamps `directiveLabel` on that paragraph's `data`; any
+  // other node reads undefined and fails the check.
+  const labelIndex = children.findIndex(
+    (child) =>
+      child.type === "paragraph" &&
+      (child.data as { directiveLabel?: boolean } | undefined)?.directiveLabel
+  );
+  const [label] = labelIndex === -1 ? [] : children.splice(labelIndex, 1);
+
+  const type = calloutTypeFor(node.name);
+  if (type === null) {
+    const [opening = "", closing] = containerFences(node, label, source);
+    return [
+      literalLine(opening),
+      ...children,
+      ...(closing === undefined ? [] : [literalLine(closing)]),
+    ];
+  }
+
+  // Flatten the label's phrasing children so `:::note[Read **this**]` yields
+  // `Read this`; image alt is excluded (an image is not label text), matching
+  // the historical child-values-only behavior.
+  const title =
+    node.attributes?.title ??
+    (label ? mdastToString(label, { includeImageAlt: false }) : undefined);
+  const attributes = [jsxAttribute("type", type)];
+  if (title) {
+    attributes.push(jsxAttribute("title", title));
+  }
+  return jsxFlowElement("Callout", attributes, children);
+};
+
+/**
+ * `node` with every directive in it rendered: text and leaf directives as
+ * their literal source, containers as {@link renderContainer}.
+ */
+const literalize = (node: MdastNode, source: string): MdastNode[] => {
+  if (node.type === "containerDirective") {
+    // SAFETY: a `containerDirective` carries a `name` plus optional
+    // attributes, children, and position — the `DirectiveNode` shape.
+    return [renderContainer(node as DirectiveNode, source)].flat();
+  }
+  const marker = LITERAL_MARKERS.get(node.type);
+  if (marker) {
+    // SAFETY: only Satteri's `textDirective`/`leafDirective` nodes have a
+    // marker, and they carry a `name` plus optional attributes, children,
+    // and position — the `DirectiveNode` shape.
+    return [literalDirective(node as DirectiveNode, marker, source)];
+  }
+  // SAFETY: a parent's `children` is always a node list; leaves carry none.
+  const children = node.children as MdastNode[] | null | undefined;
+  if (!children) {
+    return [node];
+  }
+  return [
+    {
+      ...node,
+      children: children.flatMap((child) => literalize(child, source)),
+    },
+  ];
+};
+
+/** Whether a container directive (already rendered, body and all) holds `node`. */
+const insideContainer = (node: MdastNode, ctx: DirectiveVisitorContext) => {
+  for (
+    let parent = ctx.parent?.(node);
+    parent !== undefined;
+    parent = ctx.parent?.(parent)
+  ) {
+    if (parent.type === "containerDirective") {
+      return true;
     }
+  }
+  return false;
+};
 
-    const children = [...(node.children ?? [])];
-    let title = node.attributes?.title ?? undefined;
-
-    // A leading `:::name[Label]` parses to a paragraph flagged `directiveLabel`.
-    // SAFETY: Satteri stamps `directiveLabel` on that paragraph's `data`; any
-    // other node reads undefined and fails the check.
-    const labelIndex = children.findIndex(
-      (child) =>
-        child.type === "paragraph" &&
-        (child.data as { directiveLabel?: boolean } | undefined)?.directiveLabel
-    );
-    if (labelIndex !== -1) {
-      const [label] = children.splice(labelIndex, 1);
-      if (label) {
-        // Flatten the label's phrasing children so `:::note[Read **this**]`
-        // yields `Read this`; image alt is excluded (an image is not label
-        // text), matching the historical child-values-only behavior.
-        title ??= mdastToString(label, { includeImageAlt: false }) || undefined;
-      }
+/** The text and leaf visitor: render the directive as its literal source. */
+const renderLiteral =
+  (marker: string) => (node: DirectiveNode, ctx: DirectiveVisitorContext) => {
+    // A container's body was already rendered into its replacement; a
+    // transform queued on the replaced original would be dropped with a
+    // warning.
+    if (insideContainer(node, ctx)) {
+      return;
     }
+    ctx.replaceNode(node, literalDirective(node, marker, ctx.source ?? ""));
+  };
 
-    const attributes = [jsxAttribute("type", type)];
-    if (title) {
-      attributes.push(jsxAttribute("title", title));
+/**
+ * Satteri MDAST plugin for directives. Container directives (`:::note`,
+ * `:::warning`, `:::tip`, …) map onto Blume's `<Callout>` component, and any
+ * other container renders its body between its literal fence lines (see
+ * {@link renderContainer}).
+ *
+ * Blume handles no text (`:name`) or leaf (`::name`) directives, and prose is
+ * full of text that parses as one — `16:9`, `10:30am`, `og:image`,
+ * `pets:read` — so both render as the literal source the author wrote instead
+ * of vanishing.
+ */
+export const directiveToCalloutPlugin = () => ({
+  containerDirective(node: DirectiveNode, ctx: DirectiveVisitorContext) {
+    // A container inside another was rendered with its enclosing one.
+    if (insideContainer(node, ctx)) {
+      return;
     }
-    ctx.replaceNode(node, jsxFlowElement("Callout", attributes, children));
+    ctx.replaceNode(node, renderContainer(node, ctx.source ?? ""));
   },
+  leafDirective: renderLiteral("::"),
   name: "blume-directive-callout",
+  // Positions are opt-in since satteri 0.10; the literal fallback slices
+  // directives out of the source by offset.
+  options: { position: true },
+  textDirective: renderLiteral(":"),
 });

package/src/markdown/features.ts

@@ -19,3 +19,20 @@ export const MDX_FEATURES = {
   directive: true,
   math: { singleDollarTextMath: false },
 } satisfies Features;
+
+/**
+ * The feature sets for a page body, once its front matter is off. Astro reads
+ * a page's front matter itself and hands the renderer the body alone, and the
+ * search extractor strips it first too — so front matter parsing is off here:
+ * left on, a body that opens with a `---` rule read everything up to the next
+ * `---` line as front matter and dropped it from the page.
+ */
+export const MARKDOWN_BODY_FEATURES = {
+  ...MARKDOWN_FEATURES,
+  frontmatter: false,
+} satisfies Features;
+
+export const MDX_BODY_FEATURES = {
+  ...MDX_FEATURES,
+  frontmatter: false,
+} satisfies Features;

package/src/markdown/index.ts

@@ -13,7 +13,7 @@ import { baseLinksPlugin } from "./base-links.ts";
 import { codeTitleTransformer } from "./code-title.ts";
 import { directiveToCalloutPlugin } from "./directives.ts";
 import { externalLinksPlugin } from "./external-links.ts";
-import { MARKDOWN_FEATURES, MDX_FEATURES } from "./features.ts";
+import { MARKDOWN_BODY_FEATURES, MDX_BODY_FEATURES } from "./features.ts";
 import { headingAnchorPlugin } from "./heading-anchors.ts";
 import { includePlugin } from "./include.ts";
 import { inlineCodeHighlightPlugin } from "./inline-code.ts";
@@ -286,17 +286,18 @@ export interface BlumeMarkdownOptions {
   contentRoot?: string;
   /**
    * The `blume:data` snapshot file an ejected app aliases. Relative page links
-   * resolve through the snapshot the CLI publishes; with no CLI in the
-   * process, they read this file instead.
+   * (and the base-path rewrite of dotted page routes) resolve through the
+   * snapshot the CLI publishes; with no CLI in the process, they read this
+   * file instead.
    */
   dataFile?: string;
 }
 
 /**
  * MDAST plugins that apply to both `.md` and `.mdx`: relative page links
- * rewritten to the root-relative route they mean, then the base-path link
- * rewrite (added only when a `basePath` or `deployBase` is configured), which
- * layers `deployment.base` over the rewritten routes.
+ * rewritten to the served URL of the route they mean, then the base-path link
+ * rewrite for root-relative links (added only when a `basePath` or
+ * `deployBase` is configured).
  */
 const blumeSharedMdastPlugins = (
   options: BlumeMarkdownOptions
@@ -305,12 +306,15 @@ const blumeSharedMdastPlugins = (
     relativeLinksPlugin({
       contentRoot: options.contentRoot,
       dataFile: options.dataFile,
+      deployBase: options.deployBase,
     })
   ),
   ...(options.basePath || options.deployBase
     ? [
         asMdastPlugin(
-          baseLinksPlugin(options.deployBase ?? "", options.basePath ?? "")
+          baseLinksPlugin(options.deployBase ?? "", options.basePath ?? "", {
+            dataFile: options.dataFile,
+          })
         ),
       ]
     : []),
@@ -327,7 +331,7 @@ const blumeIncludePlugin = (options: BlumeMarkdownOptions): MdastPlugin =>
 /** Sätteri processor for plain `.md`, with Blume's curated feature set. */
 export const blumeMarkdownProcessor = (options: BlumeMarkdownOptions = {}) =>
   satteri({
-    features: { ...MARKDOWN_FEATURES },
+    features: { ...MARKDOWN_BODY_FEATURES },
     hastPlugins: blumeHastPlugins(options),
     mdastPlugins: [
       blumeIncludePlugin(options),
@@ -356,7 +360,7 @@ export type BlumeMdxOptions = BlumeMarkdownOptions;
  */
 export const blumeMdxProcessor = (options: BlumeMdxOptions = {}) =>
   satteri({
-    features: { ...MDX_FEATURES },
+    features: { ...MDX_BODY_FEATURES },
     hastPlugins: blumeHastPlugins(options),
     mdastPlugins: [
       blumeIncludePlugin(options),

package/src/markdown/mdast.ts

@@ -19,9 +19,12 @@ export type MdastValue =
   | MdastValue[]
   | { [key: string]: MdastValue };
 
-/** The visitor context Blume's plugins use to mutate the tree. */
+/**
+ * The visitor context Blume's plugins use to mutate the tree. A list of
+ * nodes takes the replaced node's place in order.
+ */
 export interface MdastVisitorContext {
-  replaceNode: (node: MdastNode, replacement: MdastNode) => void;
+  replaceNode: (node: MdastNode, replacement: MdastNode | MdastNode[]) => void;
 }
 
 /** Any MDAST node, keyed loosely since we build a small subset by hand. */

package/src/markdown/relative-links.ts

@@ -1,12 +1,12 @@
-import { readFileSync, statSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
 import { dirname, normalize, relative, resolve } from "pathe";
 
-import { readRuntimeModule } from "../astro/runtime-modules.ts";
+import { mountBasePath } from "../core/base-path.ts";
 import { isIndexFileName, resolveRelativeHref } from "../core/links.ts";
 import type { RelativeLinkBase } from "../core/links.ts";
 import type { MdastNode, MdastValue } from "./mdast.ts";
+import { routeSnapshotReader } from "./route-snapshot.ts";
 
 interface UrlNode extends MdastNode {
   url?: string | null;
@@ -131,6 +131,8 @@ export interface RelativeLinksPluginOptions {
    * to publish the snapshot, the plugin reads the file eject writes instead.
    */
   dataFile?: string;
+  /** Astro's `deployment.base` subdirectory (`""` or `/seg`). */
+  deployBase?: string;
 }
 
 /**
@@ -146,9 +148,11 @@ export interface RelativeLinksPluginOptions {
  * entries (remote sources) by the longest trailing path that names one. A file
  * the snapshot doesn't know keeps its links as written.
  *
- * Runs before the base-links plugin, whose `basePath` layering is idempotent,
- * so a rewritten route (which already carries `basePath`) only gains the
- * `deployment.base` prefix.
+ * A rewritten route already carries `basePath`, and the `deployment.base`
+ * prefix goes on here, unconditionally: the route is one Blume serves, so
+ * `guides/setup.md` under base `/guides` is linked at `/guides/guides/setup`.
+ * The base-links plugin that runs next is idempotent per layer, so it leaves
+ * the based route alone.
  */
 export const relativeLinksPlugin = (
   options: RelativeLinksPluginOptions = {}
@@ -156,34 +160,16 @@ export const relativeLinksPlugin = (
   const contentRoot = options.contentRoot
     ? resolve(options.contentRoot)
     : undefined;
-  const dataFile = options.dataFile ? resolve(options.dataFile) : undefined;
+  const deployBase = options.deployBase ?? "";
+  const readSnapshot = routeSnapshotReader(options.dataFile);
 
   // Parsed once per published snapshot: the CLI republishes on regeneration,
   // and an unchanged snapshot is the same string, so every page compiled
   // between regenerations reuses one index.
   let cached: { index: RouteIndex; text: string } | undefined;
-  let fileStamp: number | undefined;
-  let fileText: string | undefined;
-
-  /** The ejected snapshot file's text, re-read only when it changes. */
-  const readDataFile = (path: string): string | undefined => {
-    let stamp: number;
-    try {
-      stamp = statSync(path).mtimeMs;
-    } catch {
-      return undefined;
-    }
-    if (stamp !== fileStamp) {
-      fileStamp = stamp;
-      fileText = readFileSync(path, "utf-8");
-    }
-    return fileText;
-  };
 
   const routeIndex = (): RouteIndex | undefined => {
-    const text =
-      readRuntimeModule("blume:data") ??
-      (dataFile ? readDataFile(dataFile) : undefined);
+    const text = readSnapshot();
     if (text === undefined) {
       return undefined;
     }
@@ -265,7 +251,9 @@ export const relativeLinksPlugin = (
     const next = resolveRelativeHref(url, page, page.routeOf, (route) =>
       page.routes.has(route)
     );
-    return next === url ? undefined : next;
+    return next === undefined || next === url
+      ? undefined
+      : mountBasePath(deployBase, next);
   };
 
   const rewrite = (node: UrlNode, ctx: RelativeLinksContext): void => {

package/src/markdown/route-snapshot.ts

@@ -0,0 +1,37 @@
+import { readFileSync, statSync } from "node:fs";
+
+import { resolve } from "pathe";
+
+import { readRuntimeModule } from "../astro/runtime-modules.ts";
+
+/**
+ * A reader for the `blume:data` snapshot the Markdown link plugins consult for
+ * the site's routes: the text the CLI publishes, or — in an ejected app, with
+ * no CLI in the process — the snapshot file eject writes (`dataFile`), re-read
+ * only when it changes. Resolves to `undefined` when neither is available.
+ */
+export const routeSnapshotReader = (
+  dataFile?: string
+): (() => string | undefined) => {
+  const file = dataFile ? resolve(dataFile) : undefined;
+  let fileStamp: number | undefined;
+  let fileText: string | undefined;
+
+  /** The ejected snapshot file's text, re-read only when it changes. */
+  const readDataFile = (path: string): string | undefined => {
+    let stamp: number;
+    try {
+      stamp = statSync(path).mtimeMs;
+    } catch {
+      return undefined;
+    }
+    if (stamp !== fileStamp) {
+      fileStamp = stamp;
+      fileText = readFileSync(path, "utf-8");
+    }
+    return fileText;
+  };
+
+  return () =>
+    readRuntimeModule("blume:data") ?? (file ? readDataFile(file) : undefined);
+};