blume 2.0.1 → 2.0.3

package/src/core/diagnostics.ts

@@ -69,8 +69,10 @@ const DOCS_PATHS = new Map(
     BLUME_TRANSLATE_MISSING: "/docs/cli/translate",
     BLUME_TRANSLATE_STALE: "/docs/cli/translate",
     BLUME_UNKNOWN_COMPONENT: "/docs/configuration/customization",
+    BLUME_UNKNOWN_DIRECTIVE: "/docs/content/syntax",
     BLUME_UNKNOWN_ICON: DOCS_CONTENT_NAVIGATION,
     BLUME_UNKNOWN_OPTION: "/docs/cli",
+    BLUME_UNLOADABLE_FILE_NAME: "/docs/content",
     BLUME_WIKILINK_AMBIGUOUS: DOCS_CONTENT_SOURCES,
     BLUME_WIKILINK_UNRESOLVED: DOCS_CONTENT_SOURCES,
     BLUME_YARN_PNP: "/docs/quickstart",
@@ -98,50 +100,237 @@ const isKeySegment = (segment: string | number): segment is string =>
   typeof segment === "string";
 
 /**
- * Best-effort source position for a Zod issue path (e.g. `["seo", "title"]`) in
- * the raw config / frontmatter text. Narrows key-by-key — finding each string
- * segment as a `key:`/`key =` at or after the previous match — so a nested key
- * lands under its parent. Array indices are skipped. Returns 1-based line/column,
- * or undefined when nothing matches.
+ * Where a located value's children are searched. `object` and `array` are the
+ * inside of a `{…}`/`[…]` literal, searched entry by entry so a key or an index
+ * only matches a direct child. `block` has no brackets — the whole file at the
+ * top, or a YAML key's indented lines — and is searched at any depth.
  */
-const stepSegment = (
+interface Scope {
+  end: number;
+  /** A literal's direct entries (keys or elements), in source order. */
+  entries: number[];
+  kind: "array" | "block" | "object";
+  start: number;
+}
+
+/** A located key or element: where it starts, and where its value starts. */
+interface Step {
+  index: number;
+  next: number;
+}
+
+const QUOTES = new Set(['"', "'", "`"]);
+const OPENERS = new Set(["(", "[", "{"]);
+const CLOSERS = new Set([")", "]", "}"]);
+const WHITESPACE = /\s/u;
+
+/**
+ * The index just past a comment starting at `index`, or `index` when none does.
+ * A `//` after a `:` is a URL scheme in YAML (`href: https://…`), not a comment.
+ */
+const skipComment = (source: string, index: number): number => {
+  if (source.startsWith("//", index) && source.charAt(index - 1) !== ":") {
+    const end = source.indexOf("\n", index);
+    return end === -1 ? source.length : end;
+  }
+  if (source.startsWith("/*", index)) {
+    const end = source.indexOf("*/", index + 2);
+    return end === -1 ? source.length : end + 2;
+  }
+  return index;
+};
+
+/**
+ * The index just past a string literal starting at `index`, or `index` when
+ * none does. A `'`/`"` that doesn't close on its own line is an apostrophe in
+ * plain YAML text, not a string.
+ */
+const skipString = (source: string, index: number): number => {
+  const quote = source.charAt(index);
+  if (!QUOTES.has(quote)) {
+    return index;
+  }
+  let cursor = index + 1;
+  while (cursor < source.length) {
+    const char = source.charAt(cursor);
+    if (char === quote) {
+      return cursor + 1;
+    }
+    if (char === "\n" && quote !== "`") {
+      return index;
+    }
+    cursor += char === "\\" ? 2 : 1;
+  }
+  return index;
+};
+
+/** Where a literal closes, and where each of its direct entries starts. */
+interface LiteralScan {
+  end: number;
+  entries: number[];
+}
+
+/**
+ * Walk the `{…}`/`[…]` literal opened at `open`: where each direct entry starts
+ * (a key, or an array element) and where the literal closes. Nested brackets,
+ * strings, and comments are stepped over, so only the literal's own commas
+ * separate its entries.
+ */
+const scanLiteral = (source: string, open: number): LiteralScan => {
+  const entries: number[] = [];
+  let depth = 0;
+  let pending = true;
+  let index = open + 1;
+  while (index < source.length) {
+    const afterComment = skipComment(source, index);
+    const char = source.charAt(index);
+    if (afterComment !== index || WHITESPACE.test(char)) {
+      index = Math.max(afterComment, index + 1);
+      continue;
+    }
+    if (depth === 0 && CLOSERS.has(char)) {
+      return { end: index, entries };
+    }
+    if (depth === 0 && pending) {
+      entries.push(index);
+      pending = false;
+    }
+    const afterString = skipString(source, index);
+    if (afterString !== index) {
+      index = afterString;
+      continue;
+    }
+    if (OPENERS.has(char)) {
+      depth += 1;
+    } else if (CLOSERS.has(char)) {
+      depth -= 1;
+    } else if (char === "," && depth === 0) {
+      pending = true;
+    }
+    index += 1;
+  }
+  return { end: source.length, entries };
+};
+
+/**
+ * The lines indented deeper than the key at `anchor` — a YAML mapping's
+ * children — up to the first line that isn't, or `limit`.
+ */
+const indentedBlock = (
   source: string,
-  segment: string | number,
-  cursor: number
-) => {
-  // A non-string path segment (array index) is skipped without moving on.
-  if (!isKeySegment(segment)) {
-    return { index: -1, next: cursor, stop: false };
+  anchor: number,
+  limit: number
+): Scope => {
+  const column = anchor - (source.lastIndexOf("\n", anchor - 1) + 1);
+  const lineEnd = source.indexOf("\n", anchor);
+  const start = lineEnd === -1 ? limit : Math.min(lineEnd + 1, limit);
+  let end = start;
+  while (end < limit) {
+    const next = source.indexOf("\n", end);
+    const after = next === -1 || next >= limit ? limit : next + 1;
+    const line = source.slice(end, after);
+    if (line.trim() !== "" && line.length - line.trimStart().length <= column) {
+      break;
+    }
+    end = after;
   }
-  // The negative lookbehind keeps a segment like `title` from matching the
-  // tail of an unrelated key such as `subtitle:`.
-  const matcher = new RegExp(
-    `(?<![\\w$])${escapeRegExp(segment)}\\s*[:=]`,
-    "gu"
-  );
-  matcher.lastIndex = cursor;
-  const match = matcher.exec(source);
-  if (!match) {
-    return { index: -1, next: cursor, stop: true };
+  return { end, entries: [], kind: "block", start };
+};
+
+/** A value's lead-in before its literal: spaces, or an adapter call's `vercel(`. */
+const VALUE_LEAD = /[\s\w$.(]*/uy;
+
+/**
+ * The scope holding the children of the key or element at `anchor`, whose
+ * value starts at `from`. A `{…}`/`[…]` literal — written directly, or as the
+ * first argument of a call like `vercel({…})` — is walked entry by entry;
+ * anything else falls back to the lines indented under `anchor` (YAML's
+ * nesting), within the enclosing scope's `limit`.
+ */
+const valueScope = (source: string, step: Step, limit: number): Scope => {
+  VALUE_LEAD.lastIndex = step.next;
+  VALUE_LEAD.exec(source);
+  const open = VALUE_LEAD.lastIndex;
+  const char = source.charAt(open);
+  if (open < limit && (char === "{" || char === "[")) {
+    const literal = scanLiteral(source, open);
+    return {
+      end: literal.end,
+      entries: literal.entries,
+      kind: char === "{" ? "object" : "array",
+      start: open,
+    };
   }
-  return { index: match.index, next: matcher.lastIndex, stop: false };
+  return indentedBlock(source, step.index, limit);
 };
 
+/**
+ * Find `segment` as a `key:`/`key =` (bare or quoted) in `scope`: among an
+ * object literal's own entries, or anywhere in a block. The negative lookbehind
+ * keeps `title` from matching the tail of an unrelated key such as `subtitle:`.
+ */
+const findKey = (
+  source: string,
+  scope: Scope,
+  segment: string
+): Step | undefined => {
+  const key = escapeRegExp(segment);
+  const pattern = `(?<![\\w$])(?:${key}|"${key}"|'${key}')\\s*[:=]`;
+  if (scope.kind === "block") {
+    const matcher = new RegExp(pattern, "gu");
+    matcher.lastIndex = scope.start;
+    const match = matcher.exec(source);
+    return match && match.index < scope.end
+      ? { index: match.index, next: matcher.lastIndex }
+      : undefined;
+  }
+  // Sticky: the key must start exactly where the entry does.
+  const matcher = new RegExp(pattern, "uy");
+  for (const entry of scope.kind === "object" ? scope.entries : []) {
+    matcher.lastIndex = entry;
+    if (matcher.test(source)) {
+      return { index: entry, next: matcher.lastIndex };
+    }
+  }
+  return undefined;
+};
+
+/** The element at `position` of an array literal; a block can't be indexed. */
+const findElement = (scope: Scope, position: number): Step | undefined => {
+  const index = scope.kind === "array" ? scope.entries[position] : undefined;
+  return index === undefined ? undefined : { index, next: index };
+};
+
+/**
+ * Best-effort source position for a Zod issue path (e.g. `["seo", "title"]`,
+ * `["redirects", 2, "status"]`) in the raw config / frontmatter text. Narrows
+ * segment by segment: a key is found among its parent's own entries (or, where
+ * there are no brackets, in the parent's indented lines), an index picks that
+ * element of an array literal. A segment that isn't there — a missing key —
+ * stops the walk at its parent, so the position never escapes into a sibling.
+ * Returns 1-based line/column, or undefined when not even the first segment
+ * matches.
+ */
 const locatePath = (
   source: string,
   path: readonly (string | number)[]
 ): { column: number; line: number } | undefined => {
-  let cursor = 0;
+  let scope: Scope = {
+    end: source.length,
+    entries: [],
+    kind: "block",
+    start: 0,
+  };
   let found = -1;
   for (const segment of path) {
-    const step = stepSegment(source, segment, cursor);
-    if (step.stop) {
+    const step = isKeySegment(segment)
+      ? findKey(source, scope, segment)
+      : findElement(scope, segment);
+    if (!step) {
       break;
     }
-    cursor = step.next;
-    if (step.index >= 0) {
-      found = step.index;
-    }
+    found = step.index;
+    scope = valueScope(source, step, scope.end);
   }
   if (found < 0) {
     return;

package/src/core/directive-diagnostics.ts

@@ -0,0 +1,99 @@
+import type { Nodes } from "mdast";
+import { mdxToMdast } from "satteri";
+
+import {
+  CALLOUT_ALIASES,
+  CALLOUT_TYPES,
+  calloutTypeFor,
+} from "../markdown/directives.ts";
+import { MDX_BODY_FEATURES } from "../markdown/features.ts";
+import { strippedLineOffset } from "./sources/normalize.ts";
+import type { SourceEntry } from "./sources/types.ts";
+import type { Diagnostic } from "./types.ts";
+
+// A line that may open a container directive: a colon fence and a name, after
+// any quote or list indentation. A page is parsed only when one of these
+// names something other than a callout, so pages without one cost a scan.
+const CONTAINER_OPENING = /^[\t >]*:{3,}(?<name>[a-z][\w-]*)/gimu;
+
+const codeList = (names: Iterable<string>): string =>
+  [...names].map((name) => `\`${name}\``).join(", ");
+
+const CALLOUT_NAMES = `${codeList(CALLOUT_TYPES)} (or the aliases ${codeList(Object.keys(CALLOUT_ALIASES))})`;
+
+/** A container directive that isn't a callout, and its line in `text`. */
+interface UnknownContainer {
+  line: number;
+  name: string;
+}
+
+/**
+ * Every container directive in an `.mdx` body whose name isn't a callout, in
+ * source order. The body is parsed as the renderer reads it, so a fence in a
+ * code block or a `::: name` that isn't a directive at all never counts. A
+ * body MDX can't parse fails to render anyway, with its own error.
+ */
+const unknownContainers = (text: string): UnknownContainer[] => {
+  const named = [...text.matchAll(CONTAINER_OPENING)].some(
+    (match) => calloutTypeFor(match.groups?.name ?? "") === null
+  );
+  if (!named) {
+    return [];
+  }
+  let tree: Nodes;
+  try {
+    tree = mdxToMdast(text, { features: MDX_BODY_FEATURES });
+  } catch {
+    return [];
+  }
+  const found: UnknownContainer[] = [];
+  const walk = (node: Nodes): void => {
+    if (
+      node.type === "containerDirective" &&
+      calloutTypeFor(node.name) === null
+    ) {
+      found.push({ line: node.position?.start.line ?? 1, name: node.name });
+    }
+    if ("children" in node) {
+      for (const child of node.children) {
+        walk(child);
+      }
+    }
+  };
+  walk(tree);
+  return found;
+};
+
+/**
+ * Warn about each `:::name` container in an `.mdx` entry that isn't a callout.
+ * The page keeps its content — the body renders between the literal `:::`
+ * lines (see `markdown/directives.ts`) — but a typo like `:::warnig`, or a
+ * `:::details` carried over from another docs tool, should read as the
+ * mistake it is rather than as a finished page. Lines point into the file
+ * the author wrote, a partial's own file for a container an `<include>`
+ * brought in.
+ */
+export const unknownDirectiveDiagnostics = (
+  entry: SourceEntry,
+  sourceName: string
+): Diagnostic[] => {
+  if (entry.body.format !== "mdx") {
+    return [];
+  }
+  const page = entry.sourcePath ?? `${sourceName}:${entry.ref}`;
+  const offset =
+    entry.bodyLineOffset ?? strippedLineOffset(entry.raw, entry.body.text);
+  return unknownContainers(entry.expanded?.text ?? entry.body.text).map(
+    ({ line, name }) => {
+      const origin = entry.expanded?.origins[line - 1];
+      return {
+        code: "BLUME_UNKNOWN_DIRECTIVE",
+        file: origin?.file ?? page,
+        line: origin?.line ?? line + offset,
+        message: `\`:::${name}\` isn't a callout type, so the page shows its \`:::\` lines as written around its content.`,
+        severity: "warning",
+        suggestion: `Use a callout type — ${CALLOUT_NAMES} — or remove the \`:::\` lines to keep the content as plain prose.`,
+      };
+    }
+  );
+};

package/src/core/frontmatter.ts

@@ -19,13 +19,18 @@ type StringifyArgs = Parameters<typeof baseMatter.stringify>;
 /** Front matter data as gray-matter types it (`GrayMatterFile["data"]`). */
 type FrontMatterData = ReturnType<typeof baseMatter>["data"];
 
+/** A YAML load result: a mapping (or list) Astro keeps as front matter data. */
+const isYamlCollection = (
+  value: ReturnType<typeof load>
+): value is FrontMatterData => typeof value === "object" && value !== null;
+
 const yamlEngine = {
-  // SAFETY: gray-matter's engine contract expects an object; a front matter
-  // block is a YAML mapping, and js-yaml returns a scalar only for degenerate
-  // input, which gray-matter treats the same way its bundled engine's output
-  // is treated.
-  parse: (input: string): object =>
-    (load(input, { schema: YAML_SCHEMA }) ?? {}) as object,
+  // A block that loads to a scalar (`title` alone, or prose between two
+  // `---` lines) is no metadata: Astro reads it as `{}`, and so does Blume.
+  parse: (input: string): FrontMatterData => {
+    const value = load(input, { schema: YAML_SCHEMA });
+    return isYamlCollection(value) ? value : {};
+  },
   stringify: (data: FrontMatterData): string => dump(data),
 };
 
@@ -45,23 +50,21 @@ const withYamlEngine = <O extends { engines?: object } | undefined>(
 
 /**
  * True when a document's leading `---` line is a CommonMark thematic break,
- * not a front matter fence. Two shapes qualify (mirroring
- * `linesWithoutFrontMatter` in `sources/normalize.ts`):
- *   - the next line is blank (or absent) — YAML metadata starts on the very
- *     next line, so a gap means the body *opens* with a divider (e.g. a
- *     Notion page whose first block is one);
- *   - no closing `---` line follows — gray-matter would swallow the whole
- *     document as one unclosed YAML block and hand it to js-yaml, which
- *     crashes on ordinary Markdown (`> quote` → "a line break is expected").
+ * not a front matter fence: no closing `---` line follows. Astro's own front
+ * matter match requires that close too, while gray-matter would swallow the
+ * whole document as one unclosed YAML block and hand it to js-yaml, which
+ * crashes on ordinary Markdown (`> quote` → "a line break is expected").
+ *
+ * A blank line after the opening `---` is still front matter: Astro strips
+ * the block from the page either way, so reading it as a divider here would
+ * ignore its `draft`, `slug`, and `hidden` while its YAML leaked into search
+ * and llms.txt.
  */
 const opensWithThematicBreak = (input: string): boolean => {
-  const [first = "", second] = input.split(/\r?\n/u, 2);
+  const [first = ""] = input.split(/\r?\n/u, 1);
   if (!/^-{3}\s*$/u.test(first)) {
     return false;
   }
-  if (second === undefined || second.trim() === "") {
-    return true;
-  }
   // gray-matter closes the block at the next line-leading `---`; matching its
   // search exactly keeps this guard from firing on any document it parses.
   return !input.includes("\n---", 1);

package/src/core/graph.ts

@@ -1,17 +1,22 @@
-import { withBasePath } from "./base-path.ts";
+import { mountBasePath, withBasePath } from "./base-path.ts";
 import {
   localizeInternalPath,
   localizeRoute,
   resolveFallbackLocale,
 } from "./i18n.ts";
-import { validateNavIcons, validateNavStructure } from "./nav-diagnostics.ts";
-import { buildNavigation } from "./navigation.ts";
+import {
+  validateNavIcons,
+  validateNavStructure,
+  validateSidebarItems,
+} from "./nav-diagnostics.ts";
+import { buildNavigation, isPageRef, pagesByRef } from "./navigation.ts";
 import type {
   FolderMeta,
   LocalizableLabel,
   ResolvedConfig,
   ResolvedI18nConfig,
   ResolvedVersionsConfig,
+  SidebarItemConfig,
 } from "./schema.ts";
 import type {
   ContentGraph,
@@ -23,6 +28,8 @@ import type {
 import { versionizeRoute } from "./versions.ts";
 
 interface BuildContentGraphOptions {
+  /** The banner's link target as configured (`banner.link.href`), if any. */
+  bannerHref?: string;
   /** Site-wide route mount point (`""` or `/seg`); invisible to the nav tree. */
   basePath?: string;
   /** The header brand link as configured (`logo.href`, default `/`). */
@@ -83,7 +90,7 @@ const localePagesFor = (
         ...source,
         fallback: true,
         locale: code,
-        route: withBasePath(basePath, localizeRoute(key, code, i18n)),
+        route: mountBasePath(basePath, localizeRoute(key, code, i18n)),
       });
     }
   }
@@ -115,6 +122,28 @@ const resolveLabel = (
   );
 };
 
+/**
+ * An explicit sidebar with every item's `href` passed through `localize` (page
+ * refs and `root`s resolve against each locale's own pages already).
+ */
+const localizeSidebarHrefs = (
+  items: SidebarItemConfig[],
+  localize: (href: string) => string
+): SidebarItemConfig[] =>
+  items.map((item) => {
+    if (isPageRef(item)) {
+      return item;
+    }
+    const localized = { ...item };
+    if (item.href !== undefined) {
+      localized.href = localize(item.href);
+    }
+    if (item.items) {
+      localized.items = localizeSidebarHrefs(item.items, localize);
+    }
+    return localized;
+  });
+
 /** Resolve every localizable label in the configured tabs for one locale. */
 const resolveTabLabels = (
   tabs: BuildContentGraphOptions["navigation"]["tabs"],
@@ -130,6 +159,18 @@ const resolveTabLabels = (
     label: resolveLabel(tab.label, locale, defaultLocale),
   }));
 
+/**
+ * Mount a configured link authored as if the site were served at root (the
+ * banner's): under `basePath`, except a route served outside the content tree
+ * — a custom page, the generated changelog index — which answers only at its
+ * own path.
+ */
+const mountConfiguredLink = (
+  path: string,
+  basePath: string,
+  extraRoutes: ReadonlySet<string>
+): string => (extraRoutes.has(path) ? path : withBasePath(basePath, path));
+
 /**
  * Build one locale's navigation tree from its own pages and folder meta.
  * `version` is the archived version id when building a snapshot's tree
@@ -217,8 +258,15 @@ const buildLocaleNavigation = (
   // next to the originals and `guides/meta.ts` applies to every locale —
   // prefixing would look up keys that can never exist. Inside a snapshot the
   // version dir is hoisted in front (`v1.0/fr`), matching `discoverFolderMeta`.
-  const localeDir =
-    i18n.parser === "dir" && code !== i18n.defaultLocale ? code : "";
+  const localeDirOf = (locale: string): string =>
+    i18n.parser === "dir" && locale !== i18n.defaultLocale ? locale : "";
+  const localeDir = localeDirOf(code);
+  // A locale padded from the fallback locale mirrors that locale's folder meta
+  // for any folder it has no meta of its own for.
+  const fallbackMetaPrefix =
+    fallback && code !== fallback
+      ? [version, localeDirOf(fallback)].filter(Boolean).join("/")
+      : undefined;
   // Internal featured and header hrefs are localized like tab paths — a pinned
   // `/changelog` link rendered on `/fr/…` pages must stay inside the reader's
   // locale, not kick them back to the default one.
@@ -227,6 +275,7 @@ const buildLocaleNavigation = (
     href: localizeServed(item.href, false),
   });
   const { actions, cta, featured } = options.navigation;
+  const sidebarItems = options.navigation.sidebar.items;
 
   const navigation = buildNavigation(localePages, {
     actions: actions?.map(localizeHref),
@@ -235,6 +284,7 @@ const buildLocaleNavigation = (
     diagnostics,
     display: options.navigation.sidebar.display,
     extraRoutes: options.extraRoutes,
+    fallbackMetaPrefix,
     featured: featured?.map(localizeHref),
     folderMeta: options.folderMeta,
     // The localized tree root ("/" for the hidden default, "/fr" otherwise;
@@ -250,13 +300,43 @@ const buildLocaleNavigation = (
     sharedMetaPrefix: version,
     // A configured explicit sidebar describes the current docs; a frozen
     // snapshot's structure comes from the snapshot itself, so archived trees
-    // always build from the filesystem.
-    sidebar: version ? undefined : options.navigation.sidebar.items,
+    // always build from the filesystem. Its `href` links are localized like
+    // featured links.
+    sidebar:
+      version || !sidebarItems
+        ? undefined
+        : localizeSidebarHrefs(sidebarItems, (href) =>
+            localizeServed(href, false)
+          ),
+    // Tab paths are written against the current docs' root, which a
+    // snapshot's versionized `localizedRoot` no longer is.
+    tabRoot: localizeRoute("/", code, i18n),
     tabs,
   });
-  return options.brandHref === undefined
-    ? navigation
-    : { ...navigation, brandHref: localizeServed(options.brandHref, false) };
+  // `serves` checked the localized brand link against based routes, and
+  // unlike tab and header links it isn't rebased later, so a localized one
+  // takes the base here (`/fr` is served at `/docs/fr`).
+  const localizedBrand = (href: string): string => {
+    const localized = localizeServed(href, false);
+    return localized === href ? localized : withBasePath(basePath, localized);
+  };
+  const branded =
+    options.brandHref === undefined
+      ? navigation
+      : { ...navigation, brandHref: localizedBrand(options.brandHref) };
+  // The banner link is authored like a featured href — in the default
+  // locale's path space, as if mounted at root — so it is localized the same
+  // way before it is mounted.
+  return options.bannerHref === undefined
+    ? branded
+    : {
+        ...branded,
+        bannerHref: mountConfiguredLink(
+          localizeServed(options.bannerHref, false),
+          basePath,
+          extraRoutes
+        ),
+      };
 };
 
 /**
@@ -348,6 +428,8 @@ const buildVersionNavigation = (
       selectors: options.navigation.selectors,
       sharedFolderMeta: options.sharedFolderMeta,
       sharedMetaPrefix: id,
+      // Tab paths are written against the current docs' root.
+      tabRoot: "/",
       // A configured explicit sidebar describes the current docs; a snapshot's
       // structure comes from the snapshot itself.
       tabs: resolveTabLabels(options.navigation.tabs, ""),
@@ -398,6 +480,16 @@ export const buildContentGraph = (
       // entry on a single-locale site.
       tabs: resolveTabLabels(options.navigation.tabs, ""),
     });
+    if (options.bannerHref !== undefined) {
+      navigation = {
+        ...navigation,
+        bannerHref: mountConfiguredLink(
+          options.bannerHref,
+          options.basePath ?? "",
+          options.extraRoutes ?? new Set<string>()
+        ),
+      };
+    }
   }
 
   const navigationByVersion: Record<string, Record<string, Navigation>> = {};
@@ -417,6 +509,23 @@ export const buildContentGraph = (
     ...validateNavIcons(navigation),
     ...validateNavStructure(navigation, currentPages)
   );
+  // Checked once against every locale's pages, not per locale tree: a page
+  // missing from one locale's sidebar is an untranslated page, not a typo.
+  const sidebarItems = options.navigation.sidebar.items;
+  if (sidebarItems) {
+    const byRef = pagesByRef(
+      currentPages,
+      options.basePath ?? "",
+      Boolean(i18n)
+    );
+    const extraRoutes = options.extraRoutes ?? new Set<string>();
+    diagnostics.push(
+      ...validateSidebarItems(
+        sidebarItems,
+        (route) => byRef.has(route) || extraRoutes.has(route)
+      )
+    );
+  }
 
   return {
     diagnostics,