blume 1.6.3 → 1.6.5

package/src/components/openapi/RequestBody.astro

@@ -1,4 +1,5 @@
 ---
+import Description from "./Description.astro";
 import type { SchemaLike } from "./helpers.ts";
 import SchemaTable from "./SchemaTable.astro";
 
@@ -46,10 +47,7 @@ const schema = chosen?.[1]?.schema ?? {};
   </div>
   {
     requestBody.description && (
-      <div
-        class="text-muted-foreground text-sm"
-        set:text={requestBody.description}
-      />
+      <Description class="text-muted-foreground text-sm" text={requestBody.description} />
     )
   }
   <div class="mt-3">

package/src/components/openapi/Responses.astro

@@ -1,5 +1,6 @@
 ---
 import { statusColor } from "../colors.ts";
+import Description from "./Description.astro";
 import type { SchemaLike } from "./helpers.ts";
 import SchemaTable from "./SchemaTable.astro";
 
@@ -52,9 +53,9 @@ const items = Object.entries(responses);
                   {status}
                 </span>
                 {response.description && (
-                  <span
-                    class="text-muted-foreground text-sm"
-                    set:text={response.description}
+                  <Description
+                    class="min-w-0 text-muted-foreground text-sm"
+                    text={response.description}
                   />
                 )}
               </div>

package/src/components/openapi/SchemaProperty.astro

@@ -1,4 +1,5 @@
 ---
+import Description from "./Description.astro";
 import {
   constraints,
   isNullable,
@@ -54,7 +55,11 @@ const expandable =
   !circular && (hasObjectShape(resolved) || Boolean(items && hasObjectShape(items)));
 ---
 
-<div class="border-border border-t py-3 first:border-t-0 last:pb-0">
+{/* The row's vertical scale is 8 / 12 / 16px, and every other reference table copies it. A
+    description is a block of Markdown, not a line: at 4px it sat closer to the label above it
+    than its own paragraphs sat to each other, and the disclosure below it touched the next row's
+    divider. Each step separates a bigger unit than the one before. */}
+<div class="border-border border-t py-4 first:border-t-0 last:pb-0">
   <div class="flex flex-wrap items-baseline gap-x-2 gap-y-1">
     <code class="font-mono text-foreground text-sm">{name}</code>
     <span class="text-muted-foreground text-xs"
@@ -77,17 +82,17 @@ const expandable =
   </div>
   {
     description && (
-      <div class="mt-1 text-muted-foreground text-sm" set:text={description} />
+      <Description class="mt-2 text-muted-foreground text-sm" text={description} />
     )
   }
   {
     limits.length > 0 && (
-      <div class="mt-1 text-muted-foreground text-xs">{limits.join(" · ")}</div>
+      <div class="mt-2 text-muted-foreground text-xs">{limits.join(" · ")}</div>
     )
   }
   {
     enumValues && (
-      <div class="mt-1 flex flex-wrap items-center gap-1 text-xs">
+      <div class="mt-2 flex flex-wrap items-center gap-1.5 text-xs">
         <span class="text-muted-foreground">Allowed:</span>
         {enumValues.map((value) => (
           <code class="rounded bg-muted px-1 py-0.5 text-foreground">
@@ -99,12 +104,12 @@ const expandable =
   }
   {
     expandable && (
-      <details class="mt-2" open={expandAll}>
+      <details class="mt-3" open={expandAll}>
         <summary class="cursor-pointer select-none text-accent text-xs hover:underline">
           <span class="[details[open]>summary_&]:hidden">Show properties</span>
           <span class="hidden [details[open]>summary_&]:inline">Hide properties</span>
         </summary>
-        <div class="mt-2 border-border border-l pl-4">
+        <div class="mt-3 border-border border-l pl-4">
           <SchemaTable
             schema={schema}
             schemas={schemas}

package/src/components/openapi/description.ts

@@ -0,0 +1,91 @@
+import { Marked } from "marked";
+
+/**
+ * Render a spec description as Markdown.
+ *
+ * An OpenAPI `description` is Markdown by specification — "CommonMark syntax MAY be used for rich
+ * text representation" — but the reference components printed it with `set:text`, so a schema
+ * property, parameter or header showed its source. On a spec generated from code docstrings that
+ * is most of them: `**Inline**` printed its asterisks, `` `apiKey` `` printed its backticks, and
+ * because HTML collapses newlines every paragraph and list ran together into one wall of text.
+ * The operation description does not have this problem — it is emitted into the MDX body and goes
+ * through the full pipeline — which is what made the difference visible page by page.
+ *
+ * `marked` rather than the site's own Markdown pipeline: the pipeline is async, plugin-laden and
+ * built for whole documents, while these are thousands of short strings per build — a large
+ * reference renders tens of thousands of them. `marked` is synchronous, already a dependency,
+ * and already how the Ask AI island renders model Markdown.
+ */
+const TABLE = /<table>[\s\S]*?<\/table>/gu;
+
+/**
+ * An href the author can have meant: an absolute URL, a site-root path, a fragment or a mailto.
+ * A bare relative href in a spec description has never yet been a link, and the lookahead keeps
+ * `//host` out: that is a scheme-relative URL to another origin, not a site-root path.
+ */
+const DELIBERATE_HREF = /^(?:https?:|mailto:|#|\/(?!\/))/iu;
+
+/** The source text of a demoted construct, made safe for `set:html`. */
+const escapeHtml = (text: string): string =>
+  text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+
+const markdown = new Marked({
+  // `breaks` is deliberately NOT set, unlike the Ask AI island. Docstring prose is hard-wrapped at
+  // 72 or 79 columns, so honouring single newlines would break every sentence mid-flow at exactly
+  // the width the source file happened to use.
+  breaks: false,
+  gfm: true,
+  hooks: {
+    // GFM tables reach the page through `set:html`, so they miss the `blume:table-wrap` plugin
+    // that gives every table in the body its scroll frame — and a description sits in a column
+    // narrower than the body. Wrapping here reuses that frame rather than reinventing it; the
+    // regex is safe because a table cannot nest and this HTML is `marked`'s own output.
+    postprocess: (html: string) =>
+      html.replaceAll(
+        TABLE,
+        (table) => `<div class="blume-table-scroll" tabindex="0">${table}</div>`
+      ),
+  },
+  renderer: {
+    // Raw HTML is escaped rather than passed through. A description is data lifted out of a spec
+    // file, frequently generated upstream from source comments, and it is interpolated with
+    // `set:html`; the island that renders model output runs DOMPurify over it for the same
+    // reason, which needs a DOM and so is unavailable in a component that renders on the server.
+    html: ({ text }: { text: string }) => escapeHtml(text),
+    // An image is held to the same href policy as a link, for the same reason: `![x](src)` is the
+    // one Markdown construct that fetches a resource, and a `javascript:` or relative source in a
+    // description is notation rather than a picture.
+    image: ({ href, raw }: { href: string; raw: string }) =>
+      DELIBERATE_HREF.test(href) ? false : escapeHtml(raw),
+    // A link is emitted only when the author clearly meant one; anything else keeps its source
+    // text verbatim. Two failures drove this, and both are prose that was never Markdown.
+    //
+    // GFM autolinks a BARE url (`raw === href`), and a spec description is full of EXAMPLE hosts
+    // — `https://myorg.my.salesforce.com`, `https://yourstore.myshopify.com`. Each became an
+    // anchor pointing at a host that does not exist and was never meant to be visited.
+    //
+    // Worse, regex and format notation reads as link syntax. Debezium's own wording for a column
+    // list is `schemaName[.]tableName[.](columnName1|columnName2)`, in which `[.](columnName1|
+    // columnName2)` is EXACTLY `[text](href)` — 48 pages of one reference linked to a path made
+    // of that notation.
+    // Rendering the demoted case as `raw` rather than as `text` is what keeps that intact: the
+    // text alone is `.`, so emitting it would silently delete the rest of the notation.
+    //
+    // The test for "meant one" is the href (see `DELIBERATE_HREF`) plus the shape of the source:
+    // an author-written link starts with `[` (inline or reference style) or `<` (an angle
+    // autolink). A GFM bare autolink never does — `https://…`, `www.…` or an email — and
+    // comparing `raw` to `href` is not enough to catch it, because marked prefixes the missing
+    // `http://` or `mailto:` for the last two, so the two strings differ exactly as they would
+    // for a deliberate link.
+    link({ href, raw }: { href: string; raw: string }) {
+      const deliberate =
+        DELIBERATE_HREF.test(href) &&
+        (raw.startsWith("[") || raw.startsWith("<"));
+      return deliberate ? false : escapeHtml(raw);
+    },
+  },
+});
+
+/** `description` rendered to HTML, or an empty string when there is nothing to render. */
+export const descriptionHtml = (description: string | undefined): string =>
+  description?.trim() ? markdown.parse(description, { async: false }) : "";

package/src/core/config-input.ts

@@ -895,6 +895,16 @@ export interface AnalyticsScript {
 
 /** Analytics providers. Configure one, several, or none. */
 export interface AnalyticsConfig {
+  /**
+   * Cloudflare Web Analytics, for a site Cloudflare doesn't proxy (manual
+   * setup). Not needed on a proxied zone with automatic RUM enabled — that
+   * injects the beacon at the edge, and configuring it here too would count
+   * every pageview twice.
+   */
+  cloudflare?: {
+    /** Site token from the Web Analytics JS snippet (`data-cf-beacon`). */
+    token: string;
+  };
   /** PostHog product analytics. */
   posthog?: {
     /** API host (for self-hosted / EU). Defaults to PostHog cloud. */

package/src/core/i18n.ts

@@ -48,8 +48,19 @@ export const resolveFallbackLocale = (
   return i18n.fallbackLocale ?? i18n.defaultLocale;
 };
 
+/**
+ * The slice of the i18n settings URL routing reads. `ResolvedI18nConfig` and
+ * the `blume:data` runtime shape both satisfy it, so route helpers serve the
+ * Node-side graph and the rendered page alike.
+ */
+export interface LocaleRouting {
+  defaultLocale: string;
+  hideDefaultLocalePrefix: boolean;
+  locales: { code: string }[];
+}
+
 /** URL prefix for a locale: `""` for the hidden default, else `/<code>`. */
-export const localePrefix = (code: string, i18n: ResolvedI18nConfig): string =>
+export const localePrefix = (code: string, i18n: LocaleRouting): string =>
   code === i18n.defaultLocale && i18n.hideDefaultLocalePrefix ? "" : `/${code}`;
 
 /**
@@ -59,7 +70,7 @@ export const localePrefix = (code: string, i18n: ResolvedI18nConfig): string =>
 export const localizeRoute = (
   logicalRoute: string,
   code: string,
-  i18n: ResolvedI18nConfig
+  i18n: LocaleRouting
 ): string => {
   const prefix = localePrefix(code, i18n);
   if (!prefix) {

package/src/core/links.ts

@@ -7,6 +7,8 @@ import {
   isRelativeImageTarget,
   resolveRelativeImage,
 } from "./content-assets.ts";
+import type { LocaleRouting } from "./i18n.ts";
+import { localizeLinkPath } from "./locale-links.ts";
 import { gradeExternal, probeAll } from "./probe.ts";
 import type {
   ContentGraph,
@@ -78,6 +80,8 @@ interface LinkContext {
   /** Servable routes outside the graph (custom pages, generated routes); their
    * headings are unknown, so anchors there are accepted unchecked. */
   extraRoutes: Set<string>;
+  /** Locale routing, when the site is multi-locale; drives served-route resolution. */
+  i18n: LocaleRouting | null;
   publicDir: string | null;
   /** Normalized `redirect.from` paths — valid targets that resolve at runtime. */
   redirects: Set<string>;
@@ -189,6 +193,30 @@ const checkAnchor = (
   };
 };
 
+/**
+ * The route a link on `page` actually lands on. Rendered under a prefixed
+ * locale, a root-relative link moves into that locale when the localized route
+ * is served — a real translation (whose own headings then answer the anchor
+ * check) or a fallback page (accepted unchecked via `extraRoutes`) — exactly as
+ * `LocaleLinks.astro` rewrites it at render time. Otherwise the authored route
+ * stands.
+ */
+const servedRoute = (
+  authored: string,
+  page: PageRecord,
+  ctx: LinkContext
+): string =>
+  ctx.i18n
+    ? localizeLinkPath(authored, {
+        basePath: ctx.basePath,
+        i18n: ctx.i18n,
+        locale: page.locale,
+        routes: {
+          has: (route) => ctx.routes.has(route) || ctx.extraRoutes.has(route),
+        },
+      })
+    : authored;
+
 /** Validate a resolved internal path: asset, route, then optional anchor. */
 const checkPathLink = (
   resolved: string,
@@ -204,7 +232,8 @@ const checkPathLink = (
   // relative link already resolved against the based `page.route`). A real
   // route always wins over the asset-extension heuristic, so a dotted route
   // (e.g. `/releases/v1.0`) isn't misread as a missing asset.
-  const route = toRoute(withBasePath(ctx.basePath, resolved));
+  const authoredRoute = toRoute(withBasePath(ctx.basePath, resolved));
+  const route = servedRoute(authoredRoute, page, ctx);
   if (ctx.routes.has(route)) {
     return fragment ? checkAnchor(route, fragment, site, ctx, via) : null;
   }
@@ -374,6 +403,8 @@ export const validateLinks = async (
      * full-route-set resolution in `nav-diagnostics.ts`/`generateRuntime`.
      */
     extraRoutes?: string[];
+    /** Locale routing when i18n is on; links then resolve into the page's locale. */
+    i18n?: LocaleRouting | null;
     publicDir: string | null;
     checkExternal?: boolean;
     /** Configured redirects; their `from` paths count as valid link targets. */
@@ -385,6 +416,7 @@ export const validateLinks = async (
     anchors: buildAnchorIndex(graph.pages),
     basePath,
     extraRoutes: new Set((options.extraRoutes ?? []).map(toRoute)),
+    i18n: options.i18n ?? null,
     publicDir: options.publicDir,
     redirects: new Set(
       (options.redirects ?? []).map((redirect) =>

package/src/core/locale-links.ts

@@ -0,0 +1,163 @@
+import {
+  isInternalPath,
+  normalizePath,
+  stripBasePath,
+  withBasePath,
+} from "./base-path.ts";
+import { localePrefix, localizeRoute } from "./i18n.ts";
+import type { LocaleRouting } from "./i18n.ts";
+
+/**
+ * Locale-aware resolution of content links.
+ *
+ * Authors write internal links as if mounted at the default locale's root
+ * (`[x](/guide)`, `<Card href="/guide">`), and translated pages are usually
+ * copies of the source with the same links — so read on `/fr/…`, a link would
+ * otherwise drop the reader back into the default language. These helpers move
+ * such a link to the reader's locale (`/fr/guide`) when that route is served
+ * (a real translation or a materialized fallback page), and leave it alone
+ * otherwise: an explicit cross-locale link (`/de/guide`), a custom `.astro`
+ * page or generated route that has no per-locale variant, or a missing
+ * translation on a site with fallbacks disabled all keep their authored
+ * target rather than pointing at a 404.
+ *
+ * The rewrite runs at render time (`components/layout/LocaleLinks.astro`)
+ * because content is compiled once per file but served per route: a fallback
+ * route renders the fallback locale's file under the missing locale's URL, and
+ * a shared `page.$.mdx` renders under every locale. The link checker applies
+ * the same resolution so anchors are validated against the page a reader lands
+ * on.
+ */
+
+/** A route set, as the runtime (`Set`) or the checker (a predicate) sees it. */
+export interface RouteSet {
+  has: (route: string) => boolean;
+}
+
+export interface LocalizeLinkOptions {
+  /** Site-wide route mount point (`""` or `/seg`); routes carry it. */
+  basePath: string;
+  i18n: LocaleRouting;
+  /** Locale of the page the link is rendered on. */
+  locale: string;
+  /** Every served route, base-prefixed like `path` (no `deployment.base`). */
+  routes: RouteSet;
+}
+
+/**
+ * Mirrors the asset heuristic in `markdown/base-links.ts`: a path whose final
+ * segment carries a file extension is a `public/` asset (or a raw `.md` twin),
+ * served at the site root and never localized.
+ */
+const ASSET_PATH = /\.[a-z0-9]+$/iu;
+
+/** Decode a percent-encoded path for a route lookup; leave junk as-is. */
+const decodePercent = (value: string): string => {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+};
+
+/** Whether `path` (base-stripped) already sits under some locale's prefix. */
+const hasLocalePrefix = (path: string, i18n: LocaleRouting): boolean =>
+  i18n.locales.some((locale) => {
+    const prefix = localePrefix(locale.code, i18n);
+    return prefix !== "" && (path === prefix || path.startsWith(`${prefix}/`));
+  });
+
+/**
+ * Move a base-prefixed, fragment-less internal path into `locale` when that
+ * route is served, else return it unchanged. Idempotent: a path already under
+ * any configured locale prefix is never re-prefixed.
+ */
+export const localizeLinkPath = (
+  path: string,
+  options: LocalizeLinkOptions
+): string => {
+  const { basePath, i18n, locale, routes } = options;
+  if (localePrefix(locale, i18n) === "") {
+    return path;
+  }
+  const rest = normalizePath(stripBasePath(basePath, path));
+  if (hasLocalePrefix(rest, i18n)) {
+    return path;
+  }
+  const localized = withBasePath(basePath, localizeRoute(rest, locale, i18n));
+  // Routes are stored decoded; a browser-copied `/caf%C3%A9` must still find
+  // its translation, but the emitted href keeps the author's encoding.
+  return routes.has(localized) || routes.has(decodePercent(localized))
+    ? localized
+    : path;
+};
+
+export interface LocalizeHrefOptions extends LocalizeLinkOptions {
+  /** `deployment.base` (Astro's `BASE_URL`), layered over `basePath` in hrefs. */
+  deployBase: string;
+}
+
+/**
+ * Localize a rendered `href`: external URLs, relative paths, bare fragments, and
+ * asset links pass through; a root-relative page link keeps its `?query` and
+ * `#fragment` and its `deployment.base` layer around the localized path.
+ */
+export const localizeHref = (
+  href: string,
+  options: LocalizeHrefOptions
+): string => {
+  if (!isInternalPath(href)) {
+    return href;
+  }
+  const suffixAt = href.search(/[#?]/u);
+  const path = suffixAt === -1 ? href : href.slice(0, suffixAt);
+  const suffix = suffixAt === -1 ? "" : href.slice(suffixAt);
+  if (ASSET_PATH.test(path)) {
+    return href;
+  }
+  const based = stripBasePath(options.deployBase, path);
+  const localized = localizeLinkPath(based, options);
+  if (localized === based) {
+    return href;
+  }
+  return `${withBasePath(options.deployBase, localized)}${suffix}`;
+};
+
+/** Every `<a …>` opening tag; `\s` keeps `<abbr>`/`<astro-island>` out. */
+const ANCHOR_TAG = /<a\s[^>]*>/giu;
+/** The tag's `href` attribute, double- or single-quoted. */
+const HREF_ATTR = /(?<attr>\shref=)(?:"(?<dq>[^"]*)"|'(?<sq>[^']*)')/iu;
+
+/**
+ * Rewrite every `<a href>` in rendered content HTML through `rewrite`. Code
+ * blocks are HTML-escaped (`&lt;a`), and island props live on
+ * `<astro-island>`, so neither is touched.
+ */
+export const localizeContentLinks = (
+  html: string,
+  rewrite: (href: string) => string
+): string =>
+  html.replace(ANCHOR_TAG, (tag) =>
+    tag.replace(HREF_ATTR, (_match, attr: string, dq?: string, sq?: string) => {
+      const quote = dq === undefined ? "'" : '"';
+      return `${attr}${quote}${rewrite(dq ?? sq ?? "")}${quote}`;
+    })
+  );
+
+/**
+ * The served route set for `blume:data`'s routes, built once per routes array
+ * (the virtual module is evaluated once, so every page render shares it).
+ */
+const routeSets = new WeakMap<readonly { path: string }[], Set<string>>();
+
+export const routeSetFor = (
+  routes: readonly { path: string }[]
+): Set<string> => {
+  const cached = routeSets.get(routes);
+  if (cached) {
+    return cached;
+  }
+  const built = new Set(routes.map((route) => route.path));
+  routeSets.set(routes, built);
+  return built;
+};

package/src/core/schema.ts

@@ -1220,6 +1220,14 @@ const analyticsScriptSchema = z
   });
 
 const analyticsConfigSchema = z.strictObject({
+  // Cloudflare Web Analytics in manual (JS snippet) mode; the token comes from
+  // the site's snippet in the dashboard. A zone Cloudflare proxies with
+  // automatic RUM injection on needs no config at all.
+  cloudflare: z
+    .strictObject({
+      token: z.string().min(1),
+    })
+    .optional(),
   posthog: z
     .strictObject({
       host: z.string().optional(),

package/src/core/sources/normalize.ts

@@ -280,6 +280,8 @@ interface HeadingScanState {
   fence: FenceState;
   /** 1-based body line of the line being scanned. */
   line: number;
+  /** Where each heading in `headings` sits, index-aligned. */
+  sites: HeadingSite[];
   /** Consecutive paragraph lines — the candidate text for a setext underline. */
   paragraph: string[];
   /** Body line of the first line in `paragraph`. */
@@ -399,23 +401,43 @@ const refDefinitionLabels = (lines: readonly string[]): Set<string> => {
  * regardless of TOC visibility. A heading that is nothing but markers keeps
  * them as literal text, mirroring the renderer.
  */
+/** A scanned heading plus whether its id came from an author pin. */
+interface ScannedHeading {
+  heading: Heading;
+  pinned: boolean;
+}
+
 const toHeading = (
   depth: number,
   raw: string,
   slugger: GithubSlugger,
   isRefDefined: (label: string) => boolean
-): Heading => {
+): ScannedHeading => {
   const unescaped = raw.replaceAll(ESCAPED_PUNCTUATION, "$<char>");
   const markers = parseHeadingMarkers(unescaped, isRefDefined);
   const text = markers.text.trim();
   if (text === "" && (markers.id !== undefined || markers.toc !== undefined)) {
-    return { depth, slug: slugger.slug(unescaped), text: unescaped };
+    return {
+      heading: { depth, slug: slugger.slug(unescaped), text: unescaped },
+      pinned: false,
+    };
   }
   if (markers.id !== undefined) {
     occupySlug(slugger, markers.id);
-    return { depth, slug: markers.id, text };
+    return { heading: { depth, slug: markers.id, text }, pinned: true };
   }
-  return { depth, slug: slugger.slug(text), text };
+  return { heading: { depth, slug: slugger.slug(text), text }, pinned: false };
+};
+
+/** Record a heading and where a trailing marker would be written for it. */
+const pushHeading = (
+  headings: Heading[],
+  state: HeadingScanState,
+  scanned: ScannedHeading,
+  line: number
+): void => {
+  headings.push(scanned.heading);
+  state.sites.push({ line, pinned: scanned.pinned });
 };
 
 /** Record a heading's unescaped trailing `{#id}` so `.mdx` pages can be warned. */
@@ -444,7 +466,12 @@ const scanContentLine = (
   if (atx?.groups) {
     const depth = atx.groups.hashes?.length ?? 1;
     const text = (atx.groups.text ?? "").trim();
-    headings.push(toHeading(depth, text, slugger, isRefDefined));
+    pushHeading(
+      headings,
+      state,
+      toHeading(depth, text, slugger, isRefDefined),
+      state.line
+    );
     noteCurlyMarker(text, state.line, state);
     state.paragraph = [];
     return;
@@ -455,7 +482,14 @@ const scanContentLine = (
     // a multi-line paragraph renders as one heading, soft breaks as spaces.
     const depth = setext.groups.marker?.startsWith("=") ? 1 : 2;
     const text = state.paragraph.join(" ").trim();
-    headings.push(toHeading(depth, text, slugger, isRefDefined));
+    // A setext heading's markers trail its last text line, just above the
+    // underline — that is where a pin is appended.
+    pushHeading(
+      headings,
+      state,
+      toHeading(depth, text, slugger, isRefDefined),
+      state.line - 1
+    );
     noteCurlyMarker(text, state.paragraphStart, state);
     state.paragraph = [];
     return;
@@ -515,6 +549,14 @@ const scanHeadingLine = (
   scanContentLine(line, state, slugger, headings, isRefDefined);
 };
 
+/** Where a heading's text ends in the scanned text, for appending a marker. */
+export interface HeadingSite {
+  /** 1-based line (of the text passed to `scanBody`) that any trailing marker ends. */
+  line: number;
+  /** True when the heading already pins its id with `[#id]`/`{#id}`. */
+  pinned: boolean;
+}
+
 /** Everything one walk over a body yields for the anchor index. */
 export interface BodyScan {
   /**
@@ -527,6 +569,8 @@ export interface BodyScan {
   /** Headings whose trailing `{#id}` marker is unescaped, for `.mdx` pages. */
   curlyMarkers: CurlyMarker[];
   headings: Heading[];
+  /** Index-aligned with `headings`: where each one's markers would go. */
+  sites: HeadingSite[];
 }
 
 /**
@@ -546,6 +590,7 @@ export const scanBody = (body: string): BodyScan => {
     paragraphStart: 0,
     promptDepth: 0,
     promptTag: false,
+    sites: [],
   };
 
   const { lines, offset } = linesWithoutFrontMatter(body);
@@ -568,7 +613,12 @@ export const scanBody = (body: string): BodyScan => {
       anchors.add(id);
     }
   }
-  return { anchors: [...anchors], curlyMarkers: state.curlyMarkers, headings };
+  return {
+    anchors: [...anchors],
+    curlyMarkers: state.curlyMarkers,
+    headings,
+    sites: state.sites,
+  };
 };
 
 export const extractHeadings = (body: string): Heading[] =>