blume 0.4.0 → 0.5.1

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

@@ -87,6 +87,8 @@ export interface BlumeDataConfig {
     favicon: BlumeFavicon;
     feedback: boolean;
     i18n: BlumeDataI18n | null;
+    /** Default icon library for bare `icon` names. */
+    icons: ResolvedConfig["icons"];
     /** `markdown.imageZoom`: click-to-zoom content images. */
     imageZoom: boolean;
     logo: BlumeLogo | null;

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

@@ -2,8 +2,18 @@ import type { ResolvedConfig } from "./schema.ts";
 import type { ProjectContext } from "./types.ts";
 /** Locate the Blume config file for a project root, if any. */
 export declare const findConfigFile: (root: string) => string | null;
+/**
+ * Resolve the generated runtime directory for a project. Defaults to
+ * `<root>/.blume`; an override (e.g. `.blume-verify` for an isolated build that
+ * runs alongside a live `blume dev`) may be relative to the root or absolute.
+ */
+export declare const resolveRuntimeDir: (root: string, runtimeDir?: string) => string;
 /**
  * Resolve every path Blume needs from a project root and its resolved config.
- * Paths are absolute and normalized.
+ * Paths are absolute and normalized. `options.runtimeDir` relocates the whole
+ * generated runtime (and its build output) so a verify build/check can run
+ * without touching a live dev server's `.blume/` or the real `dist/`.
  */
-export declare const resolveProjectContext: (root: string, config: ResolvedConfig) => ProjectContext;
+export declare const resolveProjectContext: (root: string, config: ResolvedConfig, options?: {
+    runtimeDir?: string;
+}) => ProjectContext;

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

@@ -4,6 +4,38 @@ declare const hydrationMode: z.ZodEnum<["load", "idle", "visible", "media", "onl
 export type HydrationMode = z.infer<typeof hydrationMode>;
 /** Frontmatter accepted on any content page. */
 declare const pageMetaBaseSchema: z.ZodObject<{
+    /** Post author(s) for blog/changelog content; preserved, not yet rendered. */
+    authors: z.ZodOptional<z.ZodUnion<[z.ZodUnion<[z.ZodString, z.ZodObject<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>]>, z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>]>, "many">]>>;
     changelog: z.ZodOptional<z.ZodObject<{
         category: z.ZodOptional<z.ZodString>;
         date: z.ZodOptional<z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodDate]>, string, string | Date>>;
@@ -58,14 +90,14 @@ declare const pageMetaBaseSchema: z.ZodObject<{
         noindex: boolean;
         title?: string | undefined;
         description?: string | undefined;
-        canonical?: string | undefined;
         image?: string | undefined;
+        canonical?: string | undefined;
     }, {
         title?: string | undefined;
         description?: string | undefined;
+        image?: string | undefined;
         noindex?: boolean | undefined;
         canonical?: string | undefined;
-        image?: string | undefined;
     }>>;
     sidebar: z.ZodDefault<z.ZodObject<{
         badge: z.ZodOptional<z.ZodString>;
@@ -107,8 +139,8 @@ declare const pageMetaBaseSchema: z.ZodObject<{
         noindex: boolean;
         title?: string | undefined;
         description?: string | undefined;
-        canonical?: string | undefined;
         image?: string | undefined;
+        canonical?: string | undefined;
     };
     sidebar: {
         hidden: boolean;
@@ -120,6 +152,17 @@ declare const pageMetaBaseSchema: z.ZodObject<{
     date?: string | undefined;
     title?: string | undefined;
     description?: string | undefined;
+    authors?: string | z.objectOutputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough"> | (string | z.objectOutputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">)[] | undefined;
     changelog?: {
         date?: string | undefined;
         category?: string | undefined;
@@ -147,6 +190,17 @@ declare const pageMetaBaseSchema: z.ZodObject<{
         tags?: string[] | undefined;
     } | undefined;
     description?: string | undefined;
+    authors?: string | z.objectInputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough"> | (string | z.objectInputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">)[] | undefined;
     changelog?: {
         date?: string | Date | undefined;
         category?: string | undefined;
@@ -169,9 +223,9 @@ declare const pageMetaBaseSchema: z.ZodObject<{
     seo?: {
         title?: string | undefined;
         description?: string | undefined;
+        image?: string | undefined;
         noindex?: boolean | undefined;
         canonical?: string | undefined;
-        image?: string | undefined;
     } | undefined;
     sidebar?: {
         label?: string | undefined;
@@ -185,6 +239,38 @@ declare const pageMetaBaseSchema: z.ZodObject<{
     tag?: string | undefined;
 }>;
 export declare const pageMetaSchema: z.ZodObject<{
+    /** Post author(s) for blog/changelog content; preserved, not yet rendered. */
+    authors: z.ZodOptional<z.ZodUnion<[z.ZodUnion<[z.ZodString, z.ZodObject<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>]>, z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>]>, "many">]>>;
     changelog: z.ZodOptional<z.ZodObject<{
         category: z.ZodOptional<z.ZodString>;
         date: z.ZodOptional<z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodDate]>, string, string | Date>>;
@@ -239,14 +325,14 @@ export declare const pageMetaSchema: z.ZodObject<{
         noindex: boolean;
         title?: string | undefined;
         description?: string | undefined;
-        canonical?: string | undefined;
         image?: string | undefined;
+        canonical?: string | undefined;
     }, {
         title?: string | undefined;
         description?: string | undefined;
+        image?: string | undefined;
         noindex?: boolean | undefined;
         canonical?: string | undefined;
-        image?: string | undefined;
     }>>;
     sidebar: z.ZodDefault<z.ZodObject<{
         badge: z.ZodOptional<z.ZodString>;
@@ -288,8 +374,8 @@ export declare const pageMetaSchema: z.ZodObject<{
         noindex: boolean;
         title?: string | undefined;
         description?: string | undefined;
-        canonical?: string | undefined;
         image?: string | undefined;
+        canonical?: string | undefined;
     };
     sidebar: {
         hidden: boolean;
@@ -301,6 +387,17 @@ export declare const pageMetaSchema: z.ZodObject<{
     date?: string | undefined;
     title?: string | undefined;
     description?: string | undefined;
+    authors?: string | z.objectOutputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough"> | (string | z.objectOutputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">)[] | undefined;
     changelog?: {
         date?: string | undefined;
         category?: string | undefined;
@@ -328,6 +425,17 @@ export declare const pageMetaSchema: z.ZodObject<{
         tags?: string[] | undefined;
     } | undefined;
     description?: string | undefined;
+    authors?: string | z.objectInputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough"> | (string | z.objectInputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">)[] | undefined;
     changelog?: {
         date?: string | Date | undefined;
         category?: string | undefined;
@@ -350,9 +458,9 @@ export declare const pageMetaSchema: z.ZodObject<{
     seo?: {
         title?: string | undefined;
         description?: string | undefined;
+        image?: string | undefined;
         noindex?: boolean | undefined;
         canonical?: string | undefined;
-        image?: string | undefined;
     } | undefined;
     sidebar?: {
         label?: string | undefined;
@@ -827,8 +935,8 @@ declare const i18nConfigSchema: z.ZodEffects<z.ZodObject<{
     ui?: Record<string, Record<string, Record<string, string>>> | undefined;
 }>;
 /**
- * A single spec rendered by the API reference (Scalar). `spec` is a local path
- * or an `http(s)` URL; Scalar auto-detects OpenAPI vs AsyncAPI documents.
+ * A single spec rendered by the API reference. `spec` is a local path or an
+ * `http(s)` URL (OpenAPI for the Blume renderer; OpenAPI or AsyncAPI for Scalar).
  */
 declare const openapiSourceSchema: z.ZodObject<{
     /** Nav/section label for this source. */
@@ -1643,6 +1751,13 @@ export declare const blumeConfigSchema: z.ZodObject<{
         parser?: "dir" | "dot" | undefined;
         ui?: Record<string, Record<string, Record<string, string>>> | undefined;
     }>>;
+    icons: z.ZodDefault<z.ZodObject<{
+        library: z.ZodDefault<z.ZodEnum<["lucide", "fontawesome", "tabler"]>>;
+    }, "strict", z.ZodTypeAny, {
+        library: "lucide" | "fontawesome" | "tabler";
+    }, {
+        library?: "lucide" | "fontawesome" | "tabler" | undefined;
+    }>>;
     lastModified: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodObject<{
         type: z.ZodDefault<z.ZodEnum<["git", "frontmatter"]>>;
     }, "strict", z.ZodTypeAny, {
@@ -1773,13 +1888,13 @@ export declare const blumeConfigSchema: z.ZodObject<{
     }, "strict", z.ZodTypeAny, {
         enabled: boolean;
         route: string;
-        instructions?: string | undefined;
         name?: string | undefined;
+        instructions?: string | undefined;
     }, {
+        name?: string | undefined;
         enabled?: boolean | undefined;
         route?: string | undefined;
         instructions?: string | undefined;
-        name?: string | undefined;
     }>>;
     navigation: z.ZodDefault<z.ZodObject<{
         chromeVariants: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -1926,16 +2041,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
         }>, "many">>;
         /** Explicit sidebar override; when omitted the sidebar is generated. */
         sidebar: z.ZodOptional<z.ZodArray<z.ZodType<SidebarItemConfig, z.ZodTypeDef, SidebarItemConfig>, "many">>;
-        sidebarVariants: z.ZodDefault<z.ZodArray<z.ZodObject<{
-            items: z.ZodDefault<z.ZodArray<z.ZodType<SidebarItemConfig, z.ZodTypeDef, SidebarItemConfig>, "many">>;
-            path: z.ZodString;
-        }, "strict", z.ZodTypeAny, {
-            path: string;
-            items: SidebarItemConfig[];
-        }, {
-            path: string;
-            items?: SidebarItemConfig[] | undefined;
-        }>, "many">>;
         tabs: z.ZodOptional<z.ZodArray<z.ZodObject<{
             icon: z.ZodOptional<z.ZodString>;
             items: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -2012,10 +2117,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
             }[];
             kind: "version" | "dropdown" | "language" | "product";
         }[];
-        sidebarVariants: {
-            path: string;
-            items: SidebarItemConfig[];
-        }[];
         sidebar?: SidebarItemConfig[] | undefined;
         tabs?: {
             path: string;
@@ -2060,10 +2161,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 tag?: string | undefined;
             }[] | undefined;
         }[] | undefined;
-        sidebarVariants?: {
-            path: string;
-            items?: SidebarItemConfig[] | undefined;
-        }[] | undefined;
         tabs?: {
             path: string;
             label: string;
@@ -2078,7 +2175,13 @@ export declare const blumeConfigSchema: z.ZodObject<{
         }[] | undefined;
     }>>;
     openapi: z.ZodDefault<z.ZodObject<{
+        /** Code-sample languages shown per operation (Blume renderer). */
+        codeSamples: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         enabled: z.ZodDefault<z.ZodBoolean>;
+        /** Start nested schema rows expanded rather than collapsed (Blume renderer). */
+        expandSchemas: z.ZodDefault<z.ZodBoolean>;
+        /** Who renders the reference: Blume's own UI, or the embedded Scalar SPA. */
+        renderer: z.ZodDefault<z.ZodEnum<["blume", "scalar"]>>;
         /** Where the reference mounts. */
         route: z.ZodDefault<z.ZodString>;
         /** One or more specs; each renders on its own route by default. */
@@ -2100,7 +2203,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
         }>, "many">>;
         /** Shorthand for a single source: `sources: [{ spec }]`. */
         spec: z.ZodOptional<z.ZodString>;
-        /** Scalar theme name; defaults to a Blume-derived accent override. */
+        /** Scalar theme name (Scalar renderer only). */
         theme: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
         enabled: boolean;
@@ -2110,6 +2213,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
             label?: string | undefined;
             route?: string | undefined;
         }[];
+        codeSamples: string[];
+        expandSchemas: boolean;
+        renderer: "blume" | "scalar";
         spec?: string | undefined;
         theme?: string | undefined;
     }, {
@@ -2122,6 +2228,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
             route?: string | undefined;
         }[] | undefined;
         theme?: string | undefined;
+        codeSamples?: string[] | undefined;
+        expandSchemas?: boolean | undefined;
+        renderer?: "blume" | "scalar" | undefined;
     }>>;
     redirects: z.ZodDefault<z.ZodArray<z.ZodObject<{
         from: z.ZodString;
@@ -2629,6 +2738,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
         epub: boolean;
         pdf: boolean;
     };
+    icons: {
+        library: "lucide" | "fontawesome" | "tabler";
+    };
     markdown: {
         code: {
             icons: boolean;
@@ -2648,8 +2760,8 @@ export declare const blumeConfigSchema: z.ZodObject<{
     mcp: {
         enabled: boolean;
         route: string;
-        instructions?: string | undefined;
         name?: string | undefined;
+        instructions?: string | undefined;
     };
     navigation: {
         repo: boolean;
@@ -2681,10 +2793,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
             }[];
             kind: "version" | "dropdown" | "language" | "product";
         }[];
-        sidebarVariants: {
-            path: string;
-            items: SidebarItemConfig[];
-        }[];
         sidebar?: SidebarItemConfig[] | undefined;
         tabs?: {
             path: string;
@@ -2707,6 +2815,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
             label?: string | undefined;
             route?: string | undefined;
         }[];
+        codeSamples: string[];
+        expandSchemas: boolean;
+        renderer: "blume" | "scalar";
         spec?: string | undefined;
         theme?: string | undefined;
     };
@@ -3000,6 +3111,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
         parser?: "dir" | "dot" | undefined;
         ui?: Record<string, Record<string, Record<string, string>>> | undefined;
     } | undefined;
+    icons?: {
+        library?: "lucide" | "fontawesome" | "tabler" | undefined;
+    } | undefined;
     logo?: string | {
         dark?: string | undefined;
         light?: string | undefined;
@@ -3023,10 +3137,10 @@ export declare const blumeConfigSchema: z.ZodObject<{
         math?: boolean | undefined;
     } | undefined;
     mcp?: {
+        name?: string | undefined;
         enabled?: boolean | undefined;
         route?: string | undefined;
         instructions?: string | undefined;
-        name?: string | undefined;
     } | undefined;
     navigation?: {
         sidebar?: SidebarItemConfig[] | undefined;
@@ -3059,10 +3173,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 tag?: string | undefined;
             }[] | undefined;
         }[] | undefined;
-        sidebarVariants?: {
-            path: string;
-            items?: SidebarItemConfig[] | undefined;
-        }[] | undefined;
         tabs?: {
             path: string;
             label: string;
@@ -3086,6 +3196,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
             route?: string | undefined;
         }[] | undefined;
         theme?: string | undefined;
+        codeSamples?: string[] | undefined;
+        expandSchemas?: boolean | undefined;
+        renderer?: "blume" | "scalar" | undefined;
     } | undefined;
     redirects?: {
         from: string;

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

@@ -44,6 +44,13 @@ export interface ProjectContext {
     pagesRoot: string | null;
     /** Absolute path to the generated runtime (`<root>/.blume`). */
     outDir: string;
+    /**
+     * Absolute path to the Astro build output. `<root>/dist` normally; for a
+     * relocated runtime (isolated verify build) it lives under the runtime dir so
+     * it never empties the real `dist/`. Optional so hand-built test contexts and
+     * older callers still typecheck; `resolveProjectContext` always sets it.
+     */
+    distDir?: string;
     /** Absolute path to the user `theme.css`, if present. */
     themeFile: string | null;
     /** Absolute path to the user `components.ts`/`.tsx`, if present. */
@@ -161,11 +168,6 @@ export interface NavSelector {
     kind: "dropdown" | "language" | "product" | "version";
     items: NavSelectorItem[];
 }
-/** Sidebar tree used when the current route belongs to a nav partition. */
-export interface NavSidebarVariant {
-    path: string;
-    sidebar: NavNode[];
-}
 /** Chrome overrides used when the current route belongs to a nav partition. */
 export interface NavChromeVariant {
     path: string;
@@ -177,7 +179,6 @@ export interface Navigation {
     selectors: NavSelector[];
     chromeVariants: NavChromeVariant[];
     sidebar: NavNode[];
-    sidebarVariants: NavSidebarVariant[];
     /** Repo URL for the header link, or null when hidden (`navigation.repo`). */
     repoUrl?: string | null;
 }

package/dist/types/migrate/mintlify/config.d.ts

@@ -1,2 +1,16 @@
 import type { BlumeConfig } from "../../core/schema.ts";
+type JsonObject = Record<string, unknown>;
+export interface MintlifyRedirectPartition {
+    /** Static redirects Blume can honor, translated to Blume's `from`/`to` shape. */
+    kept: NonNullable<BlumeConfig["redirects"]>;
+    /** Source paths of dynamic redirects dropped because Blume can't model them. */
+    dropped: string[];
+}
+/**
+ * Split a spec's redirects into the static ones Blume emits and the dynamic
+ * (wildcard/param) ones it drops. Keeping a dynamic redirect crashes the Astro
+ * build, so the migrator surfaces the dropped sources as a warning instead.
+ */
+export declare const partitionMintlifyRedirects: (spec: JsonObject) => MintlifyRedirectPartition;
 export declare const loadMintlifyConfig: (root: string, file: string) => Promise<BlumeConfig>;
+export {};

package/docs/01-quickstart.mdx

@@ -51,7 +51,9 @@ Go from an empty folder to a running docs site in a few commands. Blume needs **
   </Step>
 </Steps>
 
-:::tip Blume works with any package manager and never requires you to set up Astro or Tailwind yourself. :::
+:::tip
+Blume works with any package manager and never requires you to set up Astro or Tailwind yourself.
+:::
 
 ## Write your first page
 
@@ -65,7 +67,9 @@ description: Welcome to my docs.
 
 Welcome! Use **Markdown** and built-in components — no imports required:
 
-:::note Blume ships callouts, cards, tabs, steps, and more. :::
+:::note
+Blume ships callouts, cards, tabs, steps, and more.
+:::
 ```
 
 Save it, and the dev server reloads instantly. Navigation, search, and page metadata are inferred from your files as you add them — keep writing, and the site keeps up.

package/docs/02-deployment.mdx

@@ -86,7 +86,9 @@ On **Vercel**, **Netlify**, and **Cloudflare Pages**, Blume picks the matching a
 
 A server build includes everything a static build does, plus any Astro endpoints or middleware you add. The `node` adapter produces a standalone server you can run directly.
 
-:::note Server features have their own configuration — for example, Ask AI needs a model API key. See the [AI guide](/docs/configuration/ai) for setup. :::
+:::note
+Server features have their own configuration — for example, Ask AI needs a model API key. See the [AI guide](/docs/configuration/ai) for setup.
+:::
 
 ## Redirects
 

package/docs/advanced/api-reference.mdx

@@ -1,9 +1,9 @@
 ---
 title: OpenAPI / AsyncAPI
-description: Drop in an OpenAPI or AsyncAPI spec and get an interactive reference, rendered by Scalar.
+description: Drop in an OpenAPI spec and get a native API reference — one real page per operation, in your sidebar and search.
 ---
 
-Point Blume at an OpenAPI or AsyncAPI spec and it generates an interactive API reference — schemas, authentication, examples, and a request playground — on its own route. The reference is rendered by [Scalar](https://scalar.com), not by Blume: API reference isn't core to Blume, so the whole surface is delegated to a tool that has already solved its large edge-case space.
+Point Blume at an OpenAPI spec and it generates a native API reference: one **real page per operation**, grouped by tag in a tab-scoped sidebar, with schema tables, request/response examples, and generated code samples. Because each operation is a genuine Blume page, it gets its own URL, shows up in **site search** and `llms.txt`, and gets an Open Graph image — the same as any hand-written doc.
 
 ```ts blume.config.ts lineNumbers
 openapi: {
@@ -12,13 +12,15 @@ openapi: {
 }
 ```
 
-That mounts the reference at `/reference` and adds a header link to it. The `spec` is either an `http(s)` URL or a path to a local file in your project.
+That mounts the reference at `/reference` (an overview page) with each operation at `/reference/<tag>/<operation>`, and adds a header tab. The `spec` is either an `http(s)` URL or a path to a local file in your project. Blume parses it with [Scalar's OpenAPI parser](https://github.com/scalar/scalar) — Swagger 2.0 and OpenAPI 3.0 specs are upgraded to 3.1 automatically.
 
-:::note The reference mounts inside Blume's shell — your navbar stays on top — but the body is a **self-contained Scalar embed** with its own sidebar, search, and theme. By design it doesn't weave into Blume's content sidebar, site search, or `llms.txt`. :::
+:::note
+Operations are indexed for search by their **summary and tag**. The rendered schema tables and code samples aren't full-text indexed; search matches an operation's title and section, then links to its own page.
+:::
 
 ## A local spec
 
-A relative path is resolved from your project root and inlined at build time, so nothing is copied into your source tree and the page works offline:
+A relative path is resolved from your project root and read at build time. Both JSON and YAML work:
 
 ```ts blume.config.ts lineNumbers
 openapi: {
@@ -27,23 +29,34 @@ openapi: {
 }
 ```
 
-Both JSON and YAML specs work; Scalar auto-detects the format.
-
 ## Route
 
-`route` controls where the reference mounts (and the header link's target):
+`route` controls where the reference mounts — the overview page and the prefix for every operation route (and the header tab's target):
 
 ```ts blume.config.ts lineNumbers
 openapi: {
   enabled: true,
-  route: "/api",
+  route: "/api",   // overview at /api, operations at /api/<tag>/<operation>
   spec: "./openapi.yaml",
 }
 ```
 
+## Code samples and schemas
+
+`codeSamples` picks which languages render per operation (built in: `curl`, `js`, `python`); `expandSchemas` starts nested schema rows expanded rather than collapsed:
+
+```ts blume.config.ts lineNumbers
+openapi: {
+  enabled: true,
+  spec: "./openapi.yaml",
+  codeSamples: ["curl", "js"],
+  expandSchemas: true,
+}
+```
+
 ## Multiple specs
 
-Use `sources` to publish more than one spec. Each source gets its own route and header link. Give each a `label` (used for the link and to derive its route), or set an explicit `route`:
+Use `sources` to publish more than one spec. Each source gets its own overview route, operation pages, and header tab. Give each a `label` (used for the tab and to derive its route), or set an explicit `route`:
 
 ```ts blume.config.ts lineNumbers
 openapi: {
@@ -57,31 +70,32 @@ openapi: {
 
 `spec` is shorthand for a single-entry `sources`, so you only reach for `sources` when you have more than one.
 
-## AsyncAPI
+## The Scalar renderer
 
-Event-driven APIs use a sibling `asyncapi` block with the **same shape** — Scalar renders AsyncAPI through the same component. Only the default route differs (`/events`):
+The native renderer is the default. If you'd rather embed [Scalar](https://scalar.com)'s self-contained API reference — its own sidebar, search, theme, and "Try it" playground on a single route — set `renderer: "scalar"`:
 
 ```ts blume.config.ts lineNumbers
-asyncapi: {
+openapi: {
   enabled: true,
-  spec: "./asyncapi.yaml",
+  renderer: "scalar",
+  spec: "./openapi.yaml",
+  theme: "purple",   // a Scalar theme name (Scalar renderer only)
 }
 ```
 
-:::warning Scalar's AsyncAPI support is still a work in progress — it renders channels, operations, messages, and a Models section, but there's **no interactive playground** for events yet. It improves upstream over time. :::
+A Scalar-rendered reference is a self-contained embed on its own route — it doesn't weave into Blume's sidebar, search, or `llms.txt`. Its "Try it" playground calls your **target API directly from the browser** (Blume doesn't proxy), so the API must allow cross-origin requests from the docs site (`Access-Control-Allow-Origin`). `theme` and the playground apply to the Scalar renderer only.
 
-## Theming
+## AsyncAPI
 
-By default Blume layers your [accent and radius](/docs/configuration/theming) onto Scalar's theme so the reference doesn't feel jarring. It's best-effort, not pixel-identical — Scalar carries its own design system. To pick a specific [Scalar theme](https://github.com/scalar/scalar) instead, set `theme`:
+Event-driven APIs use a sibling `asyncapi` block with the same shape. AsyncAPI is rendered by Scalar (the native renderer is OpenAPI-only for now); only the default route differs (`/events`):
 
 ```ts blume.config.ts lineNumbers
-openapi: {
+asyncapi: {
   enabled: true,
-  spec: "./openapi.yaml",
-  theme: "purple",
+  spec: "./asyncapi.yaml",
 }
 ```
 
-## The playground and CORS
-
-Scalar's "Try it" playground calls your **target API directly from the browser** — Blume doesn't proxy the request. For it to succeed, the API must allow cross-origin requests from the docs site (send the appropriate `Access-Control-Allow-Origin` headers). This is a property of the API being documented, not of Blume.
+:::warning
+Scalar's AsyncAPI support is still a work in progress — it renders channels, operations, messages, and a Models section, but there's **no interactive playground** for events yet. It improves upstream over time.
+:::