blume 2.0.2 → 2.1.0

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

@@ -11,11 +11,29 @@ export const MARKDOWN_FEATURES = {
 
 /**
  * The `.mdx` feature set: Markdown's plus `:::` directives (→ `<Callout>`) and
- * block-only math — `singleDollarTextMath: false` keeps a bare `$` (currency,
- * shell, code) as literal text and only parses `$$…$$`.
+ * math — `singleDollarTextMath: false` keeps a bare `$` (currency, shell,
+ * code) as literal text and only parses `$$…$$`, as a block on its own lines
+ * or inline within a sentence.
  */
 export const MDX_FEATURES = {
   ...MARKDOWN_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/fence-meta.ts

@@ -41,9 +41,11 @@ export const metaTokens = (meta: string | null | undefined): string[] =>
  * a block title.
  */
 export const RESERVED_META_KEYWORDS: ReadonlySet<string> = new Set([
+  "expandable",
   "lineNumbers",
   "ts2js",
   "twoslash",
+  "wrap",
 ]);
 
 /** A Shiki `{1,3-5}` line-range token. */

package/src/markdown/include.ts

@@ -9,6 +9,8 @@ import {
   hasIncludeStatements,
   matchIncludeStatement,
 } from "../core/includes.ts";
+import { substituteVariables } from "../core/variables.ts";
+import type { ContentVariables } from "../core/variables.ts";
 import type { MdastNode, MdastValue } from "./mdast.ts";
 
 /**
@@ -83,6 +85,8 @@ const errorBlock = (message: string): string =>
 export interface IncludePluginOptions {
   /** The docs content root; bounds include resolution when set. */
   contentRoot?: string;
+  /** Content variables, substituted in each included file before it's parsed. */
+  variables?: ContentVariables;
 }
 
 /** A plain string attribute value; expression values don't carry a path. */
@@ -104,6 +108,10 @@ const statementFromJsx = (
     if (attr.name === "meta" && attr.value) {
       attributes.meta = attr.value;
     }
+    // Every other string attribute is a prop, as in the string-level parser.
+    if (attr.name && attr.name !== "lang" && attr.name !== "meta") {
+      attributes.props = { ...attributes.props, [attr.name]: attr.value };
+    }
   }
   return { attributes, target: ctx.textContent(node).trim() };
 };
@@ -147,7 +155,9 @@ export const includePlugin = (options: IncludePluginOptions = {}) => {
     for (const nested of expanded.errors) {
       ctx.report({ message: nested.message, node, severity: "warning" });
     }
-    return expanded.text;
+    // Substituted here, before the spliced text is parsed: in an MDX page it
+    // parses as MDX, where `{{name}}` would be a JavaScript expression.
+    return substituteVariables(expanded.text, options.variables);
   };
 
   /**

package/src/markdown/index.ts

@@ -9,11 +9,14 @@ import {
 import { escape as escapeHtml } from "html-escaper";
 import { codeToHtml } from "shiki";
 
+import { hasVariables } from "../core/variables.ts";
+import type { ContentVariables } from "../core/variables.ts";
+import { apiRailPlugin } from "./api-rail.ts";
 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";
@@ -26,6 +29,8 @@ import { tableWrapPlugin } from "./table-wrap.ts";
 import { DEFAULT_CODE_THEMES } from "./themes.ts";
 import type { CodeThemes } from "./themes.ts";
 import { ts2jsPlugin } from "./ts2js.ts";
+import { variablesPlugin } from "./variables.ts";
+import { viewsPlugin } from "./views.ts";
 
 export type { CodeTheme, CodeThemes } from "./themes.ts";
 
@@ -277,6 +282,12 @@ export interface BlumeMarkdownOptions {
    * `basePath` link isn't double-prefixed (see `withComposedBasePath`).
    */
   deployBase?: string;
+  /**
+   * `variables`: `{{name}}` references replaced in `.md` pages and in every
+   * included file (`.mdx` pages are substituted before parsing, by the
+   * `variablesVitePlugin`).
+   */
+  variables?: ContentVariables;
   /**
    * The docs content root, bounding `<include>` target resolution (and
    * anchoring `/`-leading include paths). When unset, relative includes still
@@ -295,9 +306,9 @@ export interface BlumeMarkdownOptions {
 
 /**
  * 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
@@ -306,6 +317,7 @@ const blumeSharedMdastPlugins = (
     relativeLinksPlugin({
       contentRoot: options.contentRoot,
       dataFile: options.dataFile,
+      deployBase: options.deployBase,
     })
   ),
   ...(options.basePath || options.deployBase
@@ -325,15 +337,23 @@ const blumeSharedMdastPlugins = (
  * (callouts, mermaid, math, base links) like inline content.
  */
 const blumeIncludePlugin = (options: BlumeMarkdownOptions): MdastPlugin =>
-  asMdastPlugin(includePlugin({ contentRoot: options.contentRoot }));
+  asMdastPlugin(
+    includePlugin({
+      contentRoot: options.contentRoot,
+      variables: options.variables,
+    })
+  );
 
 /** 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),
+      ...(hasVariables(options.variables)
+        ? [asMdastPlugin(variablesPlugin(options.variables))]
+        : []),
       ...blumeSharedMdastPlugins(options),
     ],
   });
@@ -344,13 +364,15 @@ export type BlumeMdxOptions = BlumeMarkdownOptions;
  * Sätteri MDX processor: Blume's feature set plus the MDAST plugins that target
  * components — `package-install` → package-manager tabs, ` ```ts ts2js ` →
  * TypeScript/JavaScript tabs, `:::note` → `<Callout>`, ` ```mermaid ` → a
- * `<blume-mermaid>` element, and block math
- * (`$$…$$`) → the `<Math>` component. Used as the `processor` for
+ * `<blume-mermaid>` element, block math
+ * (`$$…$$`) → the `<Math>` component, and top-level `<RequestExample>` and
+ * `<ResponseExample>` → the page's `<ApiRail>`. Used as the `processor` for
  * `@astrojs/mdx` so these apply to `.mdx` only (plain `.md` uses
  * {@link blumeMarkdownProcessor}).
  *
- * Math is always on but block-only: `singleDollarTextMath: false` keeps a bare
- * `$` (currency, shell, code) as literal text and only parses `$$…$$`. The
+ * Math is always on and written `$$…$$`, as a block or inline:
+ * `singleDollarTextMath: false` keeps a bare `$` (currency, shell, code) as
+ * literal text. The
  * generated runtime imports the `<Math>` component (and KaTeX's stylesheet) only
  * when content actually uses `$$`, so a math-free site ships no KaTeX CSS.
  *
@@ -359,7 +381,7 @@ export type BlumeMdxOptions = BlumeMarkdownOptions;
  */
 export const blumeMdxProcessor = (options: BlumeMdxOptions = {}) =>
   satteri({
-    features: { ...MDX_FEATURES },
+    features: { ...MDX_BODY_FEATURES },
     hastPlugins: blumeHastPlugins(options),
     mdastPlugins: [
       blumeIncludePlugin(options),
@@ -369,5 +391,7 @@ export const blumeMdxProcessor = (options: BlumeMdxOptions = {}) =>
       asMdastPlugin(mermaidPlugin()),
       asMdastPlugin(mathPlugin()),
       ...blumeSharedMdastPlugins(options),
+      asMdastPlugin(apiRailPlugin()),
+      asMdastPlugin(viewsPlugin()),
     ],
   });

package/src/markdown/math.ts

@@ -7,10 +7,10 @@ interface MathNode extends MdastNode {
 
 /**
  * Satteri MDAST plugin that turns math nodes into Blume's `<Math>` component,
- * which renders them with KaTeX at build time. Block math (`$$…$$`) becomes a
- * block element. Blume runs the parser block-only (`singleDollarTextMath:
- * false`), so a bare `$` stays literal and no `inlineMath` nodes are produced;
- * the `inlineMath` visitor remains as a harmless safety net.
+ * which renders them with KaTeX at build time. `$$…$$` on its own lines is
+ * block math and becomes a display element; `$$…$$` inside a sentence is
+ * inline math and stays inline. The parser runs with `singleDollarTextMath:
+ * false`, so a single `$` (currency, a shell variable) never opens math.
  */
 export const mathPlugin = () => ({
   inlineMath(node: MathNode, ctx: MdastVisitorContext) {

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

@@ -2,6 +2,7 @@ import { fileURLToPath } from "node:url";
 
 import { dirname, normalize, relative, resolve } from "pathe";
 
+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";
@@ -130,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;
 }
 
 /**
@@ -145,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 = {}
@@ -155,6 +160,7 @@ export const relativeLinksPlugin = (
   const contentRoot = options.contentRoot
     ? resolve(options.contentRoot)
     : undefined;
+  const deployBase = options.deployBase ?? "";
   const readSnapshot = routeSnapshotReader(options.dataFile);
 
   // Parsed once per published snapshot: the CLI republishes on regeneration,
@@ -245,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/variables.ts

@@ -0,0 +1,56 @@
+import { substituteVariables } from "../core/variables.ts";
+import type { ContentVariables } from "../core/variables.ts";
+import type { MdastNode, MdastValue } from "./mdast.ts";
+
+/**
+ * The Markdown half of content variables (see `core/variables.ts`): a Sätteri
+ * MDAST plugin that replaces `{{name}}` in a plain `.md` page's text, code,
+ * raw HTML, and link and image destinations. A `.md` page has no expressions,
+ * so every reference survives parsing as text and can be replaced here; MDX
+ * pages are substituted before they're parsed instead (`astro/variables.ts`).
+ * Nodes change through `setProperty`, not by mutating the node object.
+ */
+
+interface VariableContext {
+  setProperty: (node: MdastNode, key: string, value: string) => void;
+}
+
+const isText = (value: MdastValue): value is string =>
+  typeof value === "string";
+
+/** The node properties that can hold a reference, per node type. */
+const FIELDS = {
+  code: ["value"],
+  definition: ["url", "title"],
+  html: ["value"],
+  image: ["url", "title", "alt"],
+  inlineCode: ["value"],
+  link: ["url", "title"],
+  text: ["value"],
+} as const;
+
+export const variablesPlugin = (variables: ContentVariables) => {
+  const replaceIn =
+    (keys: readonly string[]) =>
+    (node: MdastNode, ctx: VariableContext): void => {
+      for (const key of keys) {
+        const value = node[key];
+        if (value !== undefined && isText(value)) {
+          const next = substituteVariables(value, variables);
+          if (next !== value) {
+            ctx.setProperty(node, key, next);
+          }
+        }
+      }
+    };
+  return {
+    code: replaceIn(FIELDS.code),
+    definition: replaceIn(FIELDS.definition),
+    html: replaceIn(FIELDS.html),
+    image: replaceIn(FIELDS.image),
+    inlineCode: replaceIn(FIELDS.inlineCode),
+    link: replaceIn(FIELDS.link),
+    name: "blume-variables",
+    text: replaceIn(FIELDS.text),
+  };
+};