blume 2.0.1 → 2.0.3

package/src/core/heading-markers.ts

@@ -55,17 +55,12 @@ export interface HeadingMarkers {
  * the heading count (mid-text brackets are ordinary prose); when a marker kind
  * repeats, the last one written wins.
  *
- * `isRefDefined` reports whether a link-reference definition exists for a
- * bracket's label (`toc`, `!toc`, `#id`): a defined bracket is a CommonMark
- * shortcut link, not a marker — the renderer sees a resolved `<a>` element
- * there and strips nothing at or before it, so the parse stops the same way.
- * The render-time hast plugin never passes it (resolved links are already
- * elements by the time it runs); the raw-source scanner does.
+ * Callers pass the heading's trailing text node after a Markdown parse, so a
+ * bracket that a link-reference definition turns into a CommonMark shortcut
+ * link (`[toc]` with a `[toc]: …` definition) is already an element there and
+ * never reaches this parse.
  */
-export const parseHeadingMarkers = (
-  text: string,
-  isRefDefined?: (label: string) => boolean
-): HeadingMarkers => {
+export const parseHeadingMarkers = (text: string): HeadingMarkers => {
   let remaining = text;
   let id: string | undefined;
   let toc: HeadingMarkers["toc"];
@@ -75,14 +70,6 @@ export const parseHeadingMarkers = (
     match = MARKER.exec(remaining)
   ) {
     const explicitId = match.groups.curlyId ?? match.groups.id;
-    const label =
-      explicitId === undefined
-        ? `${match.groups.hide ?? ""}toc`
-        : `#${explicitId}`;
-    // A `{#id}` is never a shortcut link, whatever the definitions say.
-    if (match.groups.curlyId === undefined && isRefDefined?.(label)) {
-      break;
-    }
     remaining = remaining.slice(0, match.index);
     if (explicitId === undefined) {
       // Stripping runs right-to-left, so keeping the first capture of each

package/src/core/i18n-ui.ts

@@ -72,11 +72,32 @@ const uiStringsObject = z.object({
     .prefault({}),
   content: z
     .object({
+      // `<Component>`'s source tab.
+      code: z.string().default("Code"),
       // A `<Color.Item>` swatch's accessible name; `{name}` and `{value}` are
       // replaced with the color's name and the value it shows.
       copyColor: z.string().default("Copy {name} color {value}"),
       copyPrompt: z.string().default("Copy prompt"),
+      // `<TypeTable>`: a row's default-value label.
+      default: z.string().default("Default"),
       diagramError: z.string().default("Could not render this diagram."),
+      // `<GithubInfo>`: the screen-reader labels of the fork and star counts.
+      forks: z.string().default("Forks"),
+      // `<Component>`'s live-preview tab, also its frame's title.
+      preview: z.string().default("Preview"),
+      // `<TypeTable>`: the property-name column.
+      prop: z.string().default("Prop"),
+      // `<Tabs dropdown>`: the accessible name of the tab picker.
+      selectTab: z.string().default("Select tab"),
+      // `<Expandable>`'s toggle when it sets no `title`.
+      showMore: z.string().default("Show more"),
+      stars: z.string().default("Stars"),
+      // An untitled tab's label; `{n}` is replaced with its position.
+      tab: z.string().default("Tab {n}"),
+      // `<TypeTable>`: the type column and a row's type label.
+      type: z.string().default("Type"),
+      // `<Update>`'s heading when it sets no `label` or `title`.
+      update: z.string().default("Update"),
     })
     .prefault({}),
   feedback: z
@@ -147,8 +168,13 @@ const uiStringsObject = z.object({
       devOnly: z
         .string()
         .default("Search is available in the production build."),
+      // The section a hit falls under when its page sits in no sidebar group.
+      docs: z.string().default("Docs"),
       error: z.string().default("Something went wrong. Please try again."),
       label: z.string().default("Search docs"),
+      // The version tag on a result from the current docs in an all-versions
+      // search (a result from an archived version shows its version id).
+      latest: z.string().default("latest"),
       navigate: z.string().default("navigate"),
       noResults: z.string().default("No results found."),
       open: z.string().default("open"),
@@ -281,11 +307,20 @@ const packFor = (code: string): UIStringsOverride | undefined => {
   );
 };
 
+/** Whether a locale code is English (`en`, `en-GB`, `en_US`), in any case. */
+const isEnglish = (code: string): boolean =>
+  code.toLowerCase().split(/[-_]/u)[0] === "en";
+
 /**
  * Resolve the active dictionary for a locale. Layers, in order:
  * English baseline ← default-locale pack ← default-locale override ←
  * locale pack ← locale override. So a missing key falls back to the default
  * locale's translation, then to English.
+ *
+ * English has no pack because the baseline is its complete translation, so an
+ * English locale (`en`, `en-GB`) skips the default-locale layers: on a site
+ * whose default is German, English pages keep English chrome instead of
+ * inheriting the German strings.
  */
 export const resolveUIStrings = (
   locale: string,
@@ -296,8 +331,10 @@ export const resolveUIStrings = (
 ): UIStrings => {
   const { defaultLocale, overrides } = options;
   let dict = EN_UI;
-  dict = mergeUI(dict, packFor(defaultLocale));
-  dict = mergeUI(dict, overrides?.[defaultLocale]);
+  if (!isEnglish(locale) || isEnglish(defaultLocale)) {
+    dict = mergeUI(dict, packFor(defaultLocale));
+    dict = mergeUI(dict, overrides?.[defaultLocale]);
+  }
   if (locale !== defaultLocale) {
     dict = mergeUI(dict, packFor(locale));
     dict = mergeUI(dict, overrides?.[locale]);

package/src/core/i18n.ts

@@ -187,12 +187,19 @@ export const localePlacement = (
  * (`x.en.mdx`) swaps it for the target's (`x.fr.mdx`) — same case-insensitive
  * last-dot-inside-filename logic as `localePlacement`, so both spellings of a
  * default-locale file resolve to one canonical target.
+ *
+ * Under `dir`, `folders` are the content root's existing top-level folders: one
+ * that names the locale in another casing (`pt-br/` for a configured `pt-BR`)
+ * is the locale's folder already, since {@link detectLocale} matches it case-
+ * insensitively. Writing beside it into a second `pt-BR/` would, on a case-
+ * sensitive filesystem, publish the page twice.
  */
 export const localeTargetPath = (
   rel: string,
   ext: string,
   locale: string,
-  i18n: ResolvedI18nConfig
+  i18n: ResolvedI18nConfig,
+  folders: readonly string[] = []
 ): string => {
   if (i18n.parser === "dot") {
     let base = rel.slice(0, rel.length - ext.length);
@@ -205,14 +212,38 @@ export const localeTargetPath = (
     }
     return `${base}.${locale}${ext}`;
   }
-  return `${locale}/${rel}`;
+  const folder = folders.includes(locale)
+    ? locale
+    : (folders.find((name) => name.toLowerCase() === locale.toLowerCase()) ??
+      locale);
+  return `${folder}/${rel}`;
 };
 
+/**
+ * The warning for a top-level folder named after the default locale
+ * (`docs/en/` when `defaultLocale` is `en`). Only non-default codes are
+ * locale folders — the default locale lives at the content root — so the
+ * folder is ordinary default-locale content, published one level down at
+ * `/en/…` (`/en/en/…` with the default prefix shown) and filled into every
+ * other locale at `/fr/en/…`.
+ */
+const defaultLocaleFolderDiagnostic = (
+  folder: string,
+  i18n: ResolvedI18nConfig
+): Diagnostic => ({
+  code: "BLUME_I18N_DEFAULT_LOCALE_FOLDER",
+  message: `Folder "${folder}/" is named after the default locale, but "${i18n.defaultLocale}" pages live at the content root — its pages publish at ${localizeRoute(`/${folder}`, i18n.defaultLocale, i18n)}/… instead.`,
+  severity: "warning",
+  suggestion: `Move the contents of "${folder}/" up to the content root; only the other locales get a folder.`,
+});
+
 /**
  * Warn about top-level content folders that look like a locale (a code Blume
  * recognizes) but aren't declared in `i18n.locales`. Without this they're
  * silently treated as default-locale content under a `/<code>/…` route, which
  * is almost never intended — usually a translation that wasn't registered.
+ * A folder named after the default locale gets the same treatment (see
+ * {@link defaultLocaleFolderDiagnostic}).
  */
 export const i18nDiagnostics = (
   pages: PageRecord[],
@@ -231,9 +262,17 @@ export const i18nDiagnostics = (
     // Inside a version snapshot the locale dir sits one level deeper
     // (`v1.0/fr/guide.md`), so a configured version segment is skipped first.
     const parts = page.source.ref.split("/");
-    const first = (
-      parts[0] && versionDirs.has(parts[0]) ? parts[1] : parts[0]
-    )?.toLowerCase();
+    const folder = parts[0] && versionDirs.has(parts[0]) ? parts[1] : parts[0];
+    const first = folder?.toLowerCase();
+    if (
+      folder !== undefined &&
+      first === i18n.defaultLocale.toLowerCase() &&
+      !seen.has(first)
+    ) {
+      seen.add(first);
+      diagnostics.push(defaultLocaleFolderDiagnostic(folder, i18n));
+      continue;
+    }
     if (
       first &&
       !seen.has(first) &&

package/src/core/last-modified.ts

@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
 
-import { relative } from "pathe";
+import { normalize, relative } from "pathe";
 
 import type { Diagnostic } from "./types.ts";
 
@@ -58,6 +59,23 @@ export const parseGitLog = (output: string): Map<string, string> => {
   return times;
 };
 
+/**
+ * `path` with every symlink resolved, the spelling git prints paths in: a
+ * project opened through a link (`/tmp/site` on macOS, where `/tmp` links to
+ * `/private/tmp`) gets `/private/tmp/site` from `rev-parse --show-toplevel`,
+ * so the project's own spelling would compare as outside the repository and
+ * every page would go undated. The native realpath also expands a Windows
+ * 8.3 short name (`RUNNER~1`), which git does too. A path that doesn't exist
+ * stays as written.
+ */
+export const realPath = (path: string): string => {
+  try {
+    return normalize(realpathSync.native(path));
+  } catch {
+    return path;
+  }
+};
+
 /**
  * The toplevel of the repository containing `root`, or null when git is
  * unavailable or the project isn't a repo. Callers use it to decide which
@@ -108,6 +126,10 @@ export const gitLastModifiedTimes = (
   if (gitRoot === null) {
     return new Map();
   }
+  // Git names paths by their real location, so the pathspecs and the paths
+  // read back against the log are compared in that spelling too (see
+  // `realPath`).
+  const top = realPath(gitRoot);
   try {
     const output = execFileSync(
       // oxlint-disable-next-line sonarjs/no-os-command-from-path -- git is a required dev-tool dependency resolved from PATH
@@ -121,14 +143,14 @@ export const gitLastModifiedTimes = (
         "--format=%x00%cI",
         "--name-only",
         "--",
-        ...contentRoots,
+        ...contentRoots.map(realPath),
       ],
       { encoding: "utf-8", env: gitEnv(), maxBuffer: 256 * 1024 * 1024 }
     );
     const byRepoPath = parseGitLog(output);
     const result = new Map<string, string>();
     for (const sourcePath of sourcePaths) {
-      const iso = byRepoPath.get(relative(gitRoot, sourcePath));
+      const iso = byRepoPath.get(relative(top, realPath(sourcePath)));
       if (iso) {
         result.set(sourcePath, iso);
       }

package/src/core/links.ts

@@ -109,10 +109,11 @@ const NUMERIC_PREFIX = /^\d+[-_.]/u;
  * falsely flagged as broken. Tested against `navPath` — the locale-stripped
  * path — so a dot-parser localized index (`index.fr.mdx`) and a shared
  * locale-agnostic one (`index.$.mdx`) count too, matching how route mapping
- * recognizes them.
+ * recognizes them. Only a lowercase `index` counts, as in route mapping:
+ * `Index.md` publishes at `…/Index`, a page of its own.
  */
 const isIndexPage = (page: PageRecord): boolean =>
-  /^index\.(?:md|mdx)$/iu.test(
+  /^index\.[Mm][Dd][Xx]?$/u.test(
     basename(page.navPath).replace(NUMERIC_PREFIX, "")
   );
 
@@ -218,14 +219,16 @@ export const resolveRelativeHref = (
  * Whether a content file is its folder's index, from its name as written on
  * disk: `index.md(x)` after an ordering prefix, optionally carrying one of
  * `localeTokens` before the extension (`index.fr.mdx` under the `dot` locale
- * parser, `index.$.mdx` for a file shared by every locale).
+ * parser, `index.$.mdx` for a file shared by every locale). The `index` itself
+ * is case-sensitive, as route mapping reads it: `Index.md` is a page named
+ * `Index`, not its folder's index.
  */
 export const isIndexFileName = (
   name: string,
   localeTokens: readonly string[] = []
 ): boolean => {
   const stem = basename(name).replace(NUMERIC_PREFIX, "");
-  const match = /^index(?:\.(?<token>[^./]+))?\.(?:md|mdx)$/iu.exec(stem);
+  const match = /^index(?:\.(?<token>[^./]+))?\.[Mm][Dd][Xx]?$/u.exec(stem);
   if (!match) {
     return false;
   }

package/src/core/load-module.ts

@@ -14,3 +14,23 @@ export const createModuleLoader = (): ((file: string) => Promise<unknown>) => {
     return loaded?.default ?? loaded;
   };
 };
+
+/**
+ * Create a loader for a module whose default export is its whole value
+ * (`blume.config.ts`). Unlike {@link createModuleLoader}, it never falls back
+ * to the module's namespace: a module with no default export, or one that
+ * exports `null`/`undefined`, resolves to `undefined` so the caller can say
+ * so, instead of validating `{}` (a bare `defineConfig({…})` call) or
+ * `{ config }` (a named export). jiti's default interop is off because it
+ * throws on `export default null`.
+ */
+export const createDefaultExportLoader: typeof createModuleLoader = () => {
+  const jiti = createJiti(import.meta.url, {
+    interopDefault: false,
+    moduleCache: false,
+  });
+  return async (file: string) => {
+    const loaded = await jiti.import<{ default?: unknown }>(file);
+    return loaded.default ?? undefined;
+  };
+};

package/src/core/locale-links.ts

@@ -1,5 +1,6 @@
 import {
   isInternalPath,
+  mountBasePath,
   normalizePath,
   stripBasePath,
   withBasePath,
@@ -44,13 +45,6 @@ export interface LocalizeLinkOptions {
   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 {
@@ -60,6 +54,13 @@ const decodePercent = (value: string): string => {
   }
 };
 
+/**
+ * Whether `routes` serves `route` (base-prefixed, fragment-less). Routes are
+ * stored decoded, so a browser-copied `/caf%C3%A9` still finds its page.
+ */
+export const servesRoute = (routes: RouteSet, route: string): boolean =>
+  routes.has(route) || routes.has(decodePercent(route));
+
 /** Whether `path` (base-stripped) already sits under some locale's prefix. */
 const hasLocalePrefix = (path: string, i18n: LocaleRouting): boolean =>
   i18n.locales.some((locale) => {
@@ -85,11 +86,9 @@ export const localizeLinkPath = (
     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;
+  // A browser-copied `/caf%C3%A9` must still find its translation, but the
+  // emitted href keeps the author's encoding.
+  return servesRoute(routes, localized) ? localized : path;
 };
 
 export interface LocalizeHrefOptions extends LocalizeLinkOptions {
@@ -98,9 +97,14 @@ export interface LocalizeHrefOptions extends LocalizeLinkOptions {
 }
 
 /**
- * Localize a rendered `href`: external URLs, relative paths, bare fragments, and
- * asset links pass through; a root-relative page link keeps its `?query` and
+ * Localize a rendered `href`: external URLs, relative paths, and bare
+ * fragments pass through; a root-relative page link keeps its `?query` and
  * `#fragment` and its `deployment.base` layer around the localized path.
+ *
+ * Asset links (`/logo.png`, a raw `.md` twin) pass through too, because no
+ * page is served at their localized path — the same served-route test the
+ * link checker applies. A file extension alone doesn't mark an asset: a
+ * dotted page route (`/releases/v1.2`) is localized like any other page.
  */
 export const localizeHref = (
   href: string,
@@ -112,15 +116,15 @@ export const localizeHref = (
   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}`;
+  // The base came off above, so it goes back on unconditionally: a localized
+  // path that starts with the base's own name (`/ja/…` under base `/ja`) is
+  // still served under it.
+  return `${mountBasePath(options.deployBase, localized)}${suffix}`;
 };
 
 /** Every `<a …>` opening tag; `\s` keeps `<abbr>`/`<astro-island>` out. */

package/src/core/manifest.ts

@@ -1,4 +1,4 @@
-import { withBasePath } from "./base-path.ts";
+import { mountBasePath } from "./base-path.ts";
 import { localizeRoute, resolveFallbackLocale } from "./i18n.ts";
 import type { ResolvedConfig } from "./schema.ts";
 import type {
@@ -106,7 +106,7 @@ const buildFallbackRoutes = (
       if (present.has(key)) {
         continue;
       }
-      const path = withBasePath(basePath, localizeRoute(key, code, i18n));
+      const path = mountBasePath(basePath, localizeRoute(key, code, i18n));
       // A fallback route is a real prerendered page, so it registers as a
       // version alternate too — the switcher on a sibling version's page
       // lands here instead of bouncing to the version root. Its own path is
@@ -183,6 +183,7 @@ export const buildManifest = (options: {
   }
 
   const routes: RouteManifestEntry[] = graph.pages.map((page) => ({
+    aiExclude: page.meta.ai.exclude,
     alternates: alternatesByKey.get(page.translationKey) ?? [],
     collection: page.collection ?? "docs",
     contentType: page.contentType,

package/src/core/meta.ts

@@ -1,5 +1,5 @@
 import { basename, dirname, relative } from "pathe";
-import { glob } from "tinyglobby";
+import { glob, isDynamicPattern } from "tinyglobby";
 
 import { diagnosticsFromZod } from "./diagnostics.ts";
 import { createModuleLoader } from "./load-module.ts";
@@ -38,12 +38,89 @@ const resolveMeta = async (mod: MetaModuleExport) =>
 
 /** A filesystem content source to scan for folder meta: its on-disk root and
  * optional route prefix. The prefix is folded into every key so meta lines up
- * with the sidebar group path, which carries the same prefix. */
+ * with the sidebar group path, which carries the same prefix. `include` and
+ * `exclude` are the source's content globs, which scope the scan to the
+ * folders the source reads. */
 export interface FolderMetaSource {
   root: string;
   prefix?: string;
+  include?: readonly string[];
+  exclude?: readonly string[];
 }
 
+/**
+ * The literal directory a glob starts from (`docs/**\/*.md` → `docs`, `""`
+ * when it matches from the root): its leading segments up to the first one
+ * with glob syntax, the file-name segment excluded.
+ */
+const globBase = (pattern: string): string => {
+  const literal: string[] = [];
+  for (const segment of pattern.split("/").slice(0, -1)) {
+    if (isDynamicPattern(segment)) {
+      break;
+    }
+    if (segment !== "" && segment !== ".") {
+      literal.push(segment);
+    }
+  }
+  return literal.join("/");
+};
+
+/** Whether `dir` is `base`, or nested beneath or above it (`""` is the root). */
+const onPathOf = (dir: string, base: string): boolean =>
+  dir === base ||
+  base === "" ||
+  dir === "" ||
+  dir.startsWith(`${base}/`) ||
+  base.startsWith(`${dir}/`);
+
+/**
+ * Whether a meta file's directory can configure a sidebar group of the
+ * source: it lies on the path of some `include` glob's base — the folders
+ * that glob reads, or the ancestors whose groups hold them. Negated globs
+ * only narrow what a source reads, so they never qualify a folder.
+ */
+const withinInclude = (
+  dir: string,
+  include: readonly string[] | undefined
+): boolean =>
+  include === undefined ||
+  include.some(
+    (pattern) => !pattern.startsWith("!") && onPathOf(dir, globBase(pattern))
+  );
+
+/**
+ * The folder-meta files a filesystem source contributes: `patterns` (every
+ * meta module name, shared `meta.$.*` included, by default) under the source's
+ * root, minus its `exclude` globs, dependencies, and build output, and only in
+ * folders its `include` globs reach. `blume translate` finds the meta files it
+ * translates through this too, so it covers exactly the ones the scan reads.
+ */
+export const findFolderMetaFiles = async (
+  source: FolderMetaSource,
+  patterns: readonly string[] = META_FILES
+): Promise<string[]> => {
+  const found = await glob([...patterns], {
+    absolute: true,
+    cwd: source.root,
+    // Never descend into dependencies or build output — relevant when the
+    // root is the project root (e.g. a `.`-rooted or all-staged project).
+    // The source's own `exclude` applies too: a `meta.ts` under an excluded
+    // folder (`src/lib/meta.ts` beside `exclude: ["src/**"]`) is application
+    // code, not folder meta, and importing it would fail.
+    ignore: [
+      ...(source.exclude ?? []),
+      "**/node_modules/**",
+      "**/.blume/**",
+      "**/dist/**",
+    ],
+    onlyFiles: true,
+  });
+  return found.filter((file) =>
+    withinInclude(relative(source.root, dirname(file)), source.include)
+  );
+};
+
 /**
  * The folder-meta key for a directory. Mirrors the sidebar group path: the
  * source's route prefix (`docs`) followed by the directory relative to the
@@ -93,7 +170,12 @@ export const discoverFolderMeta = async (
   const list: FolderMetaSource[] = Array.isArray(sources)
     ? sources
     : [{ root: sources }];
-  const localeDirs = new Set(options.localeDirs);
+  // Locale folders match case-insensitively, like content does (`pt-br/` for
+  // a configured `pt-BR`), and key under the configured casing, which is what
+  // navigation looks meta up by.
+  const localeDirs = new Map(
+    (options.localeDirs ?? []).map((code) => [code.toLowerCase(), code])
+  );
   const versionDirs = new Set(options.versionDirs);
 
   const load = createModuleLoader();
@@ -105,14 +187,7 @@ export const discoverFolderMeta = async (
   // `content.root` still contributes its folder meta.
   const perSource = await Promise.all(
     list.map(async (source) => {
-      const files = await glob(META_FILES, {
-        absolute: true,
-        cwd: source.root,
-        // Never descend into dependencies or build output — relevant when the
-        // root is the project root (e.g. a `.`-rooted or all-staged project).
-        ignore: ["**/node_modules/**", "**/.blume/**", "**/dist/**"],
-        onlyFiles: true,
-      });
+      const files = await findFolderMetaFiles(source);
       const loaded = await Promise.all(
         files.map(
           async (
@@ -149,7 +224,9 @@ export const discoverFolderMeta = async (
       const version = head && versionDirs.has(head) ? head : "";
       const afterVersion = version ? tail : [head ?? "", ...tail];
       const [localeHead, ...localeTail] = afterVersion;
-      const locale = localeHead && localeDirs.has(localeHead) ? localeHead : "";
+      const locale = localeHead
+        ? (localeDirs.get(localeHead.toLowerCase()) ?? "")
+        : "";
       const rest = (locale ? localeTail : afterVersion)
         .filter(Boolean)
         .join("/");

package/src/core/nav-diagnostics.ts

@@ -1,6 +1,8 @@
 import { isAssetIcon } from "../theme/icon-kind.ts";
 import { hasIcon } from "../theme/icons.ts";
 import { isInternalPath } from "./base-path.ts";
+import { isPageRef, normalizeRef } from "./navigation.ts";
+import type { SidebarItemConfig } from "./schema.ts";
 import type { Diagnostic, NavNode, Navigation, PageRecord } from "./types.ts";
 
 /**
@@ -137,7 +139,9 @@ export const validateNavTargets = (
     if (!isInternalPath(path) || path.startsWith("/#") || seen.has(path)) {
       continue;
     }
-    if (!resolvesToPages(routes, path.split("#")[0] ?? path)) {
+    // A query or fragment (`/guides?tab=cli`) rides on the route; only the
+    // path names a page.
+    if (!resolvesToPages(routes, path.split(/[?#]/u)[0] ?? path)) {
       seen.add(path);
       diagnostics.push({
         code: "BLUME_NAV_MISSING_PAGE",
@@ -150,6 +154,57 @@ export const validateNavTargets = (
   return diagnostics;
 };
 
+/**
+ * Warn about explicit `navigation.sidebar` items that can't render as written,
+ * instead of dropping them without a word: a page ref that matches no page
+ * (left out of the sidebar), a `root` that matches no page (its link leads
+ * nowhere), and an item with no page, `href`, `root`, or `items` (left out).
+ * `resolves` answers whether a normalized ref (`/guides`) names a page — in
+ * any locale — or a route served outside the content tree.
+ */
+export const validateSidebarItems = (
+  items: SidebarItemConfig[],
+  resolves: (route: string) => boolean
+): Diagnostic[] => {
+  const diagnostics: Diagnostic[] = [];
+  const walk = (list: SidebarItemConfig[]): void => {
+    for (const item of list) {
+      if (isPageRef(item)) {
+        if (!resolves(normalizeRef(item))) {
+          diagnostics.push({
+            code: "BLUME_NAV_MISSING_PAGE",
+            message: `Sidebar entry "${item}" matches no page, so it's left out of the sidebar.`,
+            severity: "warning",
+            suggestion: "Fix the route, or add a page at it.",
+          });
+        }
+        continue;
+      }
+      if (item.root && !resolves(normalizeRef(item.root))) {
+        diagnostics.push({
+          code: "BLUME_NAV_MISSING_PAGE",
+          message: `Sidebar entry "${item.label}" has root "${item.root}", but no page matches it, so its link leads nowhere.`,
+          severity: "warning",
+          suggestion: "Fix the root, or add a page at that route.",
+        });
+      }
+      if (item.items) {
+        walk(item.items);
+      } else if (!(item.root || item.href)) {
+        diagnostics.push({
+          code: "BLUME_NAV_EMPTY_ITEM",
+          message: `Sidebar entry "${item.label}" has no page, href, root, or items, so it's left out of the sidebar.`,
+          severity: "warning",
+          suggestion:
+            "Give it an href or a root to link somewhere, or items to make it a group.",
+        });
+      }
+    }
+  };
+  walk(items);
+  return diagnostics;
+};
+
 /** Warn about two nav items sharing a label at the same sidebar level. */
 const duplicateLabelDiagnostics = (navigation: Navigation): Diagnostic[] => {
   const diagnostics: Diagnostic[] = [];