blume 2.1.3 → 2.2.1

package/dist/types/openapi/model.d.ts

@@ -1,6 +1,7 @@
 import type { Document, OperationObject } from "@scalar/openapi-types/3.2";
 import type { GraphqlAuthOptions } from "../reference/options.ts";
 import type { AsyncApiAction, AsyncApiDocument, AsyncApiSpecValue } from "./asyncapi.ts";
+import type { SpecIssue } from "./checks.ts";
 import type { GraphqlDocument, GraphqlMember } from "./graphql.ts";
 import type { ReferenceKind } from "./references.ts";
 export { slugify } from "./references.ts";
@@ -150,19 +151,48 @@ export declare const withServerDefaults: (template: string, variables: AsyncApiS
  * silently merges the tags' routes, sidebar groups, and overview sections.
  * Collisions gain `-2`, `-3`, … in first-seen order. Shared with the AsyncAPI
  * extractor (`asyncapi.ts`), whose untagged fallback groups are channel
- * addresses.
+ * addresses. `slug` is the rule before collisions: the collector also runs
+ * the one earlier releases used (`slugify` alone, so `InboxesThreads` ->
+ * `inboxesthreads`) to redirect the routes they gave.
  */
-export declare const tagSlugger: () => ((name: string) => string);
+export declare const tagSlugger: (slug?: (name: string) => string) => ((name: string) => string);
+/**
+ * How a warning names an operation: `GET /pets`, or a webhook by its name
+ * (`Webhook "newPet" (POST)`), since a webhook has no path.
+ */
+export declare const operationLabel: (name: string, method: string, webhook: boolean) => string;
 /** An operation before the collector assigns its unique key and route. */
 type CollectedOperation = Omit<ApiOperationRef, "route" | "tagSlug">;
+/** What a spec's `tags` list says about one tag. */
+export interface ApiTagMeta {
+    description: string;
+    /**
+     * The tag's label, in place of its name, from Redocly's `x-displayName`
+     * extension. Only the label changes: the tag's slug, and so its routes,
+     * still come from its name.
+     */
+    displayName?: string;
+}
+/**
+ * A route an earlier release gave an operation's page, and the route the
+ * page has now: the source turns each into a redirect, so links to the old
+ * URL keep working.
+ */
+export interface MovedRoute {
+    from: string;
+    to: string;
+}
 /** The flattened output both extractors produce. */
 export interface CollectedOperations {
     operations: ApiOperationRef[];
     tags: ApiTagRef[];
+    /** Operation routes that moved from what earlier slug rules gave them. */
+    moved: MovedRoute[];
 }
 /** The collector handle: feed operations in, read the flattened output out. */
 export interface OperationCollector {
-    add: (entry: CollectedOperation) => void;
+    /** Add an operation, returning it with its key and route assigned. */
+    add: (entry: CollectedOperation) => ApiOperationRef;
     finish: () => CollectedOperations;
 }
 /** {@link CollectedOperations} plus anything the extractor had to skip. */
@@ -175,15 +205,32 @@ export interface ExtractedOperations extends CollectedOperations {
  * (a repeated key gains its method/action as a suffix), and the shared route
  * template — so URL shape and slug rules can never drift between the two spec
  * kinds.
+ *
+ * A key is unique across the spec, since it names the operation in
+ * `<Operation id>`. Its page's URL only has to be unique within its tag's
+ * folder, so the last route segment de-duplicates per tag: `list` in two
+ * tags is `/pets/list` and `/stores/list`, not `/stores/list-get`. Earlier
+ * releases de-duplicated the route like the key, and slugged tags without
+ * splitting their words; each route those rules gave differently is
+ * reported in `moved`.
  */
-export declare const operationCollector: (baseRoute: string, tagMeta: ReadonlyMap<string, string>) => OperationCollector;
+export declare const operationCollector: (baseRoute: string, tagMeta: ReadonlyMap<string, ApiTagMeta>) => OperationCollector;
+/** {@link ExtractedOperations} plus the spec mistakes extraction noticed. */
+export interface ExtractedApiOperations extends ExtractedOperations {
+    issues: SpecIssue[];
+}
 /**
  * Flatten a 3.1 document into a route-mapped operation list and its ordered
  * tags, webhooks included. Operations inherit the first tag they declare; keys
- * are de-duplicated so a repeated `operationId` still yields distinct routes.
- * `warnings` reports anything skipped (a `$ref` path item), so missing
- * operations aren't silent.
+ * are de-duplicated so a repeated `operationId` still yields distinct routes,
+ * with an issue naming both operations. `warnings` reports anything skipped (a
+ * `$ref` path item), so missing operations aren't silent.
+ *
+ * Operations come out in the spec's order: paths as listed, and each path's
+ * methods as written. They're keyed in the method order earlier releases
+ * walked (`HTTP_METHODS`), so a repeated id resolves to the same key, and
+ * the same route, it always did.
  */
-export declare const extractOperations: (document: ApiDocument, baseRoute: string) => ExtractedOperations;
+export declare const extractOperations: (document: ApiDocument, baseRoute: string) => ExtractedApiOperations;
 /** Resolve the operation object for a ref out of its (OpenAPI) document. */
 export declare const operationObject: (spec: ApiSpecData, ref: ApiOperationRef) => OperationObject | undefined;

package/dist/types/openapi/parse.d.ts

@@ -4,7 +4,10 @@ import type { GraphqlDocument } from "./graphql.ts";
 import type { ApiDocument } from "./model.ts";
 export interface ParsedSpec {
     document: ApiDocument;
-    /** `x-codeSamples` entries whose `$ref` couldn't be inlined. */
+    /**
+     * Issues only the spec as written shows: `nullable` in a 3.1 spec, and
+     * `x-codeSamples` entries whose `$ref` couldn't be inlined.
+     */
     issues: SpecIssue[];
     warnings: string[];
 }

package/dist/types/ratelimit/index.d.ts

@@ -25,3 +25,5 @@ export type { MemoryAdapter, RateLimitOptions } from "./memory.ts";
 export type { RateLimitAdapter } from "./schema.ts";
 export { upstash } from "./upstash.ts";
 export type { UpstashAdapter, UpstashOptions } from "./upstash.ts";
+export { unkey } from "./unkey.ts";
+export type { UnkeyAdapter, UnkeyOptions } from "./unkey.ts";

package/dist/types/ratelimit/memory.d.ts

@@ -31,6 +31,6 @@ export declare const memoryAdapterSchema: z.ZodObject<{
  * platform that runs many short-lived instances (Vercel, Netlify,
  * Cloudflare) each instance keeps its own, so it stops a burst from one
  * reader rather than enforcing the limit exactly. For that, share the count
- * with `upstash()` or `cloudflare()`.
+ * with `upstash()`, `cloudflare()`, or `unkey()`.
  */
 export declare const memory: (options?: RateLimitOptions) => MemoryAdapter;

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

@@ -27,6 +27,16 @@ export declare const rateLimitAdapterSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
     }, z.core.$strict>;
     requiredSecrets: z.ZodArray<z.ZodString>;
     runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"unkey">;
+    options: z.ZodObject<{
+        requests: z.ZodOptional<z.ZodNumber>;
+        namespace: z.ZodOptional<z.ZodString>;
+        rootKeyEnv: z.ZodOptional<z.ZodString>;
+        window: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
 }, z.core.$strict>], "kind">;
 export type RateLimitAdapter = z.output<typeof rateLimitAdapterSchema>;
 /**
@@ -62,6 +72,16 @@ export declare const rateLimitConfigSchema: z.ZodPipe<z.ZodOptional<z.ZodUnion<r
     }, z.core.$strict>;
     requiredSecrets: z.ZodArray<z.ZodString>;
     runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"unkey">;
+    options: z.ZodObject<{
+        requests: z.ZodOptional<z.ZodNumber>;
+        namespace: z.ZodOptional<z.ZodString>;
+        rootKeyEnv: z.ZodOptional<z.ZodString>;
+        window: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
 }, z.core.$strict>], "kind">]>>, z.ZodTransform<{
     kind: "cloudflare";
     options: {
@@ -89,6 +109,16 @@ export declare const rateLimitConfigSchema: z.ZodPipe<z.ZodOptional<z.ZodUnion<r
     };
     requiredSecrets: string[];
     runtimeDeps: string[];
+} | {
+    kind: "unkey";
+    options: {
+        requests?: number | undefined;
+        namespace?: string | undefined;
+        rootKeyEnv?: string | undefined;
+        window?: number | undefined;
+    };
+    requiredSecrets: string[];
+    runtimeDeps: string[];
 } | null, false | {
     kind: "cloudflare";
     options: {
@@ -116,4 +146,14 @@ export declare const rateLimitConfigSchema: z.ZodPipe<z.ZodOptional<z.ZodUnion<r
     };
     requiredSecrets: string[];
     runtimeDeps: string[];
+} | {
+    kind: "unkey";
+    options: {
+        requests?: number | undefined;
+        namespace?: string | undefined;
+        rootKeyEnv?: string | undefined;
+        window?: number | undefined;
+    };
+    requiredSecrets: string[];
+    runtimeDeps: string[];
 } | undefined>>;

package/dist/types/ratelimit/unkey.d.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import type { RateLimitOptions } from "./memory.ts";
+/** The Unkey rate limit namespace the count is kept in, unless set. */
+export declare const UNKEY_NAMESPACE = "docs";
+/** The longest window Unkey takes, in seconds (30 days). */
+export declare const UNKEY_MAX_WINDOW = 2592000;
+/** Options for {@link unkey}. */
+export interface UnkeyOptions extends RateLimitOptions {
+    /**
+     * The Unkey rate limit namespace, up to 512 characters. Defaults to `docs`;
+     * Unkey creates it on the first request.
+     */
+    namespace?: string;
+    /** Name of the env var holding the root key. Defaults to `UNKEY_ROOT_KEY`. */
+    rootKeyEnv?: string;
+    /** The window, in seconds: Unkey takes up to 30 days. */
+    window?: number;
+}
+export declare const unkeyOptionsSchema: z.ZodObject<{
+    requests: z.ZodOptional<z.ZodNumber>;
+    namespace: z.ZodOptional<z.ZodString>;
+    rootKeyEnv: z.ZodOptional<z.ZodString>;
+    window: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type UnkeyAdapter = AdapterDescriptor<"unkey", UnkeyOptions>;
+export declare const unkeyAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"unkey">;
+    options: z.ZodObject<{
+        requests: z.ZodOptional<z.ZodNumber>;
+        namespace: z.ZodOptional<z.ZodString>;
+        rootKeyEnv: z.ZodOptional<z.ZodString>;
+        window: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/** The env var the root key is read from. */
+export declare const unkeySecrets: (options: UnkeyOptions) => [string];
+/**
+ * Counts with Unkey's rate limiting, which every instance on every host
+ * shares. Unkey counts in each region and shares the counts between them
+ * within moments, so a short burst split across regions can pass more than
+ * the limit. It talks to Unkey's REST API, so there is nothing to install;
+ * the root key comes from `UNKEY_ROOT_KEY`, or the env var `rootKeyEnv`
+ * names.
+ */
+export declare const unkey: (options?: UnkeyOptions) => UnkeyAdapter;

package/dist/types/sources/filesystem.d.ts

@@ -3,11 +3,21 @@ import type { AdapterDescriptor } from "../core/adapter.ts";
 import type { SharedSourceOptions } from "./shared.ts";
 /** What `include` defaults to: every Markdown/MDX file under the root. */
 export declare const DEFAULT_CONTENT_INCLUDE: string[];
-/** What `exclude` defaults to: underscore- and dot-prefixed paths. */
+/** What `exclude` always holds: underscore- and dot-prefixed paths. */
 export declare const DEFAULT_CONTENT_EXCLUDE: string[];
+/**
+ * A source's `exclude` as the scan applies it: the defaults, plus the
+ * author's patterns. A `!pattern` entry takes that exact pattern back out, a
+ * default included, so `["!**\/_*"]` publishes `_`-prefixed files. The glob
+ * library can't negate an ignore pattern itself.
+ */
+export declare const resolveContentExclude: (patterns: readonly string[]) => string[];
 /** Options for {@link filesystem}. */
 export interface FilesystemOptions extends SharedSourceOptions {
-    /** Glob patterns to ignore. Defaults to `["**\/_*", "**\/.*"]`. */
+    /**
+     * Glob patterns to ignore, on top of `["**\/_*", "**\/.*"]`. A `!pattern`
+     * entry stops ignoring that pattern, a default included.
+     */
     exclude?: string[];
     /** Glob patterns to include. Defaults to `["**\/*.{md,mdx}"]`. */
     include?: string[];
@@ -17,7 +27,7 @@ export interface FilesystemOptions extends SharedSourceOptions {
 export declare const filesystemOptionsSchema: z.ZodObject<{
     pollInterval: z.ZodOptional<z.ZodNumber>;
     prefix: z.ZodOptional<z.ZodString>;
-    exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    exclude: z.ZodPipe<z.ZodDefault<z.ZodArray<z.ZodString>>, z.ZodTransform<string[], string[]>>;
     include: z.ZodDefault<z.ZodArray<z.ZodString>>;
     root: z.ZodDefault<z.ZodString>;
 }, z.core.$strict>;
@@ -27,7 +37,7 @@ export declare const filesystemAdapterSchema: z.ZodObject<{
     options: z.ZodObject<{
         pollInterval: z.ZodOptional<z.ZodNumber>;
         prefix: z.ZodOptional<z.ZodString>;
-        exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        exclude: z.ZodPipe<z.ZodDefault<z.ZodArray<z.ZodString>>, z.ZodTransform<string[], string[]>>;
         include: z.ZodDefault<z.ZodArray<z.ZodString>>;
         root: z.ZodDefault<z.ZodString>;
     }, z.core.$strict>;

package/dist/types/sources/mdx-remote.d.ts

@@ -56,8 +56,11 @@ export declare const mdxRemoteAdapterSchema: z.ZodObject<{
 /**
  * Remote Markdown/MDX fetched over HTTP. Enumerate files explicitly against a
  * raw `url` base, or from a GitHub repo subtree via `github`. A private repo's
- * token comes from `GITHUB_TOKEN` — never inline it here. The adapter declares
- * the variable only when it reads from GitHub, since a `url` on any other host
- * is never sent the token.
+ * token comes from `GITHUB_TOKEN` — never inline it here. Only `github`
+ * declares the variable: it lists files through GitHub's API, whose
+ * unauthenticated rate limit a build can run into even for a public
+ * repository. A raw `url` needs no token for a public repository, so a fetch
+ * that fails for want of one names the variable instead (see
+ * core/sources/mdx-remote.ts).
  */
 export declare const mdxRemote: (options: MdxRemoteOptions) => MdxRemoteAdapter;

package/dist/types/sources/registry.d.ts

@@ -18,7 +18,7 @@ declare const sourceAdapterUnion: z.ZodDiscriminatedUnion<readonly [z.ZodObject<
     options: z.ZodObject<{
         pollInterval: z.ZodOptional<z.ZodNumber>;
         prefix: z.ZodOptional<z.ZodString>;
-        exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        exclude: z.ZodPipe<z.ZodDefault<z.ZodArray<z.ZodString>>, z.ZodTransform<string[], string[]>>;
         include: z.ZodDefault<z.ZodArray<z.ZodString>>;
         root: z.ZodDefault<z.ZodString>;
     }, z.core.$strict>;
@@ -193,7 +193,7 @@ export declare const resolvedSourceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUn
     options: z.ZodObject<{
         pollInterval: z.ZodOptional<z.ZodNumber>;
         prefix: z.ZodOptional<z.ZodString>;
-        exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        exclude: z.ZodPipe<z.ZodDefault<z.ZodArray<z.ZodString>>, z.ZodTransform<string[], string[]>>;
         include: z.ZodDefault<z.ZodArray<z.ZodString>>;
         root: z.ZodDefault<z.ZodString>;
     }, z.core.$strict>;
@@ -998,7 +998,7 @@ export declare const contentSourcesSchema: z.ZodArray<z.ZodPipe<z.ZodCustom<{
     options: z.ZodObject<{
         pollInterval: z.ZodOptional<z.ZodNumber>;
         prefix: z.ZodOptional<z.ZodString>;
-        exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        exclude: z.ZodPipe<z.ZodDefault<z.ZodArray<z.ZodString>>, z.ZodTransform<string[], string[]>>;
         include: z.ZodDefault<z.ZodArray<z.ZodString>>;
         root: z.ZodDefault<z.ZodString>;
     }, z.core.$strict>;

package/dist/types/theme/color.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Just enough CSS color math to check contrast at build time: parse the color
+ * syntaxes a theme config takes (hex, `rgb()`, `hsl()`, `hwb()`, `lab()`,
+ * `lch()`, `oklab()`, `oklch()`, and named colors) to sRGB, then measure WCAG
+ * 2 relative luminance and contrast. A color outside sRGB is clipped to it,
+ * which is what a browser shows on an sRGB display. Anything else — `var()`,
+ * `color-mix()`, `color()` — parses to `null`, and the caller says it couldn't
+ * check it rather than guessing.
+ */
+/** An sRGB color: gamma-encoded channels and alpha, each 0–1. */
+export interface Rgba {
+    alpha: number;
+    blue: number;
+    green: number;
+    red: number;
+}
+/** Parse a CSS color to sRGB, or `null` for syntax this module doesn't read. */
+export declare const parseColor: (value: string) => Rgba | null;
+/**
+ * Whether `value` is a CSS color: one `parseColor` reads, or a color function
+ * or keyword it leaves unread. Words that name no color (`deep purple`), and
+ * hex values with a wrong digit count or no `#`, are not.
+ */
+export declare const isCssColor: (value: string) => boolean;
+/** `color` painted over an opaque `backdrop`. */
+export declare const composite: (color: Rgba, backdrop: Rgba) => Rgba;
+/** WCAG 2 relative luminance of an opaque color. */
+export declare const luminance: (color: Rgba) => number;
+/**
+ * WCAG 2 contrast ratio of `foreground` on an opaque `background`, from 1 to
+ * 21. A translucent foreground is painted over the background first.
+ */
+export declare const contrastRatio: (foreground: Rgba, background: Rgba) => number;

package/dist/types/theme/palette.d.ts

@@ -0,0 +1,122 @@
+import type { ResolvedConfig } from "../core/schema.ts";
+import type { Rgba } from "./color.ts";
+/** Per-mode CSS colors. */
+export interface AccentColors {
+    dark: string;
+    light: string;
+}
+/** A color mode. */
+export type ColorMode = keyof AccentColors;
+/**
+ * Named accent presets mapped to OKLCH values, per mode. The single source of
+ * truth for preset colors: the theme CSS and the OG card (og/card.ts) both
+ * resolve from this table, so a site and its social cards can't disagree
+ * about "blue". Each clears WCAG AA (4.5:1) as text on its mode's page and
+ * under its button label ({@link readableOn}), with room to spare on the
+ * tinted surfaces accent text also sits on: the light shades are dark enough
+ * for white labels, the dark shades light enough to read on the dark page.
+ */
+export declare const ACCENTS: {
+    blue: {
+        dark: string;
+        light: string;
+    };
+    green: {
+        dark: string;
+        light: string;
+    };
+    orange: {
+        dark: string;
+        light: string;
+    };
+    pink: {
+        dark: string;
+        light: string;
+    };
+    purple: {
+        dark: string;
+        light: string;
+    };
+    red: {
+        dark: string;
+        light: string;
+    };
+    teal: {
+        dark: string;
+        light: string;
+    };
+};
+/** The contrast WCAG AA asks of body-size text. */
+export declare const MIN_TEXT_CONTRAST = 4.5;
+/**
+ * The theme's own colors a configured accent is drawn against: each mode's
+ * page background and text, and the dark ink a filled accent can carry.
+ * Mirrors the defaults in `entry.ts`.
+ */
+export declare const THEME_INKS: {
+    dark: {
+        background: string;
+        foreground: string;
+        ink: string;
+        mutedForeground: string;
+    };
+    light: {
+        background: string;
+        foreground: string;
+        ink: string;
+        mutedForeground: string;
+    };
+};
+/** {@link THEME_INKS}, parsed, for contrast math. */
+export declare const themeInk: (mode: ColorMode, name: keyof (typeof THEME_INKS)[ColorMode]) => Rgba;
+/**
+ * The label color for text on a filled `fill` (a button, a step number): white
+ * while it reaches AA, else the mode's dark ink when that reads better, so a
+ * light accent (every dark-mode preset) gets dark text instead of white text
+ * nobody can read.
+ */
+export declare const labelOn: (fill: Rgba, mode: ColorMode) => string;
+/** {@link labelOn} for a CSS color; one this module can't parse keeps white. */
+export declare const readableOn: (fill: string, mode: ColorMode) => string;
+/**
+ * Whether a raw config value names an accent preset. `hasOwn` keeps a value
+ * like "constructor" from resolving an Object.prototype member — which would
+ * stringify a function into the generated CSS, breaking the rule (the exact
+ * breakout {@link safeColor} exists to prevent).
+ */
+export declare const isAccentPreset: (value: string) => value is keyof typeof ACCENTS;
+/**
+ * Resolve the configured accent to per-mode CSS colors. A named accent
+ * resolves to its preset's shade for each mode; any other value is treated as
+ * a raw CSS color so users can pass arbitrary colors without a config change.
+ * A string accent has already been normalized by the config schema to the
+ * same value for both modes.
+ */
+export declare const resolveAccent: (theme: ResolvedConfig["theme"]) => AccentColors;
+/** Resolve the configured `action` fill per mode, or `null` when unset. */
+export declare const resolveAction: (theme: ResolvedConfig["theme"]) => AccentColors | null;
+/** Resolve the configured radius preset to a CSS length. */
+export declare const resolveRadius: (theme: ResolvedConfig["theme"]) => string;
+/**
+ * Compile theme config into CSS custom properties. A named accent resolves to
+ * its preset; any other value is treated as a raw CSS color so users can pass
+ * arbitrary colors without a config change. Labels on accent and action fills
+ * take whichever of white or dark ink reads ({@link readableOn}).
+ */
+export declare const buildThemeCss: (theme: ResolvedConfig["theme"]) => string;
+/** A configured color: where the config sets it, and its value. */
+export interface ColorSetting {
+    /** The config path, e.g. `["theme", "accent", "dark"]`. */
+    path: string[];
+    /** Whether the field also takes an accent preset name (`teal`). */
+    presets: boolean;
+    value: string;
+}
+/**
+ * The configured colors that aren't CSS colors (`"deep purple"`, a hex value
+ * missing its `#`): `theme.accent`, `theme.action`, and `theme.background`,
+ * and the OG card's `seo.og.palette`. The schema takes any string, so a
+ * mistake would otherwise reach the stylesheet, where browsers drop it, or
+ * the card renderer, which rejects it. Preset names are CSS color names too.
+ */
+export declare const invalidColorSettings: (config: ResolvedConfig) => ColorSetting[];

package/docs/01-quickstart.mdx

@@ -6,7 +6,7 @@ sidebar:
   order: 1
 ---
 
-Go from an empty folder to a running docs site in a few commands. Blume needs **Node.js 22.12 or newer** and a `docs/` folder with at least one `.md` or `.mdx` file — there's nothing else to set up.
+Go from an empty folder to a running docs site in a few commands. Blume needs **Node.js 22.19 or newer** and a `docs/` folder with at least one `.md` or `.mdx` file — there's nothing else to set up.
 
 ## Install and run
 

package/docs/02-deployment.mdx

@@ -14,7 +14,7 @@ sidebar:
 | ---------------- | -------------- |
 | Build command    | `blume build`  |
 | Output directory | `dist`         |
-| Node version     | 22.12 or newer |
+| Node version     | 22.19 or newer |
 
 These settings work on Vercel, Netlify, Cloudflare Pages, GitHub Pages, or any bucket or CDN. Make sure `blume` is a dependency so the host can run the build.
 
@@ -68,9 +68,16 @@ blume preview
 
 `blume preview` serves static builds and `node()` and `cloudflare()` server builds. The Vercel and Netlify adapters have no local preview server, so after a `vercel()` or `netlify()` server build it stops with an error instead. Try the site with `blume dev`, or deploy a preview with `vercel deploy` or `netlify deploy`.
 
+On a static build, `blume preview` also answers what the host would, beyond the files in `dist/`. It applies the [redirects](#redirects), patterns included, with their configured status, as the host files the build writes do. It also handles trailing slashes the way static hosts do:
+
+- A page's URL with a trailing slash (`/guide/`) redirects to the page (`/guide`), keeping the query string.
+- A folder of HTML you ship in `public/` (`public/demo/index.html`) is served at `/demo/`, and `/demo` redirects there, so the relative links inside it resolve.
+
+`blume dev` handles trailing slashes the same way.
+
 ## Subpath deploys
 
-Serving docs under a path like `example.com/docs`? Set `base` — common for GitHub Pages project sites. The whole site, root included, moves under the base, and internal links and assets are rewritten to include it.
+Serving docs under a path like `example.com/docs`? Set `base` — common for GitHub Pages project sites. The whole site, root included, moves under the base, and internal links and assets are rewritten to include it, along with a root-relative `href` or `src` in raw HTML (`<a href="/guide">`, `<img src="/logo.png">`).
 
 ```ts blume.config.ts lineNumbers
 deployment: {
@@ -153,6 +160,8 @@ deployment: netlify({ output: "static" }),
 
 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 with `node dist/server/entry.mjs`. It listens on `localhost:4321` unless you set the `HOST` and `PORT` environment variables when you start it (`HOST=0.0.0.0 PORT=8080 node dist/server/entry.mjs`); `host` and `port` passed to `node()` have no effect, because `@astrojs/node` replaces them with Astro's own server settings. Behind a reverse proxy, set `allowedDomains` so the [rate limit](/docs/configuration/rate-limiting#behind-a-reverse-proxy) counts each reader apart. The server resolves its packages through links into your project's `node_modules`, so deploy the project with its installed dependencies, not `dist/` alone. When the site publishes discovery files, serves images a content source downloaded, or configures redirects, Blume puts a small wrapper in front of Astro's entry (moved to `astro-entry.mjs` beside it). It sends the `.well-known` discovery files with their media types and CORS headers and downloaded SVGs sandboxed, which the standalone server's static handler can't do on its own, and answers each redirect with its configured status.
 
+A `vercel()` server build checks the function bundle the adapter traced for packages it imports but didn't copy, which would crash the function on Vercel. A missing import of your own is a warning. A missing Blume dependency stops the build, and the build removes `.vercel/output/config.json`, so `vercel deploy --prebuilt` can't ship the output without the routes Blume adds to it.
+
 A `cloudflare()` server build runs on Cloudflare Workers only, since `@astrojs/cloudflare` dropped Cloudflare Pages in version 13; a static build doesn't load the package, so its `dist/` still deploys to Pages. The server build deploys with `npx wrangler deploy` from the project root after `blume build`: Blume writes the redirected Wrangler config to `.wrangler/deploy/` (and adds `.wrangler/` to `.gitignore`), and names the Worker after your project — the `package.json` `name`, else the site's hostname, else the folder — unless a `wrangler.jsonc` of your own at the project root sets `name`.
 
 On Vercel and Cloudflare, a server build also turns on [`Accept: text/markdown` content negotiation](/docs/discoverability/markdown#content-negotiation), so an agent requesting any content page with that header receives its raw-Markdown mirror at the same URL. On Vercel, Blume splices header-conditional rewrites into the deploy's routing config; on Cloudflare, it generates a small Worker in front of the Astro one and points `assets.run_worker_first` at every path except the fingerprinted build assets and the raw `.md`, `.txt`, `.json`, and `.well-known` files, since the platform would otherwise serve the prerendered pages — and its `404.html` for a URL no page backs — before any server code runs; those exempted files keep their zero-Worker fast path. That Worker also answers the prerendered per-page JSON documents (`/api/docs/pages/{route}.json`) from the asset binding when a request for one reaches it, because Astro would otherwise route it to the `/api/` catch-all.
@@ -190,9 +199,13 @@ Map old URLs to new ones in `blume.config.ts`:
 redirects: [{ from: "/old", to: "/new", status: 301 }],
 ```
 
-`status` accepts `301`, `302`, `307`, or `308` (default `301`). Server builds answer redirects at request time with the configured status, and so does `blume dev`. Static builds emit redirect pages **and** the platform files your host reads, so it issues a real HTTP redirect: `_redirects` for `netlify()` and `cloudflare()`, `vercel.json` for `vercel()`, and — when no host is named — both of those plus `blume-redirects.json`, a structured manifest for anything else (nginx/Apache rules, an edge worker). A `_redirects` or `vercel.json` you ship in `public/` is left untouched.
+`status` accepts `301`, `302`, `307`, or `308` (default `301`). Server builds answer redirects at request time with the configured status, and so do `blume dev` and `blume preview`. Static builds emit redirect pages **and** the platform files your host reads, so it issues a real HTTP redirect: `_redirects` for `netlify()` and `cloudflare()`, `vercel.json` for `vercel()`, and — when no host is named — both of those plus `blume-redirects.json`, a structured manifest for anything else (nginx/Apache rules, an edge worker). A `_redirects` or `vercel.json` you ship in `public/` is left untouched.
 
-A redirect that moves one page to another moves the page's [raw Markdown](/docs/discoverability/markdown#raw-markdown) with it: `/old.md` and `/old.mdx` redirect to `/new.md` and `/new.mdx` with the same status, in `blume dev` and every build.
+A redirect that moves one page to another moves the page's [raw Markdown](/docs/discoverability/markdown#raw-markdown) with it: `/old.md` and `/old.mdx` redirect to `/new.md` and `/new.mdx` with the same status, in `blume dev` and every build. A redirect from an `.html` URL, like `/old.html` from a site you migrated, doesn't, since that URL never had a Markdown copy. Nor does one whose Markdown URL already serves a copy: `/index.md` is the home page's, so a redirect from `/index` to `/` leaves it alone.
+
+A redirect from a page's own `index.html` URL, like `/guide/index.html` to `/guide`, gets no redirect page in a static build, because the page itself is written to that file. Hosts that read the redirect files answer it with the redirect. Any other host serves the page at that URL.
+
+Blume adds one kind of redirect itself: a date-named page that an earlier version published under a shorter URL, like `changelog/12-05-2022.mdx` at `/changelog/05-2022`, redirects from that URL to its own (see [ordering with numeric prefixes](/docs/content#ordering-with-numeric-prefixes)). It adds none where another page lives at the old URL or a redirect you configured already starts there.
 
 Two hosts need more than the file:
 
@@ -217,14 +230,16 @@ redirects: [
 ```
 
 - `:name` matches one whole segment: `/blog/:slug` covers `/blog/hello`, not `/blog/a/b`.
-- `:name*` as the last segment matches the rest of the path, any number of segments: `/beta/:slug*` sends `/beta/guides/setup` to `/v2/guides/setup`, and `/beta` itself to `/v2`. A last segment of `*` does the same.
+- `:name*` as the last segment matches the rest of the path, any number of segments: `/beta/:slug*` sends `/beta/guides/setup` to `/v2/guides/setup`, and `/beta` itself to `/v2`. A last segment of `*` does the same. Every host gets that bare path as a rule of its own (`/beta /v2` in `_redirects`), so all of them send it to the same place. `blume audit` checks where it lands, and reports `/beta` going to a `/v2` the build doesn't serve as a broken redirect.
 - `*` at the end of a segment matches the rest of the path from there: `/articles/concepts-*` covers `/articles/concepts-overview`.
 
 `to` reads a capture by name, as a whole segment (`/:slug*`, `/:slug`), or a `*` for what the `*` in `from` matched (`:splat`, the way `_redirects` spells it, reads it too). A `to` that reads no capture sends every path the pattern covers to one page. An exact redirect wins over a pattern that covers the same path, and patterns are tried in the order you list them.
 
-Each host gets the patterns in its own syntax: splats in `_redirects`, `path-to-regexp` sources in `vercel.json`, and the routing config of a `vercel()` or `netlify()` server build. The `node()` and `cloudflare()` servers match them themselves, and so does `blume dev`. A static build writes no redirect page for a pattern, since it would need one for every path the pattern covers, so a host that reads none of these files (GitHub Pages, say) applies only the exact redirects; `blume-redirects.json` lists patterns as you wrote them.
+Each host gets the patterns in its own syntax: splats in `_redirects`, `path-to-regexp` sources in `vercel.json`, and the routing config of a `vercel()` or `netlify()` server build. The `node()` and `cloudflare()` servers match them themselves, and so do `blume dev` and `blume preview`. A static build writes no redirect page for a pattern, since it would need one for every path the pattern covers, so a host that reads none of these files (GitHub Pages, say) applies only the exact redirects; `blume-redirects.json` lists patterns as you wrote them.
+
+[`blume validate`](/docs/cli/validate) checks where each redirect leads. An exact `to` must be a page, a file in `public/` or one Blume generates, or another redirect's `from`; for a pattern, something must be served under the literal part of `to` before its first capture (`/v2/` in `/v2/:slug*`). One that leads nowhere warns `BLUME_BROKEN_REDIRECT` at its `to`. [`blume audit`](/docs/cli/audit) follows every redirect through the built site.
 
-A pattern can't also match a page: hosts disagree on which of the two answers, so the build stops with `BLUME_REDIRECT_MATCHES_PAGE`, naming the page. Narrow the pattern to the paths that moved. An exact redirect from a page's own URL answers the same way on every host, taking the URL over so the page never publishes, so the same code is a warning there: delete the page if it moved, or drop the redirect.
+A pattern can't also match a page: hosts disagree on which of the two answers, so the build stops with `BLUME_REDIRECT_MATCHES_PAGE`, naming the page. Narrow the pattern to the paths that moved. An exact redirect from a page's own URL answers the same way on every host, taking the URL over so the page never publishes, so the same code is a warning there: delete the page if it moved, or drop the redirect. So is one from a page's Markdown copy, like `/guide.md` or the home page's `/index.md`, which takes that copy away from agents: drop the redirect.
 
 ## Content types
 
@@ -252,9 +267,10 @@ When a feature needs a secret, Blume warns at `blume dev`/`build` if it's missin
 | Assistant (other adapters) | the adapter's default key env var (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY`, `OPENROUTER_API_KEY`, `LLMGATEWAY_API_KEY`, `INKEEP_API_KEY`), or the `apiKeyEnv` you passed it |
 | [Assistant bot protection](/docs/configuration/assistant#bot-protection) | `TURNSTILE_SECRET_KEY` (`turnstile()`), `HCAPTCHA_SECRET_KEY` (`hcaptcha()`) |
 | [Rate limiting](/docs/configuration/rate-limiting) (`upstash()`) | `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` |
+| [Rate limiting](/docs/configuration/rate-limiting) (`unkey()`) | `UNKEY_ROOT_KEY`, or the `rootKeyEnv` you passed it |
 | Mixedbread search | `MIXEDBREAD_API_KEY` |
 | [Narration](/docs/configuration/narration) (generated voices) | `AI_GATEWAY_API_KEY` (or Vercel OIDC) for `gateway()`, `OPENAI_API_KEY` for `openai()` (none with a `baseUrl`, unless you name one), or the `apiKeyEnv` you passed to either |
-| [Content sources](/docs/content/sources) | `NOTION_TOKEN` (`notion()`), `SANITY_TOKEN` (`sanity()`), `CONTENTFUL_ACCESS_TOKEN` (`contentful()`, plus `CONTENTFUL_PREVIEW_TOKEN` for `--preview`, which fails without it), `PAYLOAD_API_KEY` (`payload()`), `STRAPI_API_TOKEN` (`strapi()`), `GITHUB_TOKEN` (`githubReleases()`, and `mdxRemote()` reading from GitHub) |
+| [Content sources](/docs/content/sources) | `NOTION_TOKEN` (`notion()`), `SANITY_TOKEN` (`sanity()`), `CONTENTFUL_ACCESS_TOKEN` (`contentful()`, plus `CONTENTFUL_PREVIEW_TOKEN` for `--preview`, which fails without it), `PAYLOAD_API_KEY` (`payload()`), `STRAPI_API_TOKEN` (`strapi()`), `GITHUB_TOKEN` (`githubReleases()`, and `mdxRemote()` with `github`) |
 
 Set them in `.env.local` for local dev and in your host's environment for production. A content source reads its token when it fetches, during `blume dev` and `blume build`, and narration reads its key during `blume build`, so set those where your site builds. Build-time secrets for search-index sync (`ALGOLIA_ADMIN_API_KEY`, `ORAMA_PRIVATE_API_KEY`, `TYPESENSE_ADMIN_API_KEY`) are checked by the sync step itself: when one is unset, the build warns and skips the sync, and when it's set, a failed sync [fails the build](/docs/configuration/search#adapters). The [GitHub info](/docs/content/components#github-info) card also sends `GITHUB_TOKEN`, when it's set, to lift GitHub's API rate limit.
 

package/docs/04-migrating.mdx

@@ -1,6 +1,6 @@
 ---
 title: Migrate to Blume
-description: Move a Mintlify, Fumadocs, Docusaurus, Starlight, or Nextra site to Blume with one command that hands the migration to Codex or Claude Code.
+description: Move a Mintlify, Docusaurus, GitBook, MkDocs, ReadMe, or other docs site to Blume with one command that hands the migration to Codex or Claude Code.
 sidebar:
   label: Migrate to Blume
   order: 2.4
@@ -29,8 +29,20 @@ Name the framework you're migrating from, or leave it out and Blume detects it f
 | `docusaurus` | `docusaurus.config.*` | [Migrate from Docusaurus](/guides/migrate-from-docusaurus) |
 | `starlight` | `@astrojs/starlight` in `package.json` | [Migrate from Starlight](/guides/migrate-from-starlight) |
 | `nextra` | `nextra` in `package.json` | [Migrate from Nextra](/guides/migrate-from-nextra) |
-
-Each source has its own mapping reference in the playbook. A site built with anything else still migrates: run the command without a source, and the agent inventories the repo first, then works from the playbook's general rules. The [MkDocs Material guide](/guides/migrate-from-mkdocs-material) walks through a migration that way.
+| `vitepress` | `.vitepress/config.ts` (or `.mts`, `.js`, `.mjs`) at the root or in `docs/`, or `vitepress` in `package.json` | [Migrate from VitePress](/guides/migrate-from-vitepress) |
+| `vuepress` | `.vuepress/config.ts` (or `.js`, `.mjs`, `.yml`, `.toml`) at the root or in `docs/`, `vuepress.config.*`, or `vuepress` (or `vuepress-vite`, `vuepress-webpack`) in `package.json` | [Migrate from VuePress](/guides/migrate-from-vuepress) |
+| `docus` | `docus` (Docus 3 and later) or `@nuxt-themes/docus` (Docus 1) in `package.json`; run it from the docs package in a workspace | [Migrate from Docus](/guides/migrate-from-docus) |
+| `mkdocs` | `mkdocs.yml`, `mkdocs.yaml`, `zensical.toml`, `properdocs.yml`, or `properdocs.yaml` | [Migrate from MkDocs Material](/guides/migrate-from-mkdocs-material) |
+| `mdbook` | `book.toml` at the root or in `docs/` or `book/` | [Migrate from mdBook](/guides/migrate-from-mdbook) |
+| `fern` | `fern/docs.yml` | [Migrate from Fern](/guides/migrate-from-fern) |
+| `gitbook` | `.gitbook.yaml`, `.gitbook.yml`, or `gitbook-docs.yaml`, or `honkit` or `gitbook-cli` in `package.json`; never `SUMMARY.md` alone | [Migrate from GitBook](/guides/migrate-from-gitbook) |
+| `redocly` | `sidebars.yaml`, or `@redocly/realm` or another Realm-family package in `package.json`; never `redocly.yaml` alone | [Migrate from Redocly](/guides/migrate-from-redocly) |
+| `readme` | `_order.yaml` in `docs/`, `reference/`, `recipes/`, or `custom_pages/`; a repository that uploads with `rdme` needs the source named | [Migrate from ReadMe](/guides/migrate-from-readme) |
+| `docsify` | `docsify-cli` or `docsify` in `package.json`; a site without a `package.json` needs the source named | [Migrate from Docsify](/guides/migrate-from-docsify) |
+| `jekyll` | `_config.yml` at the root or in `docs/`, checked after every other source Blume detects | [Migrate from Just the Docs](/guides/migrate-from-jekyll) |
+| `github-wiki` | Never detected: a wiki has no config file, so name the source | [Migrate from a GitHub wiki](/guides/migrate-from-github-wiki) |
+
+Detection checks the folder you run the command in. Each source has its own mapping reference in the playbook, and several also have a codemod the agent runs first for the mechanical rewrites, so its own effort goes to the judgment calls. A site built with anything else still migrates: run the command without a source, and the agent inventories the repo first, then works from the playbook's general rules.
 
 ## What the agent does
 
@@ -39,7 +51,7 @@ The agent follows the playbook's workflow from the source's config to a passing
 1. Writes `blume.config.ts`, mapping only what your source declares and leaving Blume's defaults to cover the rest.
 2. Restructures content into [filesystem navigation](/docs/content/navigation), converting per-folder ordering files (Fumadocs `meta.json`, Nextra `_meta`) to `meta.ts`.
 3. Rewrites pages: frontmatter to Blume's schema, callout components to [directives](/docs/content/syntax), icons to Lucide, and snippets inlined.
-4. Adds a [redirect](/docs/deployment#redirects) for every URL that moves, so no link breaks.
+4. Adds a [redirect](/docs/deployment#redirects) for every URL that moves, so no link breaks. Docsify's `#/` URLs never reach the server, so for those it adds a small script that sends each one to its new page. A GitHub wiki's URLs stay on github.com, which can't redirect, so the agent maps each page to its new route and prepares link stubs you can push to the old wiki.
 5. Points your `package.json` scripts at `blume dev` and `blume build`, and swaps the old framework's dependencies for `blume`.
 6. Runs `blume build` and `blume validate` until both pass.