blume 1.0.4 → 1.1.1

package/src/components/openapi/security.ts

@@ -0,0 +1,201 @@
+/**
+ * Security (authorization) resolution for the OpenAPI components. An operation
+ * enforces its own `security` when declared — an empty array explicitly makes
+ * it public — and inherits the document's root `security` otherwise. Within the
+ * resolved list, each requirement object is one way to authorize (OR between
+ * entries), and every scheme named inside a single requirement is needed
+ * together (AND). Pure and dependency-free like `helpers.ts`, so it runs in the
+ * browser build with no server-only imports.
+ */
+
+/** A permissive view of an OpenAPI security scheme — only the fields we render. */
+export interface SecuritySchemeLike {
+  type?: string;
+  description?: string;
+  /** `apiKey`: the parameter name the key is sent as. */
+  name?: string;
+  /** `apiKey`: where the key goes — `header`, `query`, or `cookie`. */
+  in?: string;
+  /** `http`: the HTTP auth scheme, e.g. `bearer` or `basic`. */
+  scheme?: string;
+  /** `http` bearer: a hint at the token format, e.g. `JWT`. */
+  bearerFormat?: string;
+  [key: string]: unknown;
+}
+
+/** One security requirement: scheme name -> required scopes (empty outside OAuth). */
+export type SecurityRequirementLike = Record<string, string[]>;
+
+/** A scheme resolved out of `components.securitySchemes`, with its scopes. */
+export interface ResolvedScheme {
+  /** The scheme's component name, e.g. `bearerAuth`. */
+  key: string;
+  /** The scheme object; undefined when the requirement names an unknown one. */
+  scheme?: SecuritySchemeLike;
+  scopes: string[];
+}
+
+/** The security state one operation renders. */
+export interface OperationSecurity {
+  /** Ways to authorize (OR); every scheme within one entry is required (AND). */
+  alternatives: ResolvedScheme[][];
+  /** True when an empty requirement also allows unauthenticated calls. */
+  optional: boolean;
+}
+
+/**
+ * The requirement list an operation actually enforces: its own `security` when
+ * declared — the OpenAPI override rule, where `[]` removes the default and
+ * makes the operation public — else the document's root `security`.
+ */
+export const effectiveSecurity = (
+  operation?: SecurityRequirementLike[],
+  document?: SecurityRequirementLike[]
+): SecurityRequirementLike[] => operation ?? document ?? [];
+
+/**
+ * Resolve requirement names against `components.securitySchemes`. A name with
+ * no matching component is kept (with `scheme` undefined) so an inconsistent
+ * spec still renders the requirement instead of silently dropping it. An empty
+ * requirement object — the spec idiom for "auth optional" — contributes no
+ * alternative and flips `optional` instead.
+ */
+export const resolveSecurity = (
+  requirements: SecurityRequirementLike[],
+  schemes: Record<string, SecuritySchemeLike> | undefined
+): OperationSecurity => {
+  const alternatives: ResolvedScheme[][] = [];
+  let optional = false;
+  for (const requirement of requirements) {
+    const entries = Object.entries(requirement ?? {});
+    if (entries.length === 0) {
+      optional = true;
+      continue;
+    }
+    alternatives.push(
+      entries.map(([key, scopes]) => ({
+        key,
+        scheme: schemes?.[key],
+        scopes: Array.isArray(scopes)
+          ? scopes.filter((scope): scope is string => typeof scope === "string")
+          : [],
+      }))
+    );
+  }
+  return { alternatives, optional };
+};
+
+const capitalize = (text: string): string =>
+  text.charAt(0).toUpperCase() + text.slice(1);
+
+/** A short human label for a scheme row, e.g. `Bearer token` or `API key`. */
+export const schemeLabel = (resolved: ResolvedScheme): string => {
+  const { scheme } = resolved;
+  switch (scheme?.type) {
+    case "http": {
+      const kind = (scheme.scheme ?? "").toLowerCase();
+      if (kind === "bearer") {
+        return scheme.bearerFormat
+          ? `Bearer token (${scheme.bearerFormat})`
+          : "Bearer token";
+      }
+      if (kind === "basic") {
+        return "Basic auth";
+      }
+      return kind ? `HTTP ${kind}` : "HTTP auth";
+    }
+    case "apiKey": {
+      return "API key";
+    }
+    case "oauth2": {
+      return "OAuth2 access token";
+    }
+    case "openIdConnect": {
+      return "OpenID Connect token";
+    }
+    case "mutualTLS": {
+      return "Mutual TLS";
+    }
+    default: {
+      // Unknown scheme ref: the component name is the best label available.
+      return resolved.key;
+    }
+  }
+};
+
+/**
+ * Where the credential travels: the header/query/cookie parameter it occupies.
+ * Undefined for schemes with no request parameter (mutual TLS) and for unknown
+ * refs, where guessing a location would be misleading.
+ */
+export const schemeCarrier = (
+  resolved: ResolvedScheme
+): { name: string; in: string } | undefined => {
+  const { scheme } = resolved;
+  switch (scheme?.type) {
+    case "http":
+    case "oauth2":
+    case "openIdConnect": {
+      return { in: "header", name: "Authorization" };
+    }
+    case "apiKey": {
+      return { in: scheme.in ?? "header", name: scheme.name ?? resolved.key };
+    }
+    default: {
+      return undefined;
+    }
+  }
+};
+
+/** Placeholder credentials the request samples send. */
+export interface SampleAuth {
+  headers: Record<string, string>;
+  query: Record<string, string>;
+}
+
+/**
+ * Placeholder credentials for an operation's request samples, from its first
+ * alternative (the spec's preferred way to authorize). Schemes that don't
+ * travel in the request (mutual TLS) and unknown refs contribute nothing.
+ */
+export const sampleAuth = (security: OperationSecurity): SampleAuth => {
+  const headers: Record<string, string> = {};
+  const query: Record<string, string> = {};
+  const cookies: string[] = [];
+  for (const resolved of security.alternatives[0] ?? []) {
+    const { scheme } = resolved;
+    switch (scheme?.type) {
+      case "http": {
+        const kind = (scheme.scheme ?? "bearer").toLowerCase();
+        headers.Authorization =
+          kind === "bearer"
+            ? "Bearer YOUR_TOKEN"
+            : `${capitalize(kind)} YOUR_CREDENTIALS`;
+        break;
+      }
+      case "oauth2":
+      case "openIdConnect": {
+        headers.Authorization = "Bearer YOUR_ACCESS_TOKEN";
+        break;
+      }
+      case "apiKey": {
+        const name = scheme.name ?? resolved.key;
+        if (scheme.in === "query") {
+          query[name] = "YOUR_API_KEY";
+        } else if (scheme.in === "cookie") {
+          cookies.push(`${name}=YOUR_API_KEY`);
+        } else {
+          headers[name] = "YOUR_API_KEY";
+        }
+        break;
+      }
+      default: {
+        break;
+      }
+    }
+  }
+  if (cookies.length > 0) {
+    headers.Cookie = cookies.join("; ");
+  }
+  return { headers, query };
+};

package/src/components/openapi/snippets.ts

@@ -1,5 +1,6 @@
 import { exampleValue, toJson } from "./helpers.ts";
 import type { SchemaLike } from "./helpers.ts";
+import type { SampleAuth } from "./security.ts";
 
 /**
  * Request example + code-sample generation for an operation. Kept separate from
@@ -43,16 +44,22 @@ const jsonContentType = (
   return entries.find(([type]) => type.includes("json")) ?? entries[0];
 };
 
-/** The `?a=1&b=2` query string from an operation's required query params. */
+/**
+ * The `?a=1&b=2` query string from an operation's required query params, plus
+ * any extra entries (a query-borne API key from the security requirements).
+ */
 const queryString = (
   params: ParamLike[],
-  schemas: Record<string, SchemaLike>
+  schemas: Record<string, SchemaLike>,
+  extra: Record<string, string>
 ): string => {
   const query: string[] = [];
+  const seen = new Set<string>();
   for (const param of params) {
     if (!(param.in === "query" && param.required && param.name)) {
       continue;
     }
+    seen.add(param.name);
     const value = param.example ?? exampleValue(param.schema, schemas);
     query.push(
       `${encodeURIComponent(param.name)}=${encodeURIComponent(
@@ -60,16 +67,46 @@ const queryString = (
       )}`
     );
   }
+  for (const [name, value] of Object.entries(extra)) {
+    // A spec may declare the credential as an explicit query parameter too;
+    // its (better) example wins over the auth placeholder, as in headers.
+    if (seen.has(name)) {
+      continue;
+    }
+    query.push(`${encodeURIComponent(name)}=${encodeURIComponent(value)}`);
+  }
   return query.length > 0 ? `?${query.join("&")}` : "";
 };
 
+/**
+ * The sample's headers: auth placeholders first, so a spec that also declares
+ * the credential as an explicit header parameter overrides them with its own
+ * (better) example.
+ */
+const headerValues = (
+  params: ParamLike[],
+  schemas: Record<string, SchemaLike>,
+  auth: SampleAuth | undefined
+): Record<string, string> => {
+  const headers: Record<string, string> = { ...auth?.headers };
+  for (const param of params) {
+    if (param.in === "header" && param.required && param.name) {
+      headers[param.name] = String(
+        param.example ?? exampleValue(param.schema, schemas) ?? ""
+      );
+    }
+  }
+  return headers;
+};
+
 /** Assemble a representative request from an operation and the spec servers. */
 export const buildRequestSample = (
   operation: OperationLike,
   method: string,
   path: string,
   servers: { url?: string }[],
-  schemas: Record<string, SchemaLike>
+  schemas: Record<string, SchemaLike>,
+  auth?: SampleAuth
 ): RequestSample => {
   const base = (servers[0]?.url ?? "").replace(TRAILING_SLASH, "");
   const params = operation.parameters ?? [];
@@ -85,16 +122,8 @@ export const buildRequestSample = (
     }
   }
 
-  const search = queryString(params, schemas);
-
-  const headers: Record<string, string> = {};
-  for (const param of params) {
-    if (param.in === "header" && param.required && param.name) {
-      headers[param.name] = String(
-        param.example ?? exampleValue(param.schema, schemas) ?? ""
-      );
-    }
-  }
+  const search = queryString(params, schemas, auth?.query ?? {});
+  const headers = headerValues(params, schemas, auth);
 
   const media = jsonContentType(operation.requestBody?.content);
   let body: string | undefined;

package/src/core/config-input.ts

@@ -10,6 +10,7 @@ import type {
   SidebarItemConfig,
 } from "./schema.ts";
 import type { ContentSource } from "./sources/types.ts";
+import type { StandardSchema } from "./standard-schema.ts";
 
 /**
  * The public, hand-documented authoring type for `blume.config.ts`.
@@ -452,6 +453,16 @@ export interface MixedbreadSearch {
   storeId: string;
 }
 
+/** A curated link for the search dialog empty state. */
+export interface SearchPopularLink {
+  /** Internal route or external URL. */
+  href: string;
+  /** Built-in icon name shown beside the label; defaults to the file glyph. */
+  icon?: string;
+  /** Link label shown in the dialog. */
+  label: string;
+}
+
 /**
  * Search backend. The default `orama` builds a local index at build time (and
  * runs in dev); hosted providers need their credential block below. `none`
@@ -469,6 +480,11 @@ export interface SearchConfig {
   mixedbread?: MixedbreadSearch;
   /** Orama Cloud credentials (required when `provider` is `orama-cloud`). */
   oramaCloud?: OramaCloudSearch;
+  /**
+   * Curated links for the Cmd+K empty state. When omitted or empty, the first
+   * sidebar pages are shown instead.
+   */
+  popular?: SearchPopularLink[];
   /** Which backend powers search. Defaults to `orama`. */
   provider?: SearchProvider;
   /** Typesense credentials (required when `provider` is `typesense`). */
@@ -552,9 +568,11 @@ export interface AiConfig {
   /**
    * Markdown serializers for custom components in agent-facing output (the
    * `.md` mirror, `llms-full.txt`, MCP `get_page`), keyed by JSX name. Each
-   * receives the component's statically-evaluated `props` and downleveled
-   * `children` and returns replacement Markdown — or `null` to leave the JSX
-   * verbatim. A same-name entry replaces a built-in serializer.
+   * receives the component's statically-evaluated `props` (with the page's
+   * `frontmatter` in scope, so `prop={frontmatter.status}` resolves), its
+   * downleveled `children`, and the page's `frontmatter` data, and returns
+   * replacement Markdown — or `null` to leave the JSX verbatim. A same-name
+   * entry replaces a built-in serializer.
    *
    * These live in `blume.config.ts` (which is executed at build time), not in
    * `components.tsx` (which is only statically analyzed, never run).
@@ -711,7 +729,7 @@ export interface RssConfig {
   types?: string[];
 }
 
-/** Colors used by generated Open Graph cards. Values must be hex colors. */
+/** Colors used by generated Open Graph cards. Any CSS color — hex, `oklch(…)`, `rgb(…)`, named. */
 export interface OgPaletteConfig {
   /** Fallback mark color. Defaults to the light theme accent. */
   accent?: string;
@@ -733,10 +751,32 @@ export interface OgConfig {
    * value always wins.
    */
   enabled?: boolean;
+  /**
+   * Google Font families for the generated card, extending Takumi's Latin-only
+   * default so non-Latin titles (CJK, and so on) render instead of tofu.
+   * Fetched from Google Fonts at build. A bare string loads the family's
+   * default weights; the object form pins weights (`700`, `[400, 700]`, or a
+   * `"100..900"` variable range) and styles.
+   */
+  fonts?: (
+    | string
+    | {
+        name: string;
+        style?: "normal" | "italic" | ("normal" | "italic")[];
+        weight?: number | number[] | string;
+      }
+  )[];
   /** Local SVG used in the generated card instead of the site logo. */
   logo?: string;
   /** Optional generated-card colors. */
   palette?: OgPaletteConfig;
+  /**
+   * Card headlines for custom `.astro` pages, keyed by route (`"/"`, `"/cli"`).
+   * A custom page has no frontmatter to read, so its card is otherwise titled
+   * by humanizing its last URL segment (`/cli` → "Cli"); an entry here wins.
+   * Content pages always take their card headline from the page title.
+   */
+  titles?: Record<string, string>;
 }
 
 /** Discoverability: OG images, feeds, sitemap, robots, and structured data. */
@@ -918,6 +958,38 @@ export type ExportConfig =
       pdf?: boolean;
     };
 
+/**
+ * Opt-in custom frontmatter keys. Page frontmatter is strictly validated —
+ * an unknown key fails the build so typos are caught — and `extend` carves
+ * out project-specific keys from that rule, each validated by a schema you
+ * supply.
+ */
+export interface FrontmatterConfig {
+  /**
+   * Extra frontmatter keys pages may carry, mapped to their validation
+   * schemas — any library implementing Standard Schema works (Zod — the
+   * version your project installs, 3.24+ or 4 — Valibot, ArkType):
+   *
+   * ```ts
+   * import { z } from "zod";
+   *
+   * frontmatter: {
+   *   extend: {
+   *     owner: z.string(),
+   *     reviewedAt: z.coerce.date().optional(),
+   *   },
+   * },
+   * ```
+   *
+   * Every declared key is validated on every page — absent ones included —
+   * so a required schema enforces the key site-wide; mark it `.optional()`
+   * to validate only when present. Validated values are preserved on each
+   * page record's `custom` field. Built-in frontmatter fields cannot be
+   * redeclared.
+   */
+  extend?: Record<string, StandardSchema>;
+}
+
 /**
  * "Last updated" timestamps. `false` (default) disables them; `true` derives
  * each date from git history; the object form selects the source. A page's
@@ -991,6 +1063,8 @@ export interface BlumeConfig {
   export?: ExportConfig;
   /** Show the per-page "Was this helpful?" widget. Defaults to `true`. */
   feedback?: boolean;
+  /** Opt-in custom frontmatter keys, validated by schemas you supply. */
+  frontmatter?: FrontmatterConfig;
   /** Source repository (Edit-this-page links and the header repo link). */
   github?: GithubConfig;
   /** Internationalization (opt-in multi-locale). */

package/src/core/data.ts

@@ -1,3 +1,4 @@
+import type { OgFont } from "../og/card.ts";
 import type { UIStrings } from "./i18n-ui.ts";
 import type { ResolvedConfig, SearchProvider } from "./schema.ts";
 import type { Navigation, RouteAlternate } from "./types.ts";
@@ -115,12 +116,19 @@ export interface BlumeDataConfig {
   /** Open Graph image generation. */
   og: {
     enabled: boolean;
+    /** Extra Google Font family specs for the card renderer, fetched at build. */
+    fonts?: OgFont[];
     logo?: string;
     palette?: ResolvedConfig["seo"]["og"]["palette"];
   };
   /** Repository URL for header/edit links, or `null`. */
   repoUrl: string | null;
-  search: { enabled: boolean; provider: SearchProvider };
+  search: {
+    enabled: boolean;
+    /** Resolved empty-state links; empty when unset (Search falls back to sidebar). */
+    popular: { icon?: string; label: string; route: string }[];
+    provider: SearchProvider;
+  };
   /** Deployment site URL, or `null` when none is configured/detected. */
   site: string | null;
   structuredData: boolean;

package/src/core/deployment-env.ts

@@ -44,6 +44,15 @@ const PLATFORMS: Platform[] = [
   },
 ];
 
+/**
+ * Adapters whose `deployment.site` arrives from platform env vars at deploy
+ * time. Consumers (e.g. the audit) use this to tell "site is missing" apart
+ * from "site is missing *here*, but the platform will set it".
+ */
+export const SITE_INFERRING_ADAPTERS: ReadonlySet<string> = new Set(
+  PLATFORMS.map((platform) => platform.adapter)
+);
+
 /**
  * Fill in `deployment.adapter` and `deployment.site` from platform env vars
  * (Vercel, Netlify, Cloudflare Pages) when the user hasn't set them. Explicit

package/src/core/diagnostics.ts

@@ -38,12 +38,14 @@ const DOCS_PATHS: Record<string, string> = {
   BLUME_CONTENT_ROOT_MISSING: DOCS_CONTENT_SOURCES,
   BLUME_DEAD_LINK: DOCS_REFERENCE_CLI,
   BLUME_DUPLICATE_ROUTE: DOCS_CONTENT_NAVIGATION,
+  BLUME_DUPLICATE_SIDEBAR_ORDER: DOCS_CONTENT_NAVIGATION,
   BLUME_FRONTMATTER_INVALID: "/docs/reference/frontmatter",
   BLUME_META_INVALID: "/docs/content/meta",
   BLUME_META_LOAD_FAILED: "/docs/content/meta",
   BLUME_MISSING_SECRET: DOCS_DEPLOYMENT,
   BLUME_NAV_DUPLICATE_LABEL: DOCS_CONTENT_NAVIGATION,
   BLUME_NAV_HIDDEN_IN_SIDEBAR: DOCS_CONTENT_NAVIGATION,
+  BLUME_NAV_INDEX_TITLE_MISMATCH: DOCS_CONTENT_NAVIGATION,
   BLUME_NAV_MISSING_PAGE: DOCS_CONTENT_NAVIGATION,
   BLUME_NODE_VERSION: "/docs/quickstart",
   BLUME_SERVER_FEATURE_REQUIRED: DOCS_DEPLOYMENT,
@@ -126,17 +128,43 @@ const locatePath = (
   return { column: found - lastNewline, line: before.split("\n").length };
 };
 
-/** Convert a ZodError into Blume diagnostics, anchored to a file. */
-export const diagnosticsFromZod = (
-  error: ZodError,
+/** The YAML front matter block of a `.md`/`.mdx` source, if it has one. */
+const FRONTMATTER = /^---\r?\n(?<body>[\s\S]*?)\r?\n---/u;
+
+/**
+ * Locate a front matter key in a content file, e.g. `["seo", "description"]` in
+ * `docs/api.mdx`. Scoped to the front matter block so a `title:` written in the
+ * page body can't be mistaken for the front matter key of the same name; returns
+ * undefined when the file has no front matter or the key isn't set (a missing
+ * key has no line to point at — callers anchor to the file instead).
+ */
+export const locateFrontmatterKey = (
+  source: string,
+  path: readonly (string | number)[]
+): { column: number; line: number } | undefined => {
+  const block = FRONTMATTER.exec(source);
+  if (!block) {
+    return;
+  }
+  // `locatePath` reports lines 1-based within the text it was given, and the
+  // front matter body starts one line below the opening `---`.
+  const position = locatePath(block.groups?.body ?? "", path);
+  return position && { column: position.column, line: position.line + 1 };
+};
+
+/**
+ * Convert generic validation issues (message + path, the shape shared by Zod
+ * and Standard Schema issues) into Blume diagnostics, anchored to a file.
+ */
+export const diagnosticsFromIssues = (
+  issues: readonly {
+    message: string;
+    path: readonly (string | number)[];
+  }[],
   options: { code: string; file?: string; source?: string }
 ): Diagnostic[] =>
-  error.issues.map((issue) => {
+  issues.map((issue) => {
     const schemaPath = issue.path.join(".");
-    const received =
-      "received" in issue
-        ? ` (received: ${JSON.stringify(issue.received)})`
-        : "";
     const position = options.source
       ? locatePath(options.source, issue.path)
       : undefined;
@@ -145,14 +173,28 @@ export const diagnosticsFromZod = (
       column: position?.column,
       file: options.file,
       line: position?.line,
-      message: schemaPath
-        ? `${schemaPath}: ${issue.message}${received}`
-        : `${issue.message}${received}`,
+      message: schemaPath ? `${schemaPath}: ${issue.message}` : issue.message,
       schemaPath: schemaPath || undefined,
       severity: "error",
     } satisfies Diagnostic;
   });
 
+/** Convert a ZodError into Blume diagnostics, anchored to a file. */
+export const diagnosticsFromZod = (
+  error: ZodError,
+  options: { code: string; file?: string; source?: string }
+): Diagnostic[] =>
+  diagnosticsFromIssues(
+    error.issues.map((issue) => ({
+      message:
+        "received" in issue
+          ? `${issue.message} (received: ${JSON.stringify(issue.received)})`
+          : issue.message,
+      path: issue.path,
+    })),
+    options
+  );
+
 const ESC = String.fromCodePoint(27);
 const COLORS = {
   blue: `${ESC}[34m`,
@@ -184,13 +226,20 @@ export const formatDiagnostic = (
     `${color}${COLORS.bold}${diagnostic.code}${COLORS.reset} ${diagnostic.message}`,
   ];
 
+  // An audit finding is about a built URL, and names the source file that fixes
+  // it as a second line ("at /docs/api" / "in docs/api.mdx:3:2"). Everything
+  // else is about a file alone, and keeps the original single `at file` line.
+  if (diagnostic.url) {
+    lines.push(`  ${COLORS.dim}at ${diagnostic.url}${COLORS.reset}`);
+  }
   if (diagnostic.file) {
     const location = root ? relative(root, diagnostic.file) : diagnostic.file;
     const column =
       diagnostic.column === undefined ? "" : `:${diagnostic.column}`;
     const position =
       diagnostic.line === undefined ? "" : `:${diagnostic.line}${column}`;
-    lines.push(`  ${COLORS.dim}at ${location}${position}${COLORS.reset}`);
+    const label = diagnostic.url ? "in" : "at";
+    lines.push(`  ${COLORS.dim}${label} ${location}${position}${COLORS.reset}`);
   }
 
   if (diagnostic.suggestion) {

package/src/core/graph.ts

@@ -70,6 +70,7 @@ const localePagesFor = (
     if (!present.has(key)) {
       filled.push({
         ...source,
+        fallback: true,
         locale: code,
         route: withBasePath(basePath, localizeRoute(key, code, i18n)),
       });
@@ -85,7 +86,8 @@ const buildLocaleNavigation = (
   fallback: FallbackLocale,
   fallbackByKey: Map<string, PageRecord>,
   options: BuildContentGraphOptions,
-  i18n: ResolvedI18nConfig
+  i18n: ResolvedI18nConfig,
+  diagnostics: Diagnostic[]
 ): Navigation => {
   // Localize internal tab paths — the tab's own and its dropdown items' — so a
   // header tab points to its in-locale route (e.g. `/docs` -> `/fr/docs`);
@@ -112,6 +114,7 @@ const buildLocaleNavigation = (
   );
   return buildNavigation(localePages, {
     basePath: options.basePath ?? "",
+    diagnostics,
     display: options.navigation.sidebar.display,
     featured: options.navigation.featured,
     folderMeta: options.folderMeta,
@@ -137,7 +140,8 @@ const buildLocaleNavigation = (
 const buildI18nNavigation = (
   pages: PageRecord[],
   options: BuildContentGraphOptions,
-  i18n: ResolvedI18nConfig
+  i18n: ResolvedI18nConfig,
+  diagnostics: Diagnostic[]
 ): {
   navigation: Navigation;
   navigationByLocale: Record<string, Navigation>;
@@ -155,16 +159,30 @@ const buildI18nNavigation = (
   }
 
   // Each locale gets an independent tree, so navigation may diverge per language.
+  // Untranslated pages are padded into every locale from the fallback, so a tie
+  // in shared content would otherwise be re-reported once per locale — dedupe on
+  // code + file + message, which are all locale-stable for padded pages. A
+  // locale-specific tie names its own translated files/labels and survives.
   const navigationByLocale: Record<string, Navigation> = {};
+  const seen = new Set<string>();
   for (const { code } of i18n.locales) {
+    const localeDiagnostics: Diagnostic[] = [];
     navigationByLocale[code] = buildLocaleNavigation(
       code,
       pages,
       fallback,
       fallbackByKey,
       options,
-      i18n
+      i18n,
+      localeDiagnostics
     );
+    for (const diagnostic of localeDiagnostics) {
+      const key = `${diagnostic.code}\n${diagnostic.file ?? ""}\n${diagnostic.message}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        diagnostics.push(diagnostic);
+      }
+    }
   }
   const navigation = navigationByLocale[i18n.defaultLocale] ?? {
     featured: [],
@@ -184,10 +202,11 @@ export const buildContentGraph = (
   const { i18n } = options;
 
   const { navigation, navigationByLocale } = i18n
-    ? buildI18nNavigation(pages, options, i18n)
+    ? buildI18nNavigation(pages, options, i18n, diagnostics)
     : {
         navigation: buildNavigation(pages, {
           basePath: options.basePath ?? "",
+          diagnostics,
           display: options.navigation.sidebar.display,
           featured: options.navigation.featured,
           folderMeta: options.folderMeta,