blume 2.2.1 → 2.2.3

package/src/core/project-graph.ts

@@ -14,8 +14,10 @@ import { buildContentGraph } from "./graph.ts";
 import { i18nDiagnostics } from "./i18n.ts";
 import { expandIncludes, hasIncludeStatements } from "./includes.ts";
 import {
-  gitLastModifiedTimes,
+  datePublishedShallowWarning,
+  gitFileDates,
   gitRepositoryRoot,
+  isShallowGitRepository,
   lastModifiedShallowWarning,
   realPath,
   resolveLastModifiedConfig,
@@ -301,6 +303,82 @@ const gitContentRoots = (
     .filter((dir) => isWithin(top, realPath(dir)));
 };
 
+/** Whether a page's front matter dates its publication itself. */
+const hasPublishedDate = (page: PageRecord): boolean =>
+  Boolean(page.meta.date ?? page.meta.changelog?.date);
+
+/**
+ * Fill in each page's git dates — "last updated" under `lastModified: "git"`,
+ * published under `seo.datePublished: "git"` — from one `git log`, and warn
+ * when a shallow clone leaves pages undated. Frontmatter always wins; git
+ * applies to filesystem entries, other sources supply dates on the entry.
+ */
+const applyGitDates = (
+  pages: PageRecord[],
+  sources: readonly ContentSource[],
+  root: string,
+  config: ResolvedConfig
+): Diagnostic[] => {
+  const lastModified = resolveLastModifiedConfig(config.lastModified);
+  const gitModified = lastModified.enabled && lastModified.source === "git";
+  const gitPublished = config.seo.datePublished === "git";
+  if (!(gitModified || gitPublished)) {
+    return [];
+  }
+  const fsPaths = pages
+    .map((page) => page.sourcePath)
+    .filter((path): path is string => path !== undefined);
+  // The git pathspecs must cover where the pages actually live: each local
+  // source's own on-disk root — a filesystem source's `root`, or a staged
+  // local source's tree (an Obsidian vault) — which diverges from the global
+  // `content.root`.
+  const gitRoot = gitRepositoryRoot(root);
+  const contentRoots = gitContentRoots(sources, gitRoot);
+  const gitDates = gitFileDates(root, contentRoots, fsPaths, gitRoot);
+  // Only pages the log could have dated count toward the shallow-clone
+  // warnings — a page outside every covered root stays undated no matter how
+  // deep the clone is, and the warning's suggested fix cannot help it.
+  const datable = pages.filter(
+    (page) =>
+      page.sourcePath &&
+      contentRoots.some((dir) => isWithin(dir, page.sourcePath ?? ""))
+  );
+  const warnings: Diagnostic[] = [];
+  if (gitModified) {
+    for (const page of pages) {
+      if (!page.lastModified && page.sourcePath) {
+        page.lastModified = gitDates.modified.get(page.sourcePath);
+      }
+    }
+    // A shallow CI clone (Vercel, actions/checkout) silently drops most dates;
+    // surface that instead of letting production diverge from local builds.
+    warnings.push(
+      ...lastModifiedShallowWarning(
+        root,
+        datable.filter((page) => !page.lastModified).length
+      )
+    );
+  }
+  if (gitPublished) {
+    // A shallow clone's oldest commit is where it was cut, not where a page
+    // began, so it dates nothing rather than every page wrongly.
+    const shallow = isShallowGitRepository(root);
+    for (const page of pages) {
+      if (!(shallow || hasPublishedDate(page)) && page.sourcePath) {
+        page.published = gitDates.published.get(page.sourcePath);
+      }
+    }
+    if (shallow) {
+      warnings.push(
+        ...datePublishedShallowWarning(
+          datable.filter((page) => !hasPublishedDate(page)).length
+        )
+      );
+    }
+  }
+  return warnings;
+};
+
 /**
  * Run the full core pipeline for a project root: load config, resolve paths,
  * discover content and folder meta, build the graph, and assemble the manifest.
@@ -681,47 +759,9 @@ export const scanProject = async (
       ? allPages.filter((page) => !page.meta.draft)
       : allPages;
 
-  // Resolve "last updated" dates before the graph is built so the manifest
-  // (which shares these page objects) picks them up. Frontmatter always wins;
-  // git applies to filesystem entries, other sources supply dates on the entry.
-  const lastModified = resolveLastModifiedConfig(config.lastModified);
-  const lastModifiedWarnings: Diagnostic[] = [];
-  if (lastModified.enabled && lastModified.source === "git") {
-    const fsPaths = pages
-      .map((page) => page.sourcePath)
-      .filter((path): path is string => path !== undefined);
-    // The git pathspecs must cover where the pages actually live: each local
-    // source's own on-disk root — a filesystem source's `root`, or a staged
-    // local source's tree (an Obsidian vault) — which diverges from the global
-    // `content.root`.
-    const gitRoot = gitRepositoryRoot(context.root);
-    const contentRoots = gitContentRoots(sources, gitRoot);
-    const gitTimes = gitLastModifiedTimes(
-      context.root,
-      contentRoots,
-      fsPaths,
-      gitRoot
-    );
-    for (const page of pages) {
-      if (!page.lastModified && page.sourcePath) {
-        page.lastModified = gitTimes.get(page.sourcePath);
-      }
-    }
-    // A shallow CI clone (Vercel, actions/checkout) silently drops most dates;
-    // surface that instead of letting production diverge from local builds.
-    // Only pages the log could have dated count — a page outside every covered
-    // root stays undated no matter how deep the clone is, and the warning's
-    // suggested fix cannot help it.
-    const undated = pages.filter(
-      (page) =>
-        page.sourcePath &&
-        !page.lastModified &&
-        contentRoots.some((dir) => isWithin(dir, page.sourcePath ?? ""))
-    ).length;
-    lastModifiedWarnings.push(
-      ...lastModifiedShallowWarning(context.root, undated)
-    );
-  }
+  // Resolve "last updated" and publication dates before the graph is built so
+  // the manifest (which shares these page objects) picks them up.
+  const gitDateWarnings = applyGitDates(pages, sources, context.root, config);
 
   // Custom `.astro` pages and the generated changelog index aren't content
   // pages, so name them for navigation: a `/changelog` tab should open the
@@ -791,7 +831,7 @@ export const scanProject = async (
       ...graph.diagnostics,
       ...i18nWarnings,
       ...versionWarnings,
-      ...lastModifiedWarnings,
+      ...gitDateWarnings,
       ...svgWarnings,
       ...publicOpenApiDiagnostics(config, context.root),
       ...redirectPageDiagnostics(

package/src/core/schema.ts

@@ -207,10 +207,9 @@ const changelogMetaSchema = z.strictObject({
 
 /**
  * A post author: a bare name/handle, or an object with a name plus optional
- * avatar/URL. The object is passthrough so richer author metadata (social
- * handles, roles) survives untouched — Blume doesn't render authors yet, so
- * this exists to preserve the field (common on blog/changelog pages) rather
- * than have a strict scan reject it.
+ * avatar/URL. Blume credits the name and URL in the page's JSON-LD; the object
+ * is passthrough so richer author metadata (social handles, roles) survives
+ * untouched rather than have a strict scan reject it.
  */
 const authorSchema = z.union([
   z.string(),
@@ -254,7 +253,7 @@ const pageMetaBaseSchema = z.strictObject({
     .optional(),
   /** How this page's endpoint authenticates, over the site's `api.auth`. */
   authMethod: z.enum(AUTH_METHODS).optional(),
-  /** Post author(s) for blog/changelog content; preserved, not yet rendered. */
+  /** Post author(s) for blog/changelog content, credited in JSON-LD. */
   authors: z.union([authorSchema, z.array(authorSchema)]).optional(),
   changelog: changelogMetaSchema.optional(),
   /** Publish date for feed-backed content like blog/changelog. */
@@ -1609,8 +1608,9 @@ const ogConfigSchema = z.strictObject({
   /**
    * Generate a per-page Open Graph image. Defaults to on once a deployment
    * site URL is known (set or auto-detected) and off otherwise, since
-   * `og:image` must be absolute to be useful to crawlers — resolved in
-   * `loadConfig`. An explicit value here always wins.
+   * `og:image` must be absolute to be useful to crawlers, and off when `image`
+   * sets a default every page would show instead — resolved in `loadConfig`.
+   * An explicit value here always wins.
    */
   enabled: z.boolean().optional(),
   /**
@@ -1619,6 +1619,13 @@ const ogConfigSchema = z.strictObject({
    * families are fetched from Google Fonts at build.
    */
   fonts: z.array(ogFontSchema).optional(),
+  /**
+   * Default social image for pages without their own `seo.image`, in place of
+   * the generated card: one path or URL, or one per locale (resolved like any
+   * localizable label). A root-relative path is served under the deployment
+   * base.
+   */
+  image: localizableLabelSchema.optional(),
   /**
    * Local SVG used in the generated card instead of the site logo; `false`
    * renders the card without any brand mark.
@@ -1728,6 +1735,29 @@ type SoftwareResolved = z.output<typeof softwareConfigSchema>;
 
 /** Discoverability features: OG images, feeds, sitemap, structured data. */
 const seoConfigFields = {
+  /**
+   * Date pages without a front matter `date` by the git commit that added
+   * their source file, following exact renames. Off by default.
+   */
+  datePublished: z.union([z.literal(false), z.literal("git")]).default(false),
+  /**
+   * Structured-data entities shared with a parent site (`example.com/docs`),
+   * referenced by absolute `@id` instead of defined again (see `seo/jsonld.ts`).
+   */
+  jsonLd: z
+    .strictObject({
+      /** Credited on pages without their own `authors`. */
+      author: z.strictObject({ "@id": z.url() }).optional(),
+      /** The Organization's `@id`; `seo.organization` still adds its details. */
+      organizationId: z.url().optional(),
+      /** Every page's publisher, over the Organization. */
+      publisher: z.strictObject({ "@id": z.url() }).optional(),
+      /** Emit the WebSite node. Defaults to true unless `websiteId` is set. */
+      website: z.boolean().optional(),
+      /** The WebSite's `@id`, which every page names as `isPartOf`. */
+      websiteId: z.url().optional(),
+    })
+    .prefault({}),
   /**
    * Meta tags written into every page's head, name to content: site
    * verification, `theme-color`, and anything else Blume has no setting for.
@@ -1754,8 +1784,16 @@ const seoConfigFields = {
   /** Generate robots.txt (with a Sitemap reference when available). */
   robots: z.boolean().default(true),
   rss: rssConfigSchema.prefault({}),
-  /** Generate sitemap.xml (requires deployment.site). */
-  sitemap: z.boolean().default(true),
+  /**
+   * Generate sitemap.xml (requires deployment.site). `{ alternates: true }`
+   * also lists each page's translations as hreflang links.
+   */
+  sitemap: z
+    .union([
+      z.boolean(),
+      z.strictObject({ alternates: z.boolean().default(false) }),
+    ])
+    .default(true),
   /** The documented product, as a homepage `SoftwareApplication` node. */
   software: z
     .union([z.boolean(), softwareConfigSchema])

package/src/core/types.ts

@@ -256,6 +256,11 @@ export interface PageRecord {
   unknownProps?: ElementUse[];
   /** Resolved "last updated" ISO date, when the feature is enabled. */
   lastModified?: string;
+  /**
+   * The git commit that added the source file, as an ISO date, when
+   * `seo.datePublished` is `"git"` and front matter carries no `date`.
+   */
+  published?: string;
   /** Absolute paths of files this page `<include>`s, transitively. Drives the
    * dev-server invalidation edge from a partial to the pages that splice it. */
   includes?: string[];
@@ -484,6 +489,11 @@ export interface RouteManifestEntry {
   aiExclude?: boolean;
   /** Resolved "last updated" ISO date, when the feature is enabled. */
   lastModified?: string;
+  /**
+   * The git commit that added the source file, as an ISO date, when
+   * `seo.datePublished` is `"git"` and front matter carries no `date`.
+   */
+  published?: string;
 }
 
 /** The generated runtime contract between core and the Astro project. */

package/src/deploy/sitemap.ts

@@ -14,6 +14,7 @@ import {
 import { isHiddenPage } from "../core/hidden-pages.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { siteRoot } from "../core/site-url.ts";
+import type { RouteAlternate } from "../core/types.ts";
 
 /**
  * Astro's reserved error routes. A user-authored override (`pages/404.astro`,
@@ -79,13 +80,95 @@ export const describeSitemapFiles = (files: readonly SitemapFile[]): string =>
 const URLS_PER_FILE = 50_000;
 
 const renderUrlset = (
-  urls: string[]
+  urls: string[],
+  alternatesEnabled: boolean
 ): string => `<?xml version="1.0" encoding="UTF-8"?>
-<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"${alternatesEnabled ? ' xmlns:xhtml="http://www.w3.org/1999/xhtml"' : ""}>
 ${urls.join("\n")}
 </urlset>
 `;
 
+/**
+ * The content pages crawlers may index under their own URL: drafts, hidden,
+ * `noindex` (the page's or its archived version's), and error pages can't, nor
+ * can a page whose own `seo.canonical` names another URL.
+ */
+const indexablePages = (
+  project: BlumeProject
+): BlumeProject["graph"]["pages"] => {
+  const deployBase = normalizeBasePath(project.config.deployment.options.base);
+  // A non-empty version always names a configured archived entry — that is
+  // the only way detection assigns one.
+  const noindexVersions = new Set(
+    (project.config.versions?.archived ?? []).flatMap((version) =>
+      version.noindex ? [version.id] : []
+    )
+  );
+  return project.graph.pages.filter(
+    (page) =>
+      !page.meta.draft &&
+      !isHiddenPage(page, project.graph) &&
+      !page.meta.seo.noindex &&
+      !noindexVersions.has(page.version) &&
+      !ERROR_ROUTES.has(page.route) &&
+      !canonicalElsewhere(
+        page.meta.seo.canonical,
+        mountBasePath(deployBase, page.route)
+      )
+  );
+};
+
+/**
+ * The content pages the sitemap lists: the indexable ones, less archived-version
+ * pages whose canonical points at a still-existing latest equivalent —
+ * listing a URL whose canonical says "index the other page" invites the
+ * noindexed-page-in-sitemap incoherence Docusaurus is known for. A page that
+ * exists only in an archived version stays listed (self-canonical), and a
+ * page's own `seo.canonical` wins over the version's default, as it does in
+ * the page head (see `canonicalElsewhere`).
+ */
+const listedPages = (project: BlumeProject): BlumeProject["graph"]["pages"] => {
+  const latestVersions = new Set(
+    (project.config.versions?.archived ?? []).flatMap((version) =>
+      version.canonical === "latest" ? [version.id] : []
+    )
+  );
+  const currentKeys = new Set(
+    project.graph.pages.flatMap((page) =>
+      page.version === "" ? [`${page.versionKey}\u0000${page.locale}`] : []
+    )
+  );
+  return indexablePages(project).filter(
+    (page) =>
+      !(
+        latestVersions.has(page.version) &&
+        !page.meta.seo.canonical &&
+        currentKeys.has(`${page.versionKey}\u0000${page.locale}`)
+      )
+  );
+};
+
+/**
+ * Each route's hreflang set, keyed by route: its indexable translations. The
+ * page head links it, and so does the sitemap under `seo.sitemap.alternates`,
+ * so the two never disagree, and neither points crawlers at a page they're
+ * told not to index. A page that can't be indexed joins no set — except an
+ * i18n fallback copy, which links the translations it stands in for.
+ */
+export const hreflangAlternates = (
+  project: BlumeProject
+): Map<string, RouteAlternate[]> => {
+  const indexable = new Set(indexablePages(project).map((page) => page.route));
+  return new Map(
+    project.manifest.routes.map((route) => [
+      route.path,
+      route.fallback || indexable.has(route.path)
+        ? route.alternates.filter((alternate) => indexable.has(alternate.path))
+        : [],
+    ])
+  );
+};
+
 /**
  * Build the sitemap files from the route manifest plus the routes the manifest
  * can't see: custom `.astro` pages (most importantly a custom landing `/`) and
@@ -112,43 +195,38 @@ export const buildSitemapFiles = (
   // top of every one, even a route whose first segment matches it: under base
   // `/guides`, `guides/setup.md` is served at `/guides/guides/setup`.
   const deployBase = normalizeBasePath(project.config.deployment.options.base);
-
-  // Archived-version pages leave the sitemap when the version is noindexed,
-  // or when their canonical points at a still-existing latest equivalent —
-  // listing a URL whose canonical says "index the other page" invites the
-  // noindexed-page-in-sitemap incoherence Docusaurus is known for. A page
-  // that exists only in an archived version stays listed (self-canonical),
-  // and a page's own `seo.canonical` wins over the version's default, as it
-  // does in the page head (see `canonicalElsewhere`).
-  const { versions } = project.config;
-  const archivedById = new Map(
-    (versions?.archived ?? []).map((version) => [version.id, version])
-  );
-  const currentKeys = versions
-    ? new Set(
-        project.graph.pages.flatMap((page) =>
-          page.version === "" ? [`${page.versionKey}\u0000${page.locale}`] : []
-        )
-      )
-    : null;
-  const archivedExcluded = (page: (typeof project.graph.pages)[number]) => {
-    if (!page.version) {
-      return false;
+  const alternatesEnabled =
+    project.config.seo.sitemap !== true &&
+    project.config.seo.sitemap.alternates;
+  const hreflang = alternatesEnabled ? hreflangAlternates(project) : null;
+  // A page's translations as `xhtml:link`s, plus `x-default` at the default
+  // locale's — the same set the page head links, for pages in 2+ locales.
+  const alternateTags = (route: string): string => {
+    const alternates = hreflang?.get(route) ?? [];
+    if (alternates.length < 2) {
+      return "";
     }
-    // A non-empty version always names a configured archived entry — that is
-    // the only way detection assigns one.
-    const archived = archivedById.get(page.version);
-    return Boolean(
-      archived?.noindex ||
-      (archived?.canonical === "latest" &&
-        !page.meta.seo.canonical &&
-        currentKeys?.has(`${page.versionKey}\u0000${page.locale}`))
+    const defaultPage = alternates.find(
+      (entry) => entry.locale === project.config.i18n?.defaultLocale
     );
+    const links = defaultPage
+      ? [...alternates, { ...defaultPage, locale: "x-default" }]
+      : alternates;
+    return links
+      .map(
+        (entry) =>
+          `<xhtml:link rel="alternate" hreflang="${escapeXml(entry.locale)}" href="${escapeXml(encodeURI(`${base}${mountBasePath(deployBase, entry.path)}`))}"/>`
+      )
+      .join("");
   };
 
   const seen = new Set<string>();
   const urls: string[] = [];
-  const pushUrl = (route: string, lastModified?: string): void => {
+  const pushUrl = (
+    route: string,
+    lastModified?: string,
+    alternates = ""
+  ): void => {
     // `<loc>` must be a well-formed, XML-escaped URL: percent-encode the path,
     // then escape XML metacharacters (notably `&`) so a route like
     // `/Tips & Tricks` doesn't produce invalid XML that gets the whole sitemap
@@ -158,21 +236,16 @@ export const buildSitemapFiles = (
       return;
     }
     seen.add(loc);
-    urls.push(`  <url><loc>${loc}</loc>${lastmodTag(lastModified)}</url>`);
+    urls.push(
+      `  <url><loc>${loc}</loc>${lastmodTag(lastModified)}${alternates}</url>`
+    );
   };
-  for (const page of project.graph.pages) {
-    const served = mountBasePath(deployBase, page.route);
-    if (
-      page.meta.draft ||
-      isHiddenPage(page, project.graph) ||
-      page.meta.seo.noindex ||
-      ERROR_ROUTES.has(page.route) ||
-      archivedExcluded(page) ||
-      canonicalElsewhere(page.meta.seo.canonical, served)
-    ) {
-      continue;
-    }
-    pushUrl(served, page.lastModified);
+  for (const page of listedPages(project)) {
+    pushUrl(
+      mountBasePath(deployBase, page.route),
+      page.lastModified,
+      alternateTags(page.route)
+    );
   }
   // Custom `.astro` pages and the generated changelog index mount outside
   // `basePath` (they're injected at their pattern — see `blumeIntegration`), so
@@ -192,7 +265,9 @@ export const buildSitemapFiles = (
   urls.sort();
 
   if (urls.length <= URLS_PER_FILE) {
-    return [{ name: "sitemap.xml", xml: renderUrlset(urls) }];
+    return [
+      { name: "sitemap.xml", xml: renderUrlset(urls, alternatesEnabled) },
+    ];
   }
 
   const chunks: SitemapFile[] = [];
@@ -201,7 +276,10 @@ export const buildSitemapFiles = (
     const name = `sitemap-${chunks.length + 1}.xml`;
     chunks.push({
       name,
-      xml: renderUrlset(urls.slice(start, start + URLS_PER_FILE)),
+      xml: renderUrlset(
+        urls.slice(start, start + URLS_PER_FILE),
+        alternatesEnabled
+      ),
     });
     // Chunks sit next to sitemap.xml, so their URLs layer the same deployment
     // base robots.txt uses for the index.

package/src/openapi/proxy.ts

@@ -196,7 +196,11 @@ const followUpstream = async (args: {
   signal: AbortSignal;
   url: URL;
 }): Promise<Response> => {
-  const response = await args.fetchImpl(args.url, {
+  // Called bare, never as `args.fetchImpl(...)`: that would run the global
+  // `fetch` with `this` set to `args`, which Node allows and workerd rejects
+  // as an "Illegal invocation".
+  const { fetchImpl } = args;
+  const response = await fetchImpl(args.url, {
     body: args.body,
     headers: args.headers,
     method: args.method,

package/src/search/documents.ts

@@ -11,6 +11,8 @@ import type {
   DownlevelWalk,
   MdastNode as DownlevelNode,
 } from "../ai/component-markdown.ts";
+import { relativeLinkRewriter } from "../ai/relative-links.ts";
+import type { RelativeLinkRewriter } from "../ai/relative-links.ts";
 import { projectComponentSerializers } from "../ai/serializers.ts";
 import { applyAudienceVisibility } from "../ai/visibility.ts";
 import type { VisibilityAudience } from "../ai/visibility.ts";
@@ -399,17 +401,20 @@ interface BuildOptions {
 
 /**
  * Read a page's body and reduce it per the extraction options. The
- * `"markdown"` body is agent-facing, so its components are downleveled in the
- * source with the serializers every agent surface uses (front matter in scope
- * for prop expressions). The plain body is parsed as written and walked, with
- * the same serializers applied per component on the way, so the index reads a
- * `<Card>` or `<TypeTable>` as the text it shows.
+ * `"markdown"` body, the one `rewriteLinks` comes with, is agent-facing: its
+ * page links are rewritten, then its components downleveled in the source
+ * with the serializers every agent surface uses (front matter in scope for
+ * prop expressions), in the order llms-full.txt takes. The plain body is
+ * parsed as written and walked, with the same serializers applied per
+ * component on the way, so the index reads a `<Card>` or `<TypeTable>` as
+ * the text it shows.
  */
 const pageBody = async (
   project: BlumeProject,
   page: PageRecord | undefined,
-  options: Pick<BuildOptions, "audience" | "content"> | undefined,
-  components: Record<string, ComponentMarkdown>
+  options: Pick<BuildOptions, "audience"> | undefined,
+  components: Record<string, ComponentMarkdown>,
+  rewriteLinks: RelativeLinkRewriter | undefined
 ): Promise<string> => {
   if (!page) {
     return "";
@@ -419,8 +424,12 @@ const pageBody = async (
     parsed.content,
     options?.audience ?? "web"
   );
-  if (options?.content === "markdown") {
-    return downlevelComponents(visible.trim(), components, parsed.data);
+  if (rewriteLinks) {
+    return downlevelComponents(
+      rewriteLinks(visible, page).trim(),
+      components,
+      parsed.data
+    );
   }
   return toPlainText(visible, page.format, {
     downlevel: {
@@ -460,7 +469,9 @@ const rankingFields = (
  * same serializers the `.md` mirror, llms-full.txt and MCP `get_page` use: a
  * page whose body is a `<CardGroup>` of `<Card>`s is prose to a reader and bare
  * JSX to anything reading the source, and section landing pages are exactly
- * that shape.
+ * that shape. Its page links point at the pages they mean, as they do there
+ * too, as the routes the assistant's snapshot keys those pages by (see
+ * `relativeLinkRewriter`'s `assistant`): the model cites the links it reads.
  *
  * `audience` resolves `<Visibility>` blocks before extraction: `"web"`
  * (default) keeps web-only content and drops agents-only blocks — the site
@@ -518,6 +529,12 @@ export const buildSearchDocuments = async (
   // Built once — `downlevelComponents` rebuilds its registry per call
   // otherwise.
   const components = projectComponentSerializers(project);
+  // The `"markdown"` body is the assistant's: the model cites the links it
+  // reads, so a page link points at the page the snapshot holds.
+  const rewriteLinks =
+    options?.content === "markdown"
+      ? relativeLinkRewriter(project, { assistant: true })
+      : undefined;
 
   // A page in no sidebar group falls under the "Docs" section, in its own
   // language: the label is a UI string, resolved once per locale.
@@ -542,7 +559,13 @@ export const buildSearchDocuments = async (
   return await Promise.all(
     indexable.map(async (route) => {
       const page = pageById.get(route.id);
-      const body = await pageBody(project, page, options, components);
+      const body = await pageBody(
+        project,
+        page,
+        options,
+        components,
+        rewriteLinks
+      );
       const tags = page?.meta?.search?.tags;
       const crumb = crumbs.get(route.path);
       const facets = page ? pageFacets(page, project.config) : undefined;