blume 1.1.0 → 1.1.1

package/src/astro/templates.ts

@@ -410,9 +410,10 @@ export const astroConfigTemplate = (options: {
   // Twoslash runs first, before the always-on transformers, but only on fences
   // with the `twoslash` meta (explicitTrigger) — so it's opt-in per block with
   // no config flag; the TypeScript compiler only spins up when a block uses it.
-  const twoslashImport = `import { transformerTwoslash } from "@shikijs/twoslash";\n`;
-  const twoslashTransformer =
-    "transformerTwoslash({ explicitTrigger: true }), ";
+  // Blume's preconfigured transformer compiles with the package's own pinned
+  // classic TypeScript, so the user's project can be on any version (see
+  // markdown/twoslash.ts).
+  const twoslashTransformer = "blumeTwoslashTransformer(), ";
 
   // Content links are rewritten to their real served URL: the `deployment.base`
   // subdirectory (Astro doesn't rewrite `<a href>`) layered over the site-wide
@@ -449,8 +450,8 @@ export const astroConfigTemplate = (options: {
 ${defineConfigImport}
 import mdx from "@astrojs/mdx";
 import tailwindcss from "@tailwindcss/vite";
-import { blumeMarkdownProcessor, blumeMdxProcessor, blumeShikiTransformers } from "blume/markdown";
-${twoslashImport}${reactImport}${vueImport}${svelteImport}${blumeImport}${adapterImport}
+import { blumeMarkdownProcessor, blumeMdxProcessor, blumeShikiTransformers, blumeTwoslashTransformer } from "blume/markdown";
+${reactImport}${vueImport}${svelteImport}${blumeImport}${adapterImport}
 export default defineConfig({
   root: ${JSON.stringify(context.outDir)},
   srcDir: ${JSON.stringify(`${context.outDir}/src`)},
@@ -1077,7 +1078,9 @@ import data from "blume:data";
 export const prerender = true;
 
 // Custom (non-content) pages opted into a generated card, baked in at build.
-const customRoutes = ${JSON.stringify(customRoutes)};
+// The annotation keeps the empty-array case from being an implicit any[]
+// (ts(7034)) under a strict tsconfig.
+const customRoutes: { slug: string; title: string }[] = ${JSON.stringify(customRoutes)};
 
 export function getStaticPaths() {
   const seen = new Set<string>();
@@ -1803,6 +1806,23 @@ const islandDirective = (spec: IslandSpec): string =>
     ? `client:only="${spec.framework}"`
     : `client:${spec.client}`;
 
+/**
+ * Frontmatter `Props` alias mirroring the wrapped component's own props, so
+ * `{...Astro.props}` satisfies required props under `astro check` (the spread
+ * of an untyped `Astro.props` contributes nothing to the JSX props type).
+ * `infer P extends object` rather than `Record<string, unknown>` because
+ * interfaces have no implicit index signature and would miss the narrower
+ * constraint. Non-function component types (Vue/Svelte ambient modules) fall
+ * back to an open record, keeping the untyped permissiveness they had.
+ */
+const wrapperPropsType = (name: string): string =>
+  `type Props = typeof ${name} extends (
+  props: infer P extends object,
+  ...rest: never[]
+) => unknown
+  ? P
+  : Record<string, unknown>;`;
+
 /**
  * Generate `.blume/src/generated/islands/<Name>.astro` — a wrapper that renders
  * a convention island with its hydration directive applied. Astro client
@@ -1813,6 +1833,7 @@ export const islandWrapperTemplate = (spec: IslandSpec): string =>
   `---
 // Generated by Blume. Do not edit.
 import Island from ${JSON.stringify(spec.file)};
+${wrapperPropsType("Island")}
 ---
 <Island ${islandDirective(spec)} {...Astro.props}><slot /></Island>
 `;
@@ -1875,6 +1896,7 @@ export const exampleWrapperTemplate = (spec: ExampleSpec): string =>
   `---
 // Generated by Blume. Do not edit.
 import Example from ${JSON.stringify(spec.file)};
+${wrapperPropsType("Example")}
 ---
 <Example ${exampleDirective(spec)}{...Astro.props}><slot /></Example>
 `;

package/src/audit/checks/llms.ts

@@ -91,7 +91,10 @@ export const llmsChecks: CheckModule = {
         continue;
       }
       listed.add(path);
-      if (!context.byUrl.has(path)) {
+      // A listed target may be a served asset rather than a page — Blume's own
+      // llms.txt links the changelog RSS feed — so the file index vouches for
+      // it too, the same way redirect targets may land on a served asset.
+      if (!context.byUrl.has(path) && !context.files.has(path)) {
         found.push(
           finding(
             "BLUME_AUDIT_LLMS_TXT_STALE_ENTRY",

package/src/cli/commands/build.ts

@@ -402,6 +402,13 @@ const publishBuildArtifacts = async (
 
   await runClientAssetChecks(distDir, args);
 
+  // Only reachable with --no-strict (strict aborts earlier): repeat the missing
+  // count next to the success banner so it can't scroll away unseen.
+  if (project.droppedPages > 0) {
+    logger.warn(
+      `${project.droppedPages} page(s) failed frontmatter validation and are missing from this build.`
+    );
+  }
   logger.success(`Built to ${distDir}`);
 };
 
@@ -440,7 +447,12 @@ export const buildCommand = defineCommand({
       description: "Include drafts and unpublished CMS content.",
       type: "boolean",
     },
-    strict: { description: "Fail on diagnostics.", type: "boolean" },
+    strict: {
+      default: true,
+      description:
+        "Fail on error diagnostics (default; pass --no-strict to build anyway, dropping pages that fail validation).",
+      type: "boolean",
+    },
   },
   meta: {
     description: "Build the docs site for production.",

package/src/cli/prepare.ts

@@ -83,12 +83,20 @@ export const prepareProject = async (
   }
 
   const hadErrors = reportDiagnostics(project.diagnostics, options.root);
+  const dropped =
+    project.droppedPages > 0
+      ? `${project.droppedPages} page(s) failed frontmatter validation and were dropped from the site. `
+      : "";
   if (hadErrors && options.strict) {
-    logger.error("Aborting due to errors (strict mode).");
+    logger.error(
+      `Aborting due to errors. ${dropped}Fix the diagnostics above, or pass --no-strict to continue despite them.`
+    );
     process.exit(1);
   }
   if (hasErrors(project.diagnostics) && !options.strict) {
-    logger.warn("Continuing despite errors. Use --strict to fail the build.");
+    logger.warn(
+      `Continuing despite errors. ${dropped}Use --strict to fail instead.`
+    );
   }
 
   const { warnings } = await generateRuntime(project);

package/src/core/config-input.ts

@@ -568,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).
@@ -768,6 +770,13 @@ export interface OgConfig {
   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. */

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,

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,

package/src/core/navigation.ts

@@ -7,6 +7,7 @@ import type {
   SidebarItemConfig,
 } from "./schema.ts";
 import type {
+  Diagnostic,
   FeaturedLink,
   NavNode,
   Navigation,
@@ -56,7 +57,17 @@ interface MutablePage {
   badge?: string;
   deprecated?: boolean;
   pageId: string;
+  /** Absolute source path (filesystem adapter only), to anchor diagnostics. */
+  file?: string;
   order: number;
+  /**
+   * Whether `order` reflects a deliberate authoring choice (explicit
+   * `sidebar.order`, a numeric filename prefix, or a folder-meta `pages` rank)
+   * rather than a derived value like a changelog entry's publish date — two
+   * changelog entries published on the same day aren't an authoring mistake,
+   * so they're excluded from the duplicate-order diagnostic.
+   */
+  orderIsAuthored: boolean;
 }
 
 interface MutableGroup {
@@ -110,24 +121,35 @@ const ensureGroup = (
   return group;
 };
 
-const pageOrder = (page: PageRecord, filename: string): number => {
+const pageOrder = (
+  page: PageRecord,
+  filename: string
+): { order: number; orderIsAuthored: boolean } => {
   if (page.meta.sidebar.order !== undefined) {
-    return page.meta.sidebar.order;
+    return { order: page.meta.sidebar.order, orderIsAuthored: true };
   }
   if (isIndexStem(filename.replace(extname(filename), ""))) {
-    return Number.NEGATIVE_INFINITY;
+    return { order: Number.NEGATIVE_INFINITY, orderIsAuthored: false };
   }
   // Changelog entries read newest-first, matching the generated timeline. Sort
   // on the negated publish timestamp so a later date yields a smaller order
   // under the ascending comparator; undated entries fall back to filename order.
+  // The date is derived, not an authoring choice, so same-day entries aren't a
+  // duplicate-order mistake.
   if (page.contentType === "changelog") {
     const iso = page.meta.date ?? page.meta.changelog?.date;
     const time = iso ? Date.parse(iso) : Number.NaN;
     if (!Number.isNaN(time)) {
-      return -time;
+      return { order: -time, orderIsAuthored: false };
     }
   }
-  return numericOrder(filename);
+  // An undated changelog entry's numeric filename prefix is usually a date
+  // (`2024-01-05-release.md`) rather than a rank, so it is derived too.
+  const order = numericOrder(filename);
+  return {
+    order,
+    orderIsAuthored: page.contentType !== "changelog" && Number.isFinite(order),
+  };
 };
 
 /**
@@ -166,6 +188,9 @@ const applyFolderMeta = (
         const position = rank.get(child.key);
         if (position !== undefined) {
           child.order = position;
+          if (child.kind === "page") {
+            child.orderIsAuthored = true;
+          }
         }
       }
     }
@@ -178,7 +203,108 @@ const applyFolderMeta = (
   }
 };
 
-const sortNodes = (nodes: MutableNode[]): void => {
+/**
+ * Warn when an index page's own frontmatter title diverges from its folder's
+ * explicit `meta.title`. The sidebar label and the page's own `<title>`/heading
+ * are resolved from two independent sources — under i18n, a translator can
+ * update the folder's `meta.ts` and forget the index page's own frontmatter
+ * (or vice versa), and a correct-looking sidebar hides the mismatch.
+ *
+ * Only fires when the page has an explicit frontmatter `title` of its own:
+ * when it's absent, `page.title` is derived from the first heading or the
+ * filename, so it almost never coincidentally matches a custom folder title —
+ * flagging that would be noise on exactly the plain-landing-page case this is
+ * least worth warning about. The root group's `meta.title` (an empty
+ * `folderPath`) is also skipped: nothing ever renders it as a sidebar label,
+ * so a mismatch there wouldn't correspond to anything visible.
+ *
+ * Fallback-filled pages are exempt: their title belongs to the fallback
+ * locale, so comparing it against this locale's `meta.title` would flag every
+ * not-yet-translated index page (once per locale) and point the suggestion at
+ * the fallback locale's source file, where "fixing" it would break that
+ * locale. The default locale's own build still checks the real page.
+ */
+const indexTitleMismatchDiagnostic = (
+  page: PageRecord,
+  folderPath: string,
+  folderMeta: Map<string, FolderMeta>,
+  sharedMeta: Map<string, FolderMeta>,
+  metaPrefix: string
+): Diagnostic | undefined => {
+  if (!page.meta.title || page.fallback || folderPath === "") {
+    return undefined;
+  }
+  const meta =
+    folderMeta.get(metaKey(folderPath, metaPrefix)) ??
+    sharedMeta.get(folderPath);
+  if (!meta?.title || meta.title === page.title) {
+    return undefined;
+  }
+  return {
+    code: "BLUME_NAV_INDEX_TITLE_MISMATCH",
+    file: page.sourcePath ?? page.id,
+    message: `Index page "${page.navPath}" has title "${page.title}", but its folder's meta.title is "${meta.title}" — the sidebar shows the folder title while the page's own <title>/heading still say "${page.title}".`,
+    severity: "warning",
+    suggestion: `Update the page's frontmatter title to match ("${meta.title}"), or leave it if the divergence is intentional.`,
+  };
+};
+
+/** Whether a node's `order` reflects a deliberate authoring choice. */
+const isAuthoredOrder = (node: MutableNode): boolean =>
+  node.kind === "group" || node.orderIsAuthored;
+
+/**
+ * Warn when two sibling nodes share an explicit/numeric order (frontmatter
+ * `sidebar.order`, a numeric filename prefix, or folder-meta `order`) — they'd
+ * otherwise fall back to a silent, arbitrary alphabetical tiebreak. Nodes at
+ * the default fallback order (no numeric prefix, no explicit order) are
+ * excluded: that's the common, intentional case of "just sort alphabetically."
+ * So is a derived, non-authored order (e.g. two changelog entries published
+ * on the same day) — not an authoring mistake.
+ */
+const duplicateOrderDiagnostics = (nodes: MutableNode[]): Diagnostic[] => {
+  const byOrder = new Map<number, MutableNode[]>();
+  for (const node of nodes) {
+    if (!Number.isFinite(node.order) || !isAuthoredOrder(node)) {
+      continue;
+    }
+    const tied = byOrder.get(node.order);
+    if (tied) {
+      tied.push(node);
+    } else {
+      byOrder.set(node.order, [node]);
+    }
+  }
+  const diagnostics: Diagnostic[] = [];
+  for (const [order, tied] of byOrder) {
+    if (tied.length > 1) {
+      const names = tied.map((node) => `"${node.label}"`);
+      const list =
+        names.length > 2
+          ? `${names.slice(0, -1).join(", ")}, and ${names.at(-1)}`
+          : names.join(" and ");
+      const verb = tied.length > 2 ? "all have" : "both have";
+      // Anchor the diagnostic to one tied source file so tooling can point
+      // somewhere concrete; the message names the rest. Folder-only ties
+      // (folder-meta `order`) have no single file, so `file` stays unset.
+      const file = tied.find(
+        (node): node is MutablePage => node.kind === "page"
+      )?.file;
+      diagnostics.push({
+        code: "BLUME_DUPLICATE_SIDEBAR_ORDER",
+        file,
+        message: `${list} ${verb} sidebar order ${order}; falling back to alphabetical order.`,
+        severity: "warning",
+        suggestion:
+          "Give each item a distinct sidebar.order (or folder meta order).",
+      });
+    }
+  }
+  return diagnostics;
+};
+
+const sortNodes = (nodes: MutableNode[], diagnostics: Diagnostic[]): void => {
+  diagnostics.push(...duplicateOrderDiagnostics(nodes));
   nodes.sort((a, b) => {
     if (a.order !== b.order) {
       return a.order - b.order;
@@ -187,7 +313,7 @@ const sortNodes = (nodes: MutableNode[]): void => {
   });
   for (const node of nodes) {
     if (node.kind === "group") {
-      sortNodes(node.children);
+      sortNodes(node.children, diagnostics);
     }
   }
 };
@@ -263,20 +389,37 @@ const buildFileSystemSidebar = (
   sharedMeta: Map<string, FolderMeta>,
   metaPrefix: string,
   display: SidebarDisplay,
-  tabPaths: Set<string>
+  tabPaths: Set<string>,
+  diagnostics: Diagnostic[] = []
 ): NavNode[] => {
   const root = createGroup("", "", "", 0);
 
   for (const page of pages) {
-    if (page.meta.sidebar.hidden) {
-      continue;
-    }
     // Group by the locale-stripped path so the locale dir is not a nav group.
     const parts = page.navPath.split("/");
     const filename = parts.at(-1) ?? page.navPath;
     const stem = filename.replace(extname(filename), "");
     const dirs = parts.slice(0, -1);
 
+    // Checked before the hidden filter: a sidebar-hidden index page still
+    // renders with its own <title>, so title drift matters there just the same.
+    if (isIndexStem(stem)) {
+      const diagnostic = indexTitleMismatchDiagnostic(
+        page,
+        dirs.join("/"),
+        folderMeta,
+        sharedMeta,
+        metaPrefix
+      );
+      if (diagnostic) {
+        diagnostics.push(diagnostic);
+      }
+    }
+
+    if (page.meta.sidebar.hidden) {
+      continue;
+    }
+
     // Each group's URL path is the matching prefix of the page's route. navPath
     // is locale-stripped while the route may carry a locale/base prefix, so
     // align the folder segments from the right (the extra leading segments are
@@ -301,22 +444,25 @@ const buildFileSystemSidebar = (
       parent.routePath ??= `/${folderParts.slice(0, consumed).join("/")}`;
     }
 
+    const { order, orderIsAuthored } = pageOrder(page, filename);
     parent.children.push({
       badge: page.meta.sidebar.badge,
       deprecated: page.meta.deprecated || undefined,
       description: page.description,
+      file: page.sourcePath,
       icon: page.meta.sidebar.icon,
       key: segmentKey(stem),
       kind: "page",
       label: page.meta.sidebar.label ?? page.title,
-      order: pageOrder(page, filename),
+      order,
+      orderIsAuthored,
       pageId: page.id,
       route: page.route,
     });
   }
 
   applyFolderMeta(root, folderMeta, sharedMeta, metaPrefix);
-  sortNodes(root.children);
+  sortNodes(root.children, diagnostics);
   hoistPages(root.children, display === "flat");
   hoistTabSections(root.children, tabPaths, display === "flat");
   return root.children.map((child) => toNavNode(child, display));
@@ -500,6 +646,12 @@ export const buildNavigation = (
      * scoping.
      */
     localizedRoot?: string;
+    /**
+     * Sink for diagnostics produced while building the tree (duplicate sidebar
+     * `order` values, index-page title/folder-meta-title mismatches). Pushed
+     * into in place; omit to discard.
+     */
+    diagnostics?: Diagnostic[];
   }
 ): Navigation => {
   const basePath = options.basePath ?? "";
@@ -583,7 +735,10 @@ export const buildNavigation = (
     sharedFolderMeta,
     metaPrefix,
     display,
-    new Set(tabs.flatMap((tab) => (tab.path === rootTabPath ? [] : [tab.path])))
+    new Set(
+      tabs.flatMap((tab) => (tab.path === rootTabPath ? [] : [tab.path]))
+    ),
+    options.diagnostics
   );
   return {
     featured,

package/src/core/project-graph.ts

@@ -15,7 +15,7 @@ import { resolveProjectContext } from "./project.ts";
 import type { ResolvedConfig } from "./schema.ts";
 import { normalizeEntry } from "./sources/normalize.ts";
 import { resolveDocsCollection, resolveSources } from "./sources/resolve.ts";
-import type { ContentSource } from "./sources/types.ts";
+import type { ContentSource, SourceLoadResult } from "./sources/types.ts";
 import type {
   BlumeManifest,
   ContentGraph,
@@ -70,6 +70,8 @@ export interface BlumeProject {
   graph: ContentGraph;
   manifest: BlumeManifest;
   diagnostics: Diagnostic[];
+  /** Entries excluded from the graph because their frontmatter failed validation. */
+  droppedPages: number;
   /** The instantiated content sources, for lazy entry reads (search/AI/raw). */
   sources: ContentSource[];
 }
@@ -116,6 +118,51 @@ const entryIdDiagnostics = (
   return diagnostics;
 };
 
+/**
+ * Funnel every loaded source's entries through the shared `normalizeEntry`,
+ * collecting pages, diagnostics, and the count of entries dropped outright —
+ * an entry that yields no pages but did yield diagnostics was rejected for
+ * invalid frontmatter, and callers surface that count so a build with missing
+ * pages can't read as clean.
+ */
+const normalizeLoadedEntries = (
+  loaded: ({ source: ContentSource } & SourceLoadResult)[],
+  config: ResolvedConfig
+): { pages: PageRecord[]; diagnostics: Diagnostic[]; droppedPages: number } => {
+  // Only thread `frontmatter.extend` through when a project opts in, so the
+  // known-key split in `normalizeEntry` stays off the default path.
+  const frontmatterExtend =
+    Object.keys(config.frontmatter.extend).length > 0
+      ? config.frontmatter.extend
+      : undefined;
+
+  const pages: PageRecord[] = [];
+  const allDiagnostics: Diagnostic[] = [];
+  let droppedPages = 0;
+  for (const { source, entries, diagnostics } of loaded) {
+    allDiagnostics.push(...diagnostics);
+    for (const entry of entries) {
+      const normalized = normalizeEntry(entry, {
+        basePath: config.basePath,
+        defaultType: config.content.defaultType,
+        frontmatterExtend,
+        i18n: config.i18n,
+        source: {
+          name: source.name,
+          prefix: source.prefix,
+          staged: source.staged,
+        },
+      });
+      if (normalized.pages.length === 0 && normalized.diagnostics.length > 0) {
+        droppedPages += 1;
+      }
+      pages.push(...normalized.pages);
+      allDiagnostics.push(...normalized.diagnostics);
+    }
+  }
+  return { diagnostics: allDiagnostics, droppedPages, pages };
+};
+
 /**
  * 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.
@@ -190,33 +237,11 @@ export const scanProject = async (
     discoverFolderMeta(metaSources, { localeDirs }),
   ]);
 
-  // Only thread `frontmatter.extend` through when a project opts in, so the
-  // known-key split in `normalizeEntry` stays off the default path.
-  const frontmatterExtend =
-    Object.keys(config.frontmatter.extend).length > 0
-      ? config.frontmatter.extend
-      : undefined;
-
-  const allPages: PageRecord[] = [];
-  const contentDiagnostics: Diagnostic[] = [];
-  for (const { source, entries, diagnostics } of loaded) {
-    contentDiagnostics.push(...diagnostics);
-    for (const entry of entries) {
-      const normalized = normalizeEntry(entry, {
-        basePath: config.basePath,
-        defaultType: config.content.defaultType,
-        frontmatterExtend,
-        i18n: config.i18n,
-        source: {
-          name: source.name,
-          prefix: source.prefix,
-          staged: source.staged,
-        },
-      });
-      allPages.push(...normalized.pages);
-      contentDiagnostics.push(...normalized.diagnostics);
-    }
-  }
+  const {
+    diagnostics: contentDiagnostics,
+    droppedPages,
+    pages: allPages,
+  } = normalizeLoadedEntries(loaded, config);
 
   // Drafts render in dev and in preview, but are excluded from production builds.
   const pages =
@@ -267,6 +292,7 @@ export const scanProject = async (
       ...graph.diagnostics,
       ...i18nWarnings,
     ],
+    droppedPages,
     graph,
     manifest,
     mode,