blume 1.1.0 → 1.1.2

package/dist/types/ai/component-markdown.d.ts

@@ -14,6 +14,12 @@ export interface ComponentMarkdownContext extends EvaluatedProps {
     childComponents: (name: string) => ComponentMarkdownChild[];
     /** The element's body, downleveled and dedented (empty if self-closing). */
     children: string;
+    /**
+     * The page's parsed front-matter (empty when the caller has none). Lets a
+     * serializer read page metadata directly, even when a prop expression is
+     * not statically evaluable.
+     */
+    frontmatter: Record<string, unknown>;
 }
 /**
  * A component's Markdown serializer. Return the replacement Markdown, or
@@ -29,6 +35,11 @@ export type ComponentMarkdown = (context: ComponentMarkdownContext) => string |
  * `components` adds user serializers from `ai.markdownComponents`, layered
  * over the built-ins: a same-name entry replaces the built-in serializer, and
  * one that always returns `null` effectively opts that component out.
+ *
+ * `frontmatter` is the page's parsed front-matter data. It is put in scope
+ * when evaluating attribute expressions — so `prop={frontmatter.status}`
+ * resolves the way it does when Astro renders the page — and handed to
+ * serializers on their context.
  */
-export declare const downlevelComponents: (source: string, components?: Record<string, ComponentMarkdown>) => string;
+export declare const downlevelComponents: (source: string, components?: Record<string, ComponentMarkdown>, frontmatter?: Record<string, unknown>) => string;
 export {};

package/dist/types/core/config-input.d.ts

@@ -1,4 +1,5 @@
 import type { ComponentMarkdown } from "../ai/component-markdown.ts";
+import type { CodeTheme } from "../markdown/themes.ts";
 import type { FontSlug } from "../theme/fonts.ts";
 import type { OpenApiSource, SearchProvider, SidebarDisplay, SidebarItemConfig } from "./schema.ts";
 import type { ContentSource } from "./sources/types.ts";
@@ -487,9 +488,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).
@@ -654,6 +657,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. */
 export interface SeoConfig {
@@ -713,12 +723,12 @@ export interface MarkdownConfig {
      * `` `code`{:lang} ``, `<CodeBlock>`, and `<Diff>`.
      */
     codeBlocks?: {
-        /** Shiki theme names per color mode. */
+        /** Bundled Shiki theme names or inline custom Shiki themes per color mode. */
         theme?: {
-            /** Dark-mode theme. Defaults to `github-dark`. */
-            dark?: string;
-            /** Light-mode theme. Defaults to `github-light`. */
-            light?: string;
+            /** Dark-mode theme name or custom theme. Defaults to `github-dark`. */
+            dark?: CodeTheme;
+            /** Light-mode theme name or custom theme. Defaults to `github-light`. */
+            light?: CodeTheme;
         };
     };
     /**

package/dist/types/core/schema.d.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import type { ComponentMarkdown } from "../ai/component-markdown.ts";
+import type { CodeTheme } from "../markdown/themes.ts";
 import type { ContentSource } from "./sources/types.ts";
 import type { StandardSchema } from "./standard-schema.ts";
 declare const hydrationMode: z.ZodEnum<["load", "idle", "visible", "media", "only"]>;
@@ -1916,24 +1917,24 @@ export declare const blumeConfigSchema: z.ZodObject<{
         }>>;
         codeBlocks: z.ZodDefault<z.ZodObject<{
             theme: z.ZodDefault<z.ZodObject<{
-                dark: z.ZodDefault<z.ZodString>;
-                light: z.ZodDefault<z.ZodString>;
+                dark: z.ZodDefault<z.ZodType<CodeTheme, z.ZodTypeDef, CodeTheme>>;
+                light: z.ZodDefault<z.ZodType<CodeTheme, z.ZodTypeDef, CodeTheme>>;
             }, "strict", z.ZodTypeAny, {
-                dark: string;
-                light: string;
+                dark: CodeTheme;
+                light: CodeTheme;
             }, {
-                dark?: string | undefined;
-                light?: string | undefined;
+                dark?: CodeTheme | undefined;
+                light?: CodeTheme | undefined;
             }>>;
         }, "strict", z.ZodTypeAny, {
             theme: {
-                dark: string;
-                light: string;
+                dark: CodeTheme;
+                light: CodeTheme;
             };
         }, {
             theme?: {
-                dark?: string | undefined;
-                light?: string | undefined;
+                dark?: CodeTheme | undefined;
+                light?: CodeTheme | undefined;
             } | undefined;
         }>>;
         /**
@@ -1954,8 +1955,8 @@ export declare const blumeConfigSchema: z.ZodObject<{
         };
         codeBlocks: {
             theme: {
-                dark: string;
-                light: string;
+                dark: CodeTheme;
+                light: CodeTheme;
             };
         };
         headingAnchors: boolean;
@@ -1967,8 +1968,8 @@ export declare const blumeConfigSchema: z.ZodObject<{
         } | undefined;
         codeBlocks?: {
             theme?: {
-                dark?: string | undefined;
-                light?: string | undefined;
+                dark?: CodeTheme | undefined;
+                light?: CodeTheme | undefined;
             } | undefined;
         } | undefined;
         headingAnchors?: boolean | undefined;
@@ -2529,6 +2530,13 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 foreground?: string | undefined;
                 muted?: string | undefined;
             }>>;
+            /**
+             * 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.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         }, "strict", z.ZodTypeAny, {
             enabled?: boolean | undefined;
             logo?: string | undefined;
@@ -2544,6 +2552,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 foreground?: string | undefined;
                 muted?: string | undefined;
             } | undefined;
+            titles?: Record<string, string> | undefined;
         }, {
             enabled?: boolean | undefined;
             logo?: string | undefined;
@@ -2559,6 +2568,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 foreground?: string | undefined;
                 muted?: string | undefined;
             } | undefined;
+            titles?: Record<string, string> | undefined;
         }>>;
         /** Generate robots.txt (with a Sitemap reference when available). */
         robots: z.ZodDefault<z.ZodBoolean>;
@@ -2616,6 +2626,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 foreground?: string | undefined;
                 muted?: string | undefined;
             } | undefined;
+            titles?: Record<string, string> | undefined;
         };
         robots: boolean;
         rss: {
@@ -2651,6 +2662,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 foreground?: string | undefined;
                 muted?: string | undefined;
             } | undefined;
+            titles?: Record<string, string> | undefined;
         } | undefined;
         robots?: boolean | undefined;
         rss?: {
@@ -2803,6 +2815,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
     } | undefined>;
 }, "strict", z.ZodTypeAny, {
     title: string;
+    frontmatter: {
+        extend: Record<string, StandardSchema<unknown, unknown>>;
+    };
     openapi: {
         enabled: boolean;
         route: string;
@@ -2961,9 +2976,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
         pdf: boolean;
     };
     feedback: boolean;
-    frontmatter: {
-        extend: Record<string, StandardSchema<unknown, unknown>>;
-    };
     markdown: {
         code: {
             icons: boolean;
@@ -2971,8 +2983,8 @@ export declare const blumeConfigSchema: z.ZodObject<{
         };
         codeBlocks: {
             theme: {
-                dark: string;
-                light: string;
+                dark: CodeTheme;
+                light: CodeTheme;
             };
         };
         headingAnchors: boolean;
@@ -3074,6 +3086,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 foreground?: string | undefined;
                 muted?: string | undefined;
             } | undefined;
+            titles?: Record<string, string> | undefined;
         };
         robots: boolean;
         rss: {
@@ -3145,6 +3158,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
     } | undefined;
 }, {
     title?: string | undefined;
+    frontmatter?: {
+        extend?: Record<string, StandardSchema<unknown, unknown>> | undefined;
+    } | undefined;
     openapi?: {
         enabled?: boolean | undefined;
         route?: string | undefined;
@@ -3332,9 +3348,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
         pdf?: boolean | undefined;
     } | undefined;
     feedback?: boolean | undefined;
-    frontmatter?: {
-        extend?: Record<string, StandardSchema<unknown, unknown>> | undefined;
-    } | undefined;
     i18n?: {
         locales: {
             code: string;
@@ -3363,8 +3376,8 @@ export declare const blumeConfigSchema: z.ZodObject<{
         } | undefined;
         codeBlocks?: {
             theme?: {
-                dark?: string | undefined;
-                light?: string | undefined;
+                dark?: CodeTheme | undefined;
+                light?: CodeTheme | undefined;
             } | undefined;
         } | undefined;
         headingAnchors?: boolean | undefined;
@@ -3466,6 +3479,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 foreground?: string | undefined;
                 muted?: string | undefined;
             } | undefined;
+            titles?: Record<string, string> | undefined;
         } | undefined;
         robots?: boolean | undefined;
         rss?: {

package/dist/types/core/types.d.ts

@@ -103,6 +103,13 @@ export interface PageRecord {
      * `/guides/x`). Pages with the same key are translations of each other.
      */
     translationKey: string;
+    /**
+     * True for entries filled in from the fallback locale to pad a locale's
+     * navigation for pages it hasn't translated yet. The record's content —
+     * title included — belongs to the fallback locale, so per-locale content
+     * checks skip these.
+     */
+    fallback?: boolean;
     /**
      * Content-relative path with the leading locale directory stripped, used for
      * sidebar grouping so the locale dir is not surfaced as a nav group. Equals
@@ -206,6 +213,13 @@ export interface Navigation {
     tabs: NavTab[];
     selectors: NavSelector[];
     sidebar: NavNode[];
+    /**
+     * The tree root in final path space — localized and based (`/`, `/en`,
+     * `/docs`). Tab paths arrive in the same space, so the tab sitting at this
+     * path spans the whole tree and must be scoped as the root tab, not as a
+     * section tab. Absent on older serialized graphs; treat as `/`.
+     */
+    root?: string;
     /** Pinned links shown above the sidebar sections, unscoped by tab. */
     featured: FeaturedLink[];
     /** Repo URL for the header link, or null when hidden (`navigation.repo`). */

package/dist/types/markdown/themes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The light/dark Shiki themes Blume highlights code with. Every Shiki surface —
+ * fenced code (the generated Astro `shikiConfig.themes`), inline `` `code`{:lang} ``,
+ * out-of-pipeline `highlightCode`, and `<Diff>` — resolves to the same pair so a
+ * project's `markdown.codeBlocks.theme` shifts them all in lockstep. This is the
+ * single home for the github fallback used when nothing is configured.
+ */
+import type { ThemeRegistrationAny } from "shiki";
+/** A bundled Shiki theme name or an inline custom Shiki theme definition. */
+export type CodeTheme = string | ThemeRegistrationAny;
+/**
+ * A light/dark Shiki theme pair (`markdown.codeBlocks.theme`). A `type` (not an
+ * `interface`) so it keeps the implicit index signature Shiki's `themes`
+ * parameter (`Partial<Record<string, …>>`) expects.
+ */
+export type CodeThemes = {
+    dark: CodeTheme;
+    light: CodeTheme;
+};
+/** The default pair, used when `markdown.codeBlocks.theme` is unset. */
+export declare const DEFAULT_CODE_THEMES: CodeThemes;

package/docs/advanced/changelog.mdx

@@ -87,7 +87,7 @@ content: {
 }
 ```
 
-The release name becomes the title, its tag becomes `changelog.version`, and its published date sorts the timeline. A private repo authenticates with the `GITHUB_TOKEN` environment variable. See [Content sources](/docs/content/sources#github-releases) for every option.
+The release name becomes the title, its tag becomes `changelog.version`, and its published date sorts the timeline. Each release page also gets a unique meta description summarized from its notes — markdown stripped, section headings and changeset commit-hash prefixes dropped, trimmed to the search-snippet length [`blume audit`](/docs/reference/cli#auditing-the-built-site) checks for — instead of falling back to the site description. A private repo authenticates with the `GITHUB_TOKEN` environment variable. See [Content sources](/docs/content/sources#github-releases) for every option.
 
 ## The RSS feed
 

package/docs/configuration/ai.mdx

@@ -47,11 +47,11 @@ Append `.md` or `.mdx` to any page's URL to fetch its raw Markdown source — pe
 
 Nested routes work the same way (`/content/syntax.md`), and the home page is served at `/index.md`.
 
-The `.md` variant _downlevels_ components to plain Markdown for consumers that can't interpret JSX: `<TypeTable>` becomes a Markdown table, `<Callout>` a labeled blockquote, `<Steps>` an ordered list, `<Tabs>` bold-labeled sections, and `<YouTube>` a link. Anything that can't be converted faithfully — a custom component, or a prop computed from an import — is left as-is, and component markup inside fenced code blocks is never touched. The same conversion applies to `llms-full.txt` and the MCP server's `get_page` tool, so every agent-facing surface reads clean Markdown. When you want the untransformed source, use the `.mdx` variant.
+The `.md` variant _downlevels_ components to plain Markdown for consumers that can't interpret JSX: `<TypeTable>` becomes a Markdown table, `<Callout>` a labeled blockquote, `<Steps>` an ordered list, `<Tabs>` bold-labeled sections, and `<YouTube>` a link. Props are evaluated with the page's `frontmatter` in scope, so a prop like `title={frontmatter.status}` resolves to the same value the rendered page shows. Anything that can't be converted faithfully — a custom component, or a prop computed from an import — is left as-is, and component markup inside fenced code blocks is never touched. The same conversion applies to `llms-full.txt` and the MCP server's `get_page` tool, so every agent-facing surface reads clean Markdown. When you want the untransformed source, use the `.mdx` variant.
 
 ### Custom component serializers
 
-Give your own components a Markdown form with `ai.markdownComponents` — a map of JSX name to serializer. Each serializer receives the component's `props` (statically evaluated from the MDX attributes) and its `children` (already downleveled to Markdown), and returns the replacement — or `null` to leave the JSX as-is:
+Give your own components a Markdown form with `ai.markdownComponents` — a map of JSX name to serializer. Each serializer receives the component's `props` (statically evaluated from the MDX attributes, with the page's `frontmatter` in scope), its `children` (already downleveled to Markdown), and the page's `frontmatter` data, and returns the replacement — or `null` to leave the JSX as-is:
 
 ```ts blume.config.ts lineNumbers
 import { defineConfig } from "blume";

package/docs/configuration/index.mdx

@@ -55,7 +55,7 @@ export default defineConfig({
     },
     codeBlocks: {
       theme: {
-        light: "github-light", // any bundled Shiki theme
+        light: "github-light", // bundled name or custom Shiki theme object
         dark: "github-dark",
       },
     },

package/docs/configuration/seo.mdx

@@ -166,6 +166,22 @@ seo: {
 
 Each entry is a family name, or an object pinning its `weight` (a number, a list, or a variable range like `"100..900"`) and `style` (`"normal"`, `"italic"`, or both). The families are fetched from Google Fonts at build — so a build that uses them needs network access — and the renderer only pulls the glyph subsets each title actually uses. Fallback is per-glyph, so adding a family only affects glyphs the built-in font can't draw; Latin text renders exactly as before.
 
+### Custom page titles
+
+A custom [`.astro` page](/docs/advanced/custom-pages) has no frontmatter to read, so its generated card is titled by humanizing the last URL segment of its route — `/getting-started` becomes "Getting Started", but `/cli` becomes "Cli". Name those cards explicitly with `og.titles`, keyed by route (`"/"` addresses the home, whose card otherwise carries the site title):
+
+```ts blume.config.ts lineNumbers
+seo: {
+  og: {
+    titles: {
+      "/cli": "CLI",
+    },
+  },
+}
+```
+
+Entries only apply to custom pages — a content page's card always takes its headline from the page title, so retitle those in frontmatter instead.
+
 `seo.image` is frontmatter, so it only covers Markdown and MDX content. To give a custom [`.astro` page](/docs/advanced/custom-pages) its own social image — a marketing home or landing page, and the way to give the home page alone a bespoke share image — pass the `ogImage` prop to `PageLayout`.
 
 ## RSS feeds

package/docs/content/components.mdx

@@ -560,7 +560,7 @@ A card linking to a GitHub repository with its live star and fork counts. Counts
 
 `Component` renders an example file from your project's `examples/` directory as a live preview alongside its highlighted source, in tabs. Point it at a file with `path` — its location under `examples/`, without the extension (so `examples/counter.tsx` is `path="counter"`). React, Vue, Svelte, and Astro examples are all supported; framework examples hydrate, Astro ones render statically. It keeps the preview and the code in sync from a single file.
 
-The preview renders in an isolated frame that the docs styles never reach — no prose margins, typography, or theme chrome bleed into your component. The frame gets Tailwind (preflight + utilities scanned from your example files and anything they import), Blume's design tokens so classes like `bg-background` follow the site palette by default, and it follows the site's light/dark toggle live.
+The preview renders in an isolated frame that the docs styles never reach — no prose margins, typography, or theme chrome bleed into your component. The frame gets Tailwind (preflight + utilities scanned from your example files and anything they import), Blume's design tokens so classes like `bg-background` follow the site palette by default, and it follows the site's light/dark toggle live. The pane sizes itself to the rendered example — and keeps tracking it if the example grows or shrinks after load — with the Preview and Code tabs sharing one height so toggling them never shifts the page.
 
 To style previews with your own design system — say, shadcn variables — point `examples.css` at a stylesheet. It's injected into every preview frame after Blume's defaults, so your tokens win. Don't `@import "tailwindcss"` in it; the frame already provides Tailwind. Both `.dark` and `[data-theme="dark"]` work for dark-mode overrides:
 

package/docs/content/navigation.mdx

@@ -45,6 +45,8 @@ export default defineMeta({
 
 See [Folder meta](/docs/content/meta) for every field and computing meta at scan time.
 
+A folder's `meta.title` and its own `index` page's frontmatter `title` are resolved independently — translating one under i18n and forgetting the other renders a correct sidebar with a stale `<title>`/heading on the landing page itself. Blume reports a `BLUME_NAV_INDEX_TITLE_MISMATCH` warning when they diverge. Untranslated pages filled in from the fallback locale are exempt — their title belongs to the fallback locale, and the fix is translating the page, not editing its frontmatter.
+
 To group pages _without_ adding a URL segment, use a parenthesized folder name — see [Pages](/docs/content#group-folders).
 
 ## Display modes
@@ -86,6 +88,8 @@ When the sidebar is generated, order is resolved highest priority first:
   </Step>
 </Steps>
 
+Two siblings that land on the same explicit or numeric order fall back to alphabetical order between themselves — Blume reports a `BLUME_DUPLICATE_SIDEBAR_ORDER` warning so the tie doesn't go unnoticed.
+
 ## Hidden pages
 
 Hide a page from the sidebar — and from previous/next pagination — while keeping it built and reachable by its URL:

package/docs/content/syntax.mdx

@@ -154,6 +154,20 @@ export default defineConfig({
 });
 ```
 
+You can also provide a custom [Shiki theme definition](https://shiki.style/guide/load-theme) directly. Import a VS Code-compatible theme JSON file (using an import attribute when your runtime requires one) and assign it to either color mode; bundled names and custom definitions can be mixed:
+
+```ts blume.config.ts
+import darkTheme from "./themes/acme-dark.json" with { type: "json" };
+
+export default defineConfig({
+  markdown: {
+    codeBlocks: {
+      theme: { light: "github-light", dark: darkTheme },
+    },
+  },
+});
+```
+
 ### Line numbers
 
 Append `lineNumbers` to render a line-number gutter — on its own or alongside a title:

package/docs/reference/cli.mdx

@@ -35,7 +35,7 @@ blume <command> [options]
 - `blume dev --content-dir <dir>` — scan a different content folder without editing `blume.config.ts`.
 - `blume dev --debug` — verbose Astro/Vite logging for troubleshooting.
 - `blume dev --preview` / `blume build --preview` — include drafts and unpublished CMS content.
-- `blume build --strict` — fail the build on diagnostic errors (also works on `blume dev`).
+- `blume build --no-strict` — build despite diagnostic errors. By default `blume build` fails (exit 1) on any error diagnostic, because pages that fail frontmatter validation are dropped from the output; with `--no-strict` the build succeeds and reports how many pages are missing. `blume dev --strict` opts dev into the same fail-fast behavior.
 - `blume build --output static|server --adapter vercel|node|netlify|cloudflare --base /docs` — override the deployment output, adapter, and base path from `blume.config.ts`.
 - `blume build --analyze` — print the client JavaScript bundle sizes (largest first) after the build.
 - `blume build --budget-js <kb> --budget-css <kb>` — fail the build when total client JavaScript/CSS exceeds the budget, turning a performance target into a CI gate.

package/docs/reference/frontmatter.mdx

@@ -109,4 +109,6 @@ reviewedAt: 2026-06-20
 
 Schemas are accepted through the [Standard Schema](https://standardschema.dev) interface, so Zod (whichever version your project installs), Valibot, and ArkType all work. 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 where present. All other keys stay strictly validated, and built-in fields can't be redeclared.
 
+A page that fails validation fails `blume build` with a diagnostic naming the file and key. With [`--no-strict`](/docs/reference/cli#common-flags), the build succeeds anyway and the failing pages are dropped from the output — the build summary reports how many.
+
 Schemas are exported from `blume/schema` for editor and migration tooling.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -112,6 +112,7 @@
     "tailwindcss": "^4",
     "takumi-js": "^2.2.1",
     "tinyglobby": "^0.2.10",
+    "twoslash": "^0.3.9",
     "typescript": "^6.0.3",
     "undici": "^8.6.0",
     "zod": "^3.24.0"

package/src/ai/component-markdown.ts

@@ -63,6 +63,12 @@ export interface ComponentMarkdownContext extends EvaluatedProps {
   childComponents: (name: string) => ComponentMarkdownChild[];
   /** The element's body, downleveled and dedented (empty if self-closing). */
   children: string;
+  /**
+   * The page's parsed front-matter (empty when the caller has none). Lets a
+   * serializer read page metadata directly, even when a prop expression is
+   * not statically evaluable.
+   */
+  frontmatter: Record<string, unknown>;
 }
 
 /**
@@ -78,15 +84,22 @@ export type ComponentMarkdown = (
  * Statically evaluate an MDX attribute expression (`prop={...}`). Component
  * data props are object/array/number literals in practice; evaluation runs at
  * build time over the author's own content — the same trust level as the MDX
- * itself, which Astro compiles and executes. Expressions that reference
- * imports or scope throw and report as not evaluable.
+ * itself, which Astro compiles and executes. The page's `frontmatter` is in
+ * scope, mirroring what Astro provides an MDX body at render time, so
+ * `prop={frontmatter.status}` resolves; expressions that reference imports or
+ * other scope throw and report as not evaluable.
  */
-const evaluateExpression = (raw: string): { ok: boolean; value: unknown } => {
+const evaluateExpression = (
+  raw: string,
+  frontmatter: Record<string, unknown> | undefined
+): { ok: boolean; value: unknown } => {
   try {
     // Build-time eval of the author's own attribute literals; a throw falls
     // back to leaving the JSX verbatim.
     // oxlint-disable-next-line no-new-func
-    const value = new Function(`"use strict"; return (${raw});`)();
+    const value = new Function("frontmatter", `"use strict"; return (${raw});`)(
+      frontmatter
+    );
     return { ok: true, value };
   } catch {
     return { ok: false, value: undefined };
@@ -94,7 +107,10 @@ const evaluateExpression = (raw: string): { ok: boolean; value: unknown } => {
 };
 
 /** Evaluate an element's attributes into a plain props object. */
-const readProps = (node: MdastNode): EvaluatedProps => {
+const readProps = (
+  node: MdastNode,
+  frontmatter: Record<string, unknown> | undefined
+): EvaluatedProps => {
   const props: Record<string, unknown> = {};
   let lossy = false;
   for (const attribute of node.attributes ?? []) {
@@ -109,7 +125,7 @@ const readProps = (node: MdastNode): EvaluatedProps => {
     } else if (typeof attribute.value === "string") {
       props[attribute.name] = attribute.value;
     } else {
-      const result = evaluateExpression(attribute.value.value);
+      const result = evaluateExpression(attribute.value.value, frontmatter);
       if (result.ok) {
         props[attribute.name] = result.value;
       } else {
@@ -347,8 +363,9 @@ const componentHint = (registry: Record<string, ComponentMarkdown>): RegExp =>
 
 const BUILT_IN_HINT = componentHint(SERIALIZERS);
 
-/** One downlevel pass's inputs: the full source and the active registry. */
+/** One downlevel pass's inputs: the source, registry, and page metadata. */
 interface Walk {
+  frontmatter: Record<string, unknown> | undefined;
   registry: Record<string, ComponentMarkdown>;
   source: string;
 }
@@ -388,15 +405,16 @@ const serializeElement = (
   node: MdastNode
 ): string | null =>
   serializer({
-    ...readProps(node),
+    ...readProps(node, walk.frontmatter),
     childComponents: (name) =>
       (node.children ?? [])
         .filter((child) => isJsxElement(child) && child.name === name)
         .map((child) => ({
-          ...readProps(child),
+          ...readProps(child, walk.frontmatter),
           children: renderChildren(walk, child),
         })),
     children: renderChildren(walk, node),
+    frontmatter: walk.frontmatter ?? {},
   });
 
 /**
@@ -438,10 +456,16 @@ const collectSplices = (
  * `components` adds user serializers from `ai.markdownComponents`, layered
  * over the built-ins: a same-name entry replaces the built-in serializer, and
  * one that always returns `null` effectively opts that component out.
+ *
+ * `frontmatter` is the page's parsed front-matter data. It is put in scope
+ * when evaluating attribute expressions — so `prop={frontmatter.status}`
+ * resolves the way it does when Astro renders the page — and handed to
+ * serializers on their context.
  */
 export const downlevelComponents = (
   source: string,
-  components?: Record<string, ComponentMarkdown>
+  components?: Record<string, ComponentMarkdown>,
+  frontmatter?: Record<string, unknown>
 ): string => {
   const custom = components && Object.keys(components).length > 0;
   const registry = custom ? { ...SERIALIZERS, ...components } : SERIALIZERS;
@@ -456,6 +480,10 @@ export const downlevelComponents = (
     return source;
   }
   const splices: Splice[] = [];
-  collectSplices({ registry, source }, tree.children ?? [], splices);
+  collectSplices(
+    { frontmatter, registry, source },
+    tree.children ?? [],
+    splices
+  );
   return splices.length > 0 ? applySplices(source, splices) : source;
 };

package/src/ai/llms.ts

@@ -170,9 +170,11 @@ const buildFull = async (project: BlumeProject): Promise<string> => {
       // Resolve `<Visibility>` audiences (web-only content omitted from the
       // agent-facing output, agents-only unwrapped), then downlevel supported
       // components to plain Markdown.
+      const parsed = matter(raw);
       const body = downlevelComponents(
-        applyAgentVisibility(matter(raw).content),
-        config.ai.markdownComponents
+        applyAgentVisibility(parsed.content),
+        config.ai.markdownComponents,
+        parsed.data
       ).trim();
       const url = pageUrl(
         page.route,

package/src/ai/markdown.ts

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 
+import matter from "../core/frontmatter.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { readEntryText } from "../core/sources/read.ts";
 import type { RouteManifestEntry } from "../core/types.ts";
@@ -47,9 +48,12 @@ export const buildRawMarkdown = async (
   const entries = await Promise.all(
     project.manifest.routes.map(async (route) => {
       const source = applyAgentVisibility(await readRoute(route));
+      // The `.md` variant keeps the front-matter block in the output, but its
+      // data must also be in scope for `prop={frontmatter.*}` expressions.
       const md = downlevelComponents(
         source,
-        project.config.ai.markdownComponents
+        project.config.ai.markdownComponents,
+        matter(source).data
       );
       const entry: RawMarkdownEntry =
         md === source ? { mdx: source } : { md, mdx: source };