blume 1.0.4 → 1.1.0

package/src/core/nav-diagnostics.ts

@@ -55,10 +55,13 @@ const collectIcons = (
 };
 
 /** Warn about icon names that aren't in Blume's set (skipping image/SVG icons). */
-export const validateNavIcons = (navigation: Navigation): Diagnostic[] => {
+const unknownIconDiagnostics = (
+  icons: { icon: string; where: string }[],
+  suggestion: string
+): Diagnostic[] => {
   const seen = new Set<string>();
   const diagnostics: Diagnostic[] = [];
-  for (const { icon, where } of collectIcons(navigation)) {
+  for (const { icon, where } of icons) {
     if (isAssetIcon(icon) || hasIcon(icon) || seen.has(icon)) {
       continue;
     }
@@ -67,13 +70,54 @@ export const validateNavIcons = (navigation: Navigation): Diagnostic[] => {
       code: "BLUME_UNKNOWN_ICON",
       message: `Unknown icon "${icon}" (${where}) — it isn't in Blume's icon set.`,
       severity: "warning",
-      suggestion:
-        "Use a built-in icon name, an image path/URL, or inline SVG markup.",
+      suggestion,
     });
   }
   return diagnostics;
 };
 
+/** Warn about icon names that aren't in Blume's set (skipping image/SVG icons). */
+export const validateNavIcons = (navigation: Navigation): Diagnostic[] =>
+  unknownIconDiagnostics(
+    collectIcons(navigation),
+    "Use a built-in icon name, an image path/URL, or inline SVG markup."
+  );
+
+/**
+ * Warn about unknown icons on curated `search.popular` links. Separate from
+ * {@link validateNavIcons} because these live under `search`, not the built
+ * navigation — and unlike nav icons they resolve in a *client* island, so only
+ * set names work (an image/SVG icon quietly falls back to the file glyph).
+ */
+export const validateSearchPopularIcons = (
+  popular: { icon?: string; label: string }[]
+): Diagnostic[] => {
+  const icons = popular.flatMap((link) =>
+    link.icon
+      ? [{ icon: link.icon, where: `popular link "${link.label}"` }]
+      : []
+  );
+  // Asset icons are valid in the nav, so the shared helper skips them — but
+  // here they are exactly the silent failure this validator exists to catch.
+  const diagnostics: Diagnostic[] = [];
+  const seen = new Set<string>();
+  for (const { icon, where } of icons) {
+    if (isAssetIcon(icon) && !seen.has(icon)) {
+      seen.add(icon);
+      diagnostics.push({
+        code: "BLUME_UNKNOWN_ICON",
+        message: `Icon "${icon}" (${where}) is an image or inline SVG — popular links render in the client search island, where only built-in icon names resolve, so it falls back to the file glyph.`,
+        severity: "warning",
+        suggestion: "Use a built-in icon name.",
+      });
+    }
+  }
+  return [
+    ...diagnostics,
+    ...unknownIconDiagnostics(icons, "Use a built-in icon name."),
+  ];
+};
+
 /** Whether an internal path resolves to a page or a section that has pages. */
 const resolvesToPages = (routes: Set<string>, path: string): boolean =>
   routes.has(path) || [...routes].some((route) => route.startsWith(`${path}/`));

package/src/core/probe.ts

@@ -0,0 +1,136 @@
+import type { DiagnosticSeverity } from "./types.ts";
+
+export const PROBE_CONCURRENCY = 8;
+export const PROBE_TIMEOUT_MS = 10_000;
+
+const STATUS_NOT_FOUND = 404;
+const STATUS_GONE = 410;
+const STATUS_METHOD_NOT_ALLOWED = 405;
+const STATUS_NOT_IMPLEMENTED = 501;
+
+/** The outcome of a single HTTP probe, with failures normalized rather than thrown. */
+export interface ProbeResult {
+  ok: boolean;
+  status?: number;
+  timedOut?: boolean;
+  error?: string;
+  /** Whether the request was redirected before landing on `status`. */
+  redirected?: boolean;
+  /** The URL finally landed on, after following redirects. */
+  finalUrl?: string;
+  /** `Content-Encoding` of the response, when the server set one. */
+  encoding?: string | null;
+  /** Wall-clock milliseconds for the request. */
+  ms?: number;
+  /** `X-Robots-Tag` of the response, when the server set one. */
+  robotsTag?: string | null;
+}
+
+/** Probe a URL with the given method, normalizing failures to a result. */
+const request = async (
+  url: string,
+  method: "GET" | "HEAD",
+  timeoutMs: number
+): Promise<ProbeResult> => {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  const started = performance.now();
+  try {
+    const response = await fetch(url, {
+      method,
+      redirect: "follow",
+      signal: controller.signal,
+    });
+    return {
+      encoding: response.headers.get("content-encoding"),
+      finalUrl: response.url,
+      ms: Math.round(performance.now() - started),
+      ok: response.ok,
+      redirected: response.redirected,
+      robotsTag: response.headers.get("x-robots-tag"),
+      status: response.status,
+    };
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      return { ok: false, timedOut: true };
+    }
+    return {
+      error: error instanceof Error ? error.message : String(error),
+      ok: false,
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+/**
+ * Probe a single URL: HEAD first, falling back to GET.
+ *
+ * Plenty of servers reject HEAD outright (405/501) or drop the connection, so a
+ * HEAD-only probe would report healthy pages as dead.
+ */
+export const probe = async (
+  url: string,
+  options: { timeoutMs?: number } = {}
+): Promise<ProbeResult> => {
+  const timeoutMs = options.timeoutMs ?? PROBE_TIMEOUT_MS;
+  const head = await request(url, "HEAD", timeoutMs);
+  const unreachable = !head.ok && head.status === undefined && !head.timedOut;
+  const retry =
+    head.status === STATUS_METHOD_NOT_ALLOWED ||
+    head.status === STATUS_NOT_IMPLEMENTED ||
+    unreachable;
+  return retry ? await request(url, "GET", timeoutMs) : head;
+};
+
+/** Grade a probe result into a severity + detail, or null when the URL is fine. */
+export const gradeExternal = (
+  result: ProbeResult
+): { severity: DiagnosticSeverity; detail: string } | null => {
+  if (result.ok) {
+    return null;
+  }
+  if (result.timedOut) {
+    return { detail: "request timed out", severity: "warning" };
+  }
+  if (result.status === undefined) {
+    return { detail: result.error ?? "unreachable", severity: "error" };
+  }
+  // A 404/410 is definitively dead. A 403/429/5xx may well be rate limiting or a
+  // transient blip, which is not the author's bug to fix.
+  if (result.status === STATUS_NOT_FOUND || result.status === STATUS_GONE) {
+    return { detail: `HTTP ${result.status}`, severity: "error" };
+  }
+  return { detail: `HTTP ${result.status}`, severity: "warning" };
+};
+
+/**
+ * Probe many URLs with bounded concurrency, deduplicating first. Returns a map
+ * from URL to its result — the caller decides what each one means.
+ */
+export const probeAll = async (
+  urls: readonly string[],
+  options: { concurrency?: number; timeoutMs?: number } = {}
+): Promise<Map<string, ProbeResult>> => {
+  const unique = [...new Set(urls)];
+  const results = new Map<string, ProbeResult>();
+  const limit = Math.min(
+    options.concurrency ?? PROBE_CONCURRENCY,
+    unique.length
+  );
+
+  let cursor = 0;
+  const worker = async (): Promise<void> => {
+    while (cursor < unique.length) {
+      const url = unique[cursor];
+      cursor += 1;
+      if (url !== undefined) {
+        // oxlint-disable-next-line no-await-in-loop -- bounded-concurrency pool
+        results.set(url, await probe(url, options));
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: limit }, worker));
+
+  return results;
+};

package/src/core/project-graph.ts

@@ -190,6 +190,13 @@ 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) {
@@ -198,6 +205,7 @@ export const scanProject = async (
       const normalized = normalizeEntry(entry, {
         basePath: config.basePath,
         defaultType: config.content.defaultType,
+        frontmatterExtend,
         i18n: config.i18n,
         source: {
           name: source.name,

package/src/core/schema.ts

@@ -7,6 +7,8 @@ import { FONT_SLUGS, isFontSlug } from "../theme/fonts.ts";
 import { normalizeBasePath } from "./base-path.ts";
 import { uiLocaleOverridesSchema } from "./i18n-ui.ts";
 import type { ContentSource } from "./sources/types.ts";
+import { isStandardSchema } from "./standard-schema.ts";
+import type { StandardSchema } from "./standard-schema.ts";
 
 /**
  * Public Blume schemas.
@@ -514,6 +516,13 @@ const PROVIDER_CONFIG_KEY = {
   typesense: "typesense",
 } as const;
 
+/** Curated link for the search dialog empty state (internal route or external URL). */
+const searchPopularLinkSchema = z.strictObject({
+  href: z.string(),
+  icon: iconName.optional(),
+  label: z.string(),
+});
+
 const searchConfigSchema = z
   .strictObject({
     algolia: algoliaSearchSchema.optional(),
@@ -524,6 +533,8 @@ const searchConfigSchema = z
       .default({}),
     mixedbread: mixedbreadSearchSchema.optional(),
     oramaCloud: oramaCloudSearchSchema.optional(),
+    /** Curated links for the Cmd+K empty state; defaults to the first sidebar pages. */
+    popular: z.array(searchPopularLinkSchema).default([]),
     provider: z.enum(searchProviders).default("orama"),
     typesense: typesenseSearchSchema.optional(),
   })
@@ -802,9 +813,14 @@ const xConfigSchema = z.strictObject({
   handle: xHandleSchema,
 });
 
-const ogColorSchema = z
-  .string()
-  .regex(/^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/iu);
+/**
+ * Any CSS color. Takumi parses the full grammar, so this stays unvalidated
+ * here and a bad value fails the OG prerender with a parse error naming it —
+ * the same fail-fast the card's accent relies on. Validating hex-only here
+ * would reject `oklch(…)`, which `theme.accent` (the card's default accent)
+ * already accepts.
+ */
+const ogColorSchema = z.string();
 
 const ogPaletteSchema = z.strictObject({
   accent: ogColorSchema.optional(),
@@ -814,6 +830,28 @@ const ogPaletteSchema = z.strictObject({
   muted: ogColorSchema.optional(),
 });
 
+/**
+ * A Google Font family to load into the OG card renderer. A bare string is the
+ * family name; the object form pins the weight (a number, a list, or a variable
+ * range like `"100..900"`) and style. Fetched from Google Fonts at build and
+ * handed to Takumi, which does per-glyph fallback so a family covering a script
+ * (e.g. Noto Sans JP for CJK) fixes tofu without touching how Latin renders.
+ */
+const ogFontWeightSchema = z.union([
+  z.number().int().positive(),
+  z.array(z.number().int().positive()),
+  z.string().regex(/^\d+\.\.\d+$/u),
+]);
+const ogFontStyleSchema = z.enum(["normal", "italic"]);
+const ogFontSchema = z.union([
+  z.string(),
+  z.strictObject({
+    name: z.string(),
+    style: z.union([ogFontStyleSchema, z.array(ogFontStyleSchema)]).optional(),
+    weight: ogFontWeightSchema.optional(),
+  }),
+]);
+
 const ogConfigSchema = z.strictObject({
   /**
    * Generate a per-page Open Graph image. Defaults to on once a deployment
@@ -822,6 +860,12 @@ const ogConfigSchema = z.strictObject({
    * `loadConfig`. An explicit value here always wins.
    */
   enabled: z.boolean().optional(),
+  /**
+   * 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.
+   */
+  fonts: z.array(ogFontSchema).optional(),
   /** Local SVG used in the generated card instead of the site logo. */
   logo: z.string().optional(),
   /** Optional generated-card colors. */
@@ -1041,6 +1085,41 @@ const asyncapiConfigSchema = z.strictObject({
   theme: z.string().optional(),
 });
 
+/**
+ * Opt-in custom frontmatter keys. `extend` maps each extra key a project's
+ * pages may carry (e.g. `owner`, `reviewedAt`) to a validation schema; the
+ * page schema stays strict for everything else, so typo-catching is preserved.
+ * Schemas are consumed through the Standard Schema `~standard` contract —
+ * never Zod's own API — so the consumer's zod (any version), Valibot, or
+ * ArkType all work (see `standard-schema.ts`). 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. Built-in
+ * frontmatter fields can't be redeclared — they're load-bearing (routing,
+ * sidebar, SEO), and shadowing one would silently change its semantics.
+ */
+const frontmatterConfigSchema = z.strictObject({
+  extend: z
+    .record(
+      z.string(),
+      z.custom<StandardSchema>(isStandardSchema, {
+        message:
+          "Expected a Standard Schema (e.g. a Zod schema — any Zod version works).",
+      })
+    )
+    .default({})
+    .superRefine((value, ctx) => {
+      for (const key of Object.keys(value)) {
+        if (Object.hasOwn(pageMetaBaseSchema.shape, key)) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `"${key}" is a built-in frontmatter field and cannot be redeclared via frontmatter.extend.`,
+            path: [key],
+          });
+        }
+      }
+    }),
+});
+
 /** Full user-facing config schema. All fields optional with defaults. */
 /**
  * Table-of-contents config. `true`/`false` toggles it; an object narrows the
@@ -1101,6 +1180,8 @@ export const blumeConfigSchema = z.strictObject({
   examples: examplesConfigSchema.default("examples"),
   export: exportConfigSchema.default(false),
   feedback: z.boolean().default(true),
+  /** Opt-in custom frontmatter keys, validated by user-supplied schemas. */
+  frontmatter: frontmatterConfigSchema.default({}),
   github: githubConfigSchema.optional(),
   i18n: i18nConfigSchema.optional(),
   lastModified: lastModifiedConfigSchema.default(false),
@@ -1119,6 +1200,8 @@ export const blumeConfigSchema = z.strictObject({
 
 /** Resolved config: every field present after defaults are applied. */
 export type ResolvedConfig = z.infer<typeof blumeConfigSchema>;
+/** Resolved `frontmatter.extend`: custom key → user-supplied schema. */
+export type FrontmatterExtend = Record<string, StandardSchema>;
 /** Resolved i18n block (present only when the project opts into i18n). */
 export type ResolvedI18nConfig = z.infer<typeof i18nConfigSchema>;
 /** A configured locale with display metadata. */

package/src/core/sources/normalize.ts

@@ -4,10 +4,10 @@ import GithubSlugger from "github-slugger";
 import { extname } from "pathe";
 
 import { withBasePath } from "../base-path.ts";
-import { diagnosticsFromZod } from "../diagnostics.ts";
+import { diagnosticsFromIssues, diagnosticsFromZod } from "../diagnostics.ts";
 import { localePlacement, localizeRoute } from "../i18n.ts";
 import { pageMetaSchema } from "../schema.ts";
-import type { PageMeta } from "../schema.ts";
+import type { FrontmatterExtend, PageMeta } from "../schema.ts";
 import type { Diagnostic, Heading, PageLink, PageRecord } from "../types.ts";
 import type { NormalizeContext, SourceEntry } from "./types.ts";
 
@@ -131,6 +131,21 @@ const PARAGRAPH_INTERRUPT = /^ {0,3}(?:[-+*][ \t]|\d{1,9}[.)][ \t]|>)/u;
 const THEMATIC_BREAK =
   /^ {0,3}(?:(?:-[ \t]*){3,}|(?:\*[ \t]*){3,}|(?:_[ \t]*){3,})$/u;
 const FRONT_MATTER_CLOSE = /^(?:-{3}|\.{3})\s*$/u;
+// `<Prompt>` renders its children into a permanently `hidden` DOM node (see
+// `Prompt.astro`) — the agent-facing prompt text is never visible page
+// content, only read by client JS for the copy button. Any `##` inside it
+// must not surface in the page's heading-derived table of contents. Tracked
+// as an open/close depth, the same way fenced code blocks are tracked above.
+// The opening tag is matched only at the start of a trimmed line: block-level
+// JSX in MDX starts its own line, so a mention mid-prose or mid-heading —
+// "the `<Prompt>` component", `## Using <Prompt>` — never opens a hidden
+// region (an unanchored match here silently ate every heading after the
+// mention). The lookahead rejects longer tag names that share the prefix,
+// like `<PromptCard>` or `<Prompt-Custom>`.
+const PROMPT_OPEN = /^<Prompt(?![\w-])/u;
+// Unanchored: while inside a prompt the close tag may trail the hidden
+// children text (`...copy this.</Prompt>`), not just sit on its own line.
+const PROMPT_CLOSE = /<\/Prompt>/u;
 
 /**
  * The body lines, minus a leading front matter block. Bodies from the
@@ -155,13 +170,46 @@ interface HeadingScanState {
   fence: FenceState;
   /** Consecutive paragraph lines — the candidate text for a setext underline. */
   paragraph: string[];
+  /** Nesting depth inside `<Prompt>...</Prompt>` — 0 when outside one. */
+  promptDepth: number;
+  /** True inside a multi-line `<Prompt` opening tag, awaiting its `>`. */
+  promptTag: boolean;
 }
 
+/**
+ * Consume the rest of a `<Prompt` opening tag, scanning a trimmed line from
+ * `start`. The tag's attributes may spread over several lines
+ * (`state.promptTag` carries the search onto the next one), and until the
+ * terminating `>` arrives it isn't known whether the tag even has children —
+ * so the depth only rises once that `>` is found, and not when it turns out
+ * to be `/>` or when the element also closes on the same line
+ * (`<Prompt ...>copy this</Prompt>`). Attribute values containing `>` are not
+ * parsed: the first `>` ends the tag, which errs toward opening a region a
+ * real close tag will still exit.
+ */
+const finishPromptTag = (
+  line: string,
+  start: number,
+  state: HeadingScanState
+): void => {
+  const end = line.indexOf(">", start);
+  if (end === -1) {
+    state.promptTag = true;
+    return;
+  }
+  state.promptTag = false;
+  if (line[end - 1] === "/" || line.includes("</Prompt>", end)) {
+    return;
+  }
+  state.promptDepth += 1;
+};
+
 /**
  * Extract ATX and setext headings from a markdown body, skipping fenced code
- * blocks, exactly as the renderer sees them: ATX headings may be indented up
- * to 3 spaces, and a paragraph underlined with `=`/`-` is a level 1/2 setext
- * heading. Each heading's anchor slug comes from a per-document
+ * blocks and `<Prompt>` children, exactly as the renderer sees them: ATX
+ * headings may be indented up to 3 spaces, and a paragraph underlined with
+ * `=`/`-` is a level 1/2 setext heading. Each heading's anchor slug comes
+ * from a per-document
  * `github-slugger` — the exact slugger the renderer uses
  * (`markdown/heading-anchors`) — advanced over every heading in document
  * order. Matching it (rather than a hand-rolled slugify) keeps the manifest's
@@ -185,6 +233,28 @@ const scanHeadingLine = (
     state.paragraph = [];
     return;
   }
+  // Prompt tags may be indented arbitrarily (MDX has no indented code
+  // blocks), so they match against the trimmed line. A tag line can't also
+  // be a heading, so each just updates the state and moves on, same as a
+  // fence delimiter line. Outside a prompt, a `</Prompt>` line is plain text.
+  const trimmed = line.trimStart();
+  if (state.promptTag) {
+    finishPromptTag(trimmed, 0, state);
+    state.paragraph = [];
+    return;
+  }
+  if (PROMPT_OPEN.test(trimmed)) {
+    finishPromptTag(trimmed, "<Prompt".length, state);
+    state.paragraph = [];
+    return;
+  }
+  if (state.promptDepth > 0) {
+    if (PROMPT_CLOSE.test(line)) {
+      state.promptDepth -= 1;
+    }
+    state.paragraph = [];
+    return;
+  }
   const atx = line.match(ATX_HEADING);
   if (atx?.groups) {
     const depth = atx.groups.hashes?.length ?? 1;
@@ -220,7 +290,12 @@ const scanHeadingLine = (
 export const extractHeadings = (body: string): Heading[] => {
   const headings: Heading[] = [];
   const slugger = new GithubSlugger();
-  const state: HeadingScanState = { fence: null, paragraph: [] };
+  const state: HeadingScanState = {
+    fence: null,
+    paragraph: [],
+    promptDepth: 0,
+    promptTag: false,
+  };
 
   for (const line of linesWithoutFrontMatter(body)) {
     scanHeadingLine(line, state, slugger, headings);
@@ -364,6 +439,118 @@ const withPrefix = (prefix: string | undefined, path: string): string => {
   return clean ? `${clean}/${path}` : path;
 };
 
+/** A custom-key validation failure, lowered to a joinable diagnostic path. */
+interface CustomKeyIssue {
+  message: string;
+  path: (string | number)[];
+}
+
+/** Lower a Standard Schema path segment (`key` or `{ key }`) for joining. */
+const segmentKey = (
+  segment: PropertyKey | { readonly key: PropertyKey }
+): string | number => {
+  const key =
+    typeof segment === "object" && segment !== null ? segment.key : segment;
+  return typeof key === "symbol" ? String(key) : key;
+};
+
+/**
+ * Validate the opt-in custom frontmatter keys (`frontmatter.extend`) through
+ * the Standard Schema contract — the consumer's own Zod (any version),
+ * Valibot, or ArkType, never Blume's bundled zod (see `standard-schema.ts`).
+ * Every declared key is checked, absent ones included, so a required schema
+ * enforces its key on every page. Async schemas are rejected with a
+ * diagnostic: this funnel is synchronous, and frontmatter validation has no
+ * business awaiting I/O.
+ */
+const validateCustomKeys = (
+  data: Record<string, unknown>,
+  extend: FrontmatterExtend
+): { custom?: Record<string, unknown>; issues: CustomKeyIssue[] } => {
+  const custom: Record<string, unknown> = {};
+  const issues: CustomKeyIssue[] = [];
+  for (const [key, schema] of Object.entries(extend)) {
+    const outcome = schema["~standard"].validate(data[key]);
+    if (outcome instanceof Promise) {
+      issues.push({
+        message: "Async schemas are not supported in frontmatter.extend.",
+        path: [key],
+      });
+      continue;
+    }
+    if (outcome.issues !== undefined) {
+      issues.push(
+        ...outcome.issues.map((issue) => ({
+          message: issue.message,
+          path: [key, ...(issue.path ?? []).map(segmentKey)],
+        }))
+      );
+      continue;
+    }
+    // Preserve the validated (schema-output) value; skip keys that are absent
+    // and stay absent, so `.optional()` extras don't materialize as undefined.
+    if (outcome.value !== undefined || Object.hasOwn(data, key)) {
+      custom[key] = outcome.value;
+    }
+  }
+  return {
+    custom: Object.keys(custom).length > 0 ? custom : undefined,
+    issues,
+  };
+};
+
+/**
+ * Parse an entry's frontmatter: built-in keys through the strict page schema,
+ * custom keys (`frontmatter.extend`) through their user-supplied schemas. The
+ * custom keys are carved out before the strict parse, so the page schema stays
+ * strict for everything else and unknown-key typo catching is unchanged.
+ * Returns diagnostics instead of meta when either side rejects.
+ */
+const parseEntryMeta = (
+  entry: SourceEntry,
+  ctx: NormalizeContext
+):
+  | { meta: PageMeta; custom?: Record<string, unknown>; diagnostics?: never }
+  | { meta?: never; diagnostics: Diagnostic[] } => {
+  const extend = ctx.frontmatterExtend;
+  const known = extend
+    ? Object.fromEntries(
+        Object.entries(entry.data).filter(
+          ([key]) => !Object.hasOwn(extend, key)
+        )
+      )
+    : entry.data;
+
+  const result = pageMetaSchema.safeParse(known);
+  const customResult = extend ? validateCustomKeys(entry.data, extend) : null;
+
+  if (result.success && (customResult?.issues.length ?? 0) === 0) {
+    return { custom: customResult?.custom, meta: result.data };
+  }
+
+  // Source text lets the error carry a line/column into the frontmatter block:
+  // `entry.raw` for non-filesystem sources, else the file itself (read only on
+  // this rare error path, so filesystem entries stay cheap in the happy path).
+  const source =
+    entry.raw ??
+    (entry.sourcePath && existsSync(entry.sourcePath)
+      ? readFileSync(entry.sourcePath, "utf-8")
+      : undefined);
+  const location = {
+    code: "BLUME_FRONTMATTER_INVALID",
+    file: entry.sourcePath ?? `${ctx.source.name}:${entry.ref}`,
+    source,
+  };
+  return {
+    diagnostics: [
+      ...(result.success ? [] : diagnosticsFromZod(result.error, location)),
+      ...(customResult
+        ? diagnosticsFromIssues(customResult.issues, location)
+        : []),
+    ],
+  };
+};
+
 /**
  * Normalize one source entry into per-locale `PageRecord`s. This is the single
  * funnel every adapter's entries pass through, so route mapping, heading/link
@@ -376,27 +563,12 @@ export const normalizeEntry = (
   const { format } = entry.body;
   const ext = format === "mdx" ? ".mdx" : ".md";
 
-  const result = pageMetaSchema.safeParse(entry.data);
-  if (!result.success) {
-    // Source text lets the error carry a line/column into the frontmatter block:
-    // `entry.raw` for non-filesystem sources, else the file itself (read only on
-    // this rare error path, so filesystem entries stay cheap in the happy path).
-    const source =
-      entry.raw ??
-      (entry.sourcePath && existsSync(entry.sourcePath)
-        ? readFileSync(entry.sourcePath, "utf-8")
-        : undefined);
-    return {
-      diagnostics: diagnosticsFromZod(result.error, {
-        code: "BLUME_FRONTMATTER_INVALID",
-        file: entry.sourcePath ?? `${ctx.source.name}:${entry.ref}`,
-        source,
-      }),
-      pages: [],
-    };
+  const parsed = parseEntryMeta(entry, ctx);
+  if (parsed.diagnostics) {
+    return { diagnostics: parsed.diagnostics, pages: [] };
   }
 
-  const meta = result.data;
+  const { meta } = parsed;
 
   // Top-level `hidden`/`noindex` are accepted as shorthands for their nested
   // equivalents — the schema declares them, so silently ignoring them would
@@ -439,6 +611,7 @@ export const normalizeEntry = (
     componentsUsed:
       format === "mdx" ? extractComponentTags(entry.body.text) : undefined,
     contentType: meta.type ?? ctx.defaultType,
+    custom: parsed.custom,
     description: meta.description,
     editUrl: entry.editUrl,
     entryId: staged ? `${ctx.source.name}/${entry.ref}` : undefined,

package/src/core/sources/types.ts

@@ -1,4 +1,4 @@
-import type { ResolvedI18nConfig } from "../schema.ts";
+import type { FrontmatterExtend, ResolvedI18nConfig } from "../schema.ts";
 import type { Diagnostic } from "../types.ts";
 
 /**
@@ -109,5 +109,7 @@ export interface NormalizeContext {
   /** Site-wide route mount point (`""` or `/seg`), prepended to every route. */
   basePath?: string;
   defaultType: string;
+  /** Opt-in custom frontmatter keys (`frontmatter.extend`), schema per key. */
+  frontmatterExtend?: FrontmatterExtend;
   i18n?: ResolvedI18nConfig;
 }