blume 1.0.4 → 1.1.1

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,25 +237,11 @@ export const scanProject = async (
     discoverFolderMeta(metaSources, { localeDirs }),
   ]);
 
-  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,
-        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 =
@@ -259,6 +292,7 @@ export const scanProject = async (
       ...graph.diagnostics,
       ...i18nWarnings,
     ],
+    droppedPages,
     graph,
     manifest,
     mode,

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,10 +860,23 @@ 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. */
   palette: ogPaletteSchema.optional(),
+  /**
+   * 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: z.record(z.string(), z.string()).optional(),
 });
 
 const rssConfigSchema = z.strictObject({
@@ -1041,6 +1092,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 +1187,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 +1207,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/github-releases.ts

@@ -56,6 +56,63 @@ const LEADING_V = /^v/iu;
 const NON_SLUG = /[^a-z0-9]+/gu;
 const EDGE_DASHES = /^-+|-+$/gu;
 
+// `blume audit` grades meta descriptions against the 110–160 character search
+// snippet range (audit/types.ts thresholds), so the derived summary aims for
+// the longest word-boundary cut under the cap.
+const DESCRIPTION_MAX = 160;
+const DESCRIPTION_MIN = 110;
+
+const CODE_FENCE = /```[\s\S]*?```/gu;
+const HEADING_LINE = /^#{1,6}\s.*$/gmu;
+const LIST_MARK = /^\s*(?:[-*+]|\d+[.)])\s+/u;
+// Changesets-generated release bullets open with the changeset's short commit
+// hash (`- cf8fa22: Fix …`) — noise in a search snippet.
+const CHANGESET_HASH = /^[0-9a-f]{7,40}:\s+/u;
+const IMAGE = /!\[[^\]]*\]\([^)]*\)/gu;
+const LINK = /\[(?<text>[^\]]*)\]\([^)]*\)/gu;
+const INLINE_CODE = /`(?<code>[^`]+)`/gu;
+// Tag-shaped only: a bare `<` in prose must not swallow text up to a later `>`.
+const HTML_OR_JSX = /<\/?[a-zA-Z][^\n<>]*>|<\/?>/gu;
+const MARKDOWN_PUNCT = /[*_~>]+/gu;
+const WHITESPACE = /\s+/gu;
+const TRAILING_FRAGMENT = /[\s,;:.—–-]+$/u;
+
+/**
+ * Derive a meta description from release notes: markdown reduced to plain
+ * text — section headings ("### Patch Changes") and changesets' commit-hash
+ * bullet prefixes dropped — then cut at a word boundary to fit the search
+ * snippet cap. Undefined when the notes have no prose at all.
+ */
+const releaseDescription = (body: string): string | undefined => {
+  const text = body
+    .replaceAll(CODE_FENCE, " ")
+    .replaceAll(HEADING_LINE, "")
+    .split("\n")
+    .map((line) => line.replace(LIST_MARK, "").replace(CHANGESET_HASH, ""))
+    .join("\n")
+    .replaceAll(IMAGE, " ")
+    .replaceAll(LINK, "$<text>")
+    .replaceAll(INLINE_CODE, "$<code>")
+    .replaceAll(HTML_OR_JSX, " ")
+    .replaceAll(MARKDOWN_PUNCT, " ")
+    .replaceAll(WHITESPACE, " ")
+    .trim();
+  if (!text) {
+    return undefined;
+  }
+  if (text.length <= DESCRIPTION_MAX) {
+    return text;
+  }
+  // Cut before the cap at a word boundary (kept only when it doesn't drop the
+  // summary under the minimum), shed any dangling punctuation, and mark the cut.
+  const slice = text.slice(0, DESCRIPTION_MAX - 1);
+  const boundary = slice.lastIndexOf(" ");
+  const head = (
+    boundary >= DESCRIPTION_MIN ? slice.slice(0, boundary) : slice
+  ).replace(TRAILING_FRAGMENT, "");
+  return `${head}…`;
+};
+
 /** Slugify a tag into a stable, URL-safe source ref (`v1.2.0` -> `v1-2-0`). */
 const slugifyTag = (tag: string): string =>
   tag.toLowerCase().replaceAll(NON_SLUG, "-").replaceAll(EDGE_DASHES, "");
@@ -71,9 +128,10 @@ const githubHeaders = (): Headers => {
 };
 
 /**
- * Lower one release to a staged Markdown entry: the notes become the body and
+ * Lower one release to a staged Markdown entry: the notes become the body,
  * `type: changelog` frontmatter (title/date/version/category) drives the
- * generated `/changelog` timeline and RSS feed.
+ * generated `/changelog` timeline and RSS feed, and a summary derived from the
+ * notes becomes the release page's meta description.
  */
 const releaseToEntry = (release: GithubRelease): SourceEntry => {
   const version = release.tag_name.replace(LEADING_V, "");
@@ -81,9 +139,14 @@ const releaseToEntry = (release: GithubRelease): SourceEntry => {
   const date = release.published_at ?? release.created_at;
   const category = release.prerelease ? "Prerelease" : "Release";
   const body = (release.body ?? "").replaceAll("\r\n", "\n").trim();
+  // A summary in `seo.description` gives each release page a unique meta
+  // description (instead of the site-wide fallback) without also rendering the
+  // visible lede paragraph a top-level `description` would add.
+  const description = releaseDescription(body);
   const data = {
     changelog: { category, version },
     date,
+    ...(description ? { seo: { description } } : {}),
     title,
     type: "changelog",
   };

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;
 }