blume 0.6.7 → 0.8.0

package/src/core/config-input.ts

@@ -1,5 +1,6 @@
 import type { z } from "zod";
 
+import type { ComponentMarkdown } from "../ai/component-markdown.ts";
 import type { FontSlug } from "../theme/fonts.ts";
 import type {
   blumeConfigSchema,
@@ -315,11 +316,16 @@ export interface NavSelectorItem {
  * A header dropdown for switching context — versions, languages, products, or a
  * generic dropdown. `kind` drives the icon and a11y labeling.
  */
+/** Context-partition selector kinds (a versioned/localized/multi-product site). */
+type NavSelectorContextKind = "product" | "version";
+/** What a header selector switches between. */
+type NavSelectorKind = "dropdown" | "language" | NavSelectorContextKind;
+
 export interface NavSelector {
   /** The options shown in the dropdown. */
   items?: NavSelectorItem[];
   /** What the selector switches between. */
-  kind: "dropdown" | "language" | "product" | "version";
+  kind: NavSelectorKind;
   /** Selector label / current value. */
   label: string;
 }
@@ -385,6 +391,11 @@ export interface FontsConfig {
 }
 
 /** Colors, fonts, radius, and color-mode behavior. */
+/** Corner radius scale (`none`/`sm` tighter, `md`/`lg` rounder). */
+type RadiusScaleTight = "none" | "sm";
+type RadiusScaleRound = "md" | "lg";
+type RadiusScale = RadiusScaleTight | RadiusScaleRound;
+
 export interface ThemeConfig {
   /**
    * Accent color. A palette name (`blue`, `violet`, `green`, …) or any CSS
@@ -405,7 +416,7 @@ export interface ThemeConfig {
   /** Initial color mode. Defaults to `system`. */
   mode?: "system" | "light" | "dark";
   /** Corner radius scale. Defaults to `md`. */
-  radius?: "none" | "sm" | "md" | "lg";
+  radius?: RadiusScale;
 }
 
 // ---------------------------------------------------------------------------
@@ -477,6 +488,10 @@ export interface AskSuggestion {
 }
 
 /** The Ask AI chat assistant. */
+/** Backends that can route an Ask AI request. */
+type AskProviderGateway = "gateway" | "openrouter" | "llmgateway";
+type AskProvider = AskProviderGateway | "inkeep" | "openai-compatible";
+
 export interface AskConfig {
   /**
    * Name of the env var holding the provider API key. Each provider has a
@@ -493,22 +508,51 @@ export interface AskConfig {
   /** Model id to use. Defaults to `openai/gpt-5.5`. */
   model?: string;
   /** Which backend routes the request. Defaults to `gateway`. */
-  provider?:
-    | "gateway"
-    | "openrouter"
-    | "llmgateway"
-    | "inkeep"
-    | "openai-compatible";
+  provider?: AskProvider;
   /** Starter prompts shown before the first question. */
   suggestions?: AskSuggestion[];
 }
 
+/** What the `llms.txt`/`llms-full.txt` files include. */
+export interface LlmsTxtConfig {
+  /** Emit `llms.txt` and `llms-full.txt`. Defaults to `true`. */
+  enabled?: boolean;
+  /**
+   * Include the generated API reference pages (OpenAPI/AsyncAPI). Defaults to
+   * `true`; set `false` to keep a placeholder or example spec's pages out of
+   * the LLM-facing files.
+   */
+  openapi?: boolean;
+}
+
 /** AI-facing features: the Ask AI assistant and an `llms.txt` manifest. */
 export interface AiConfig {
   /** The Ask AI chat assistant. */
   ask?: AskConfig;
-  /** Emit `llms.txt` (an index of the docs for LLMs). Defaults to `true`. */
-  llmsTxt?: boolean;
+  /**
+   * Emit `llms.txt` (an index of the docs for LLMs). Defaults to `true`.
+   * The object form adds knobs for what the files include.
+   */
+  llmsTxt?: boolean | LlmsTxtConfig;
+  /**
+   * 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.
+   *
+   * These live in `blume.config.ts` (which is executed at build time), not in
+   * `components.tsx` (which is only statically analyzed, never run).
+   *
+   * ```ts
+   * ai: {
+   *   markdownComponents: {
+   *     Chart: ({ props }) => `![${props.title}](/charts/${props.slug}.png)`,
+   *   },
+   * }
+   * ```
+   */
+  markdownComponents?: Record<string, ComponentMarkdown>;
 }
 
 // ---------------------------------------------------------------------------
@@ -603,9 +647,13 @@ export interface I18nConfig {
  * Where and how the site deploys. `site` (and `adapter`) are auto-detected from
  * the platform env on Vercel, Netlify, and Cloudflare.
  */
+/** Astro server-output adapters, by hosting platform. */
+type CloudDeploymentAdapter = "netlify" | "cloudflare";
+type DeploymentAdapter = "vercel" | "node" | CloudDeploymentAdapter;
+
 export interface DeploymentConfig {
   /** Astro adapter for server output. `null` (default) keeps a static build. */
-  adapter?: "vercel" | "node" | "netlify" | "cloudflare" | null;
+  adapter?: DeploymentAdapter | null;
   /** Base path when the site is served from a subdirectory. */
   base?: string;
   /** Build output mode. Defaults to `static`. */
@@ -617,12 +665,17 @@ export interface DeploymentConfig {
   site?: string;
 }
 
+/** HTTP redirect status codes: permanent (301/308) and temporary (302/307). */
+type RedirectStatusPermanent = 301 | 308;
+type RedirectStatusTemporary = 302 | 307;
+type RedirectStatus = RedirectStatusPermanent | RedirectStatusTemporary;
+
 /** A URL redirect rule. */
 export interface RedirectConfig {
   /** Path to redirect from. */
   from: string;
   /** HTTP status. Defaults to `301`. */
-  status?: 301 | 302 | 307 | 308;
+  status?: RedirectStatus;
   /** Path or URL to redirect to. */
   to: string;
 }
@@ -717,7 +770,10 @@ export interface CodeConfig {
 export interface MarkdownConfig {
   /** Code-block rendering: language icons, line wrap. */
   code?: CodeConfig;
-  /** Syntax-highlighting themes for fenced code blocks. */
+  /**
+   * Syntax-highlighting themes for every code surface — fenced blocks, inline
+   * `` `code`{:lang} ``, `<CodeBlock>`, and `<Diff>`.
+   */
   codeBlocks?: {
     /** Shiki theme names per color mode. */
     theme?: {
@@ -736,6 +792,16 @@ export interface MarkdownConfig {
   imageZoom?: boolean;
 }
 
+/** React island behavior. */
+export interface ReactConfig {
+  /**
+   * Auto-memoize React components/hooks with the React Compiler
+   * (`babel-plugin-react-compiler`). On by default whenever React is enabled;
+   * set to `false` to skip the compiler's babel pass. Defaults to `true`.
+   */
+  compiler?: boolean;
+}
+
 // ---------------------------------------------------------------------------
 // OpenAPI / AsyncAPI
 // ---------------------------------------------------------------------------
@@ -787,6 +853,25 @@ export interface AsyncApiConfig {
 // Misc top-level unions
 // ---------------------------------------------------------------------------
 
+/** `<Component />` example previews (the object form of `examples`). */
+export interface ExamplesConfig {
+  /**
+   * A stylesheet, relative to the project root, injected into every preview
+   * frame after Blume's default tokens. Previews render inside an isolated
+   * iframe the docs styles never reach, so design tokens for the previewed
+   * components — shadcn variables, `@theme` mappings, custom fonts — live
+   * here. Tailwind is already provided in the frame; the file should hold
+   * tokens and styles, not another `@import "tailwindcss"`.
+   */
+  css?: string;
+  /**
+   * Where example files live, relative to the project root. Defaults to
+   * `examples`; may be a glob to target a registry that colocates component
+   * sources with their examples (e.g. `registry/<pkg>/**\/examples/*`).
+   */
+  source?: string;
+}
+
 /**
  * Reader-facing "Export" page actions. A boolean toggles both formats; the
  * object form enables each individually. Defaults to `false`.
@@ -843,6 +928,16 @@ export interface BlumeConfig {
   asyncapi?: AsyncApiConfig;
   /** Site-wide announcement banner shown above the header. */
   banner?: BannerConfig;
+  /**
+   * Site-wide mount point prepended to every generated route (e.g. `/docs`) —
+   * pages, links, redirects, sitemap, OG images, `llms.txt`, and the search
+   * index — while staying invisible to the sidebar/nav tree (no wrapper group).
+   * Distinct from a per-source `prefix` (which namespaces one source *and*
+   * creates a group) and from `deployment.base` (Astro's host-subdirectory
+   * base, for serving the whole site — root included — from a subpath). The two
+   * compose: with both set, a page lands at `{deployment.base}/{basePath}/page`.
+   */
+  basePath?: string;
   /** Where content lives and how it's discovered. */
   content?: ContentConfig;
   /** Where and how the site deploys (site URL, adapter, output mode). */
@@ -850,11 +945,15 @@ export interface BlumeConfig {
   /** Default meta description, used where a page sets none. */
   description?: string;
   /**
-   * Where `<Component path>` resolves live previews and their source from,
-   * relative to the project root. Defaults to `examples`. May be a glob to
-   * target a registry that colocates component sources with their examples.
+   * `<Component path>` example previews. A string is shorthand for
+   * `{ source }`: where examples live, relative to the project root (defaults
+   * to `examples`; may be a glob to target a registry that colocates
+   * component sources with their examples). The object form adds `css` — a
+   * stylesheet injected into every preview frame (previews render in an
+   * iframe the docs theme never reaches), for the previewed components'
+   * design tokens, e.g. shadcn variables.
    */
-  examples?: string;
+  examples?: string | ExamplesConfig;
   /** Reader-facing PDF/EPUB export actions. Defaults to `false`. */
   export?: ExportConfig;
   /** Show the per-page "Was this helpful?" widget. Defaults to `true`. */
@@ -875,6 +974,8 @@ export interface BlumeConfig {
   navigation?: NavigationConfig;
   /** Native OpenAPI reference. */
   openapi?: OpenApiConfig;
+  /** React island behavior (compiler auto-memoization). */
+  react?: ReactConfig;
   /** URL redirect rules. */
   redirects?: RedirectConfig[];
   /** Search backend and credentials. */

package/src/core/config.ts

@@ -73,8 +73,9 @@ import type { Diagnostic } from "./types.ts";
  * - `search` — search backend `provider` (`orama` by default; `pagefind`,
  *   `algolia`, `typesense`, `orama-cloud`, `mixedbread`, or `none`) plus its
  *   credential block.
- * - `ai` — `ask` (the Ask AI chat endpoint and its provider/model) and `llmsTxt`
- *   (emit `llms.txt`).
+ * - `ai` — `ask` (the Ask AI chat endpoint and its provider/model), `llmsTxt`
+ *   (emit `llms.txt`), and `markdownComponents` (Markdown serializers for
+ *   custom components in agent-facing output).
  * - `mcp` — expose the docs as an MCP server for connecting agents.
  *
  * **SEO, feeds & analytics**
@@ -91,8 +92,9 @@ import type { Diagnostic } from "./types.ts";
  * - `i18n` — opt-in multi-locale: `locales`, `defaultLocale`, `parser`
  *   (`dir` vs filename `dot` suffix), and per-locale UI overrides.
  *
- * - `examples` — where `<Component path>` previews resolve their source from
- *   (defaults to `examples/`; supports a glob for colocated registries).
+ * - `examples` — `<Component path>` previews: `source` (default `examples/`;
+ *   supports a glob for colocated registries) and `css`, a stylesheet injected
+ *   into the isolated preview frames (e.g. shadcn variables).
  *
  * @example Zero-config — just render the Markdown under `docs/`.
  * ```ts
@@ -197,11 +199,12 @@ export const loadConfig = async (
     };
     // Surface every issue in one failing run — reporting only the first turns
     // a three-mistake config into three fix-rerun-fail loops.
+    const moreIssues = rest.map((d) => `  - ${d.message}`).join("\n");
     throw new BlumeError(
       rest.length > 0
         ? {
             ...primary,
-            message: `${primary.message}\n${rest.length} more config issue(s):\n${rest.map((d) => `  - ${d.message}`).join("\n")}`,
+            message: `${primary.message}\n${rest.length} more config issue(s):\n${moreIssues}`,
           }
         : primary
     );

package/src/core/content.ts

@@ -22,6 +22,7 @@ export const discoverContent = async (options: {
   include: string[];
   exclude: string[];
   defaultType: string;
+  basePath?: string;
   i18n?: ResolvedI18nConfig;
 }): Promise<{ pages: PageRecord[]; diagnostics: Diagnostic[] }> => {
   const source = filesystemSource({
@@ -38,6 +39,7 @@ export const discoverContent = async (options: {
 
   for (const entry of entries) {
     const normalized = normalizeEntry(entry, {
+      basePath: options.basePath ?? "",
       defaultType: options.defaultType,
       i18n: options.i18n,
       source: { name: source.name, prefix: source.prefix, staged: false },

package/src/core/data.ts

@@ -93,6 +93,10 @@ export interface BlumeDataConfig {
     suggestions: NonNullable<ResolvedConfig["ai"]["ask"]>["suggestions"];
   } | null;
   banner: BlumeBanner | null;
+  /** Site-wide route mount point, normalized to `""` or `/seg` (see config). */
+  basePath: string;
+  /** `markdown.codeBlocks.theme`: light/dark Shiki themes for code surfaces. */
+  codeThemes: ResolvedConfig["markdown"]["codeBlocks"]["theme"];
   /** `markdown.code.wrap`: wrap long code lines instead of scrolling. */
   codeWrap: boolean;
   description: string | undefined;

package/src/core/diagnostics.ts

@@ -20,35 +20,40 @@ export const createDiagnostic = (diagnostic: Diagnostic): Diagnostic =>
 /** Docs site base; diagnostic help links resolve against it. */
 const DOCS_BASE = "https://useblume.dev";
 
+const DOCS_DEPLOYMENT = "/docs/deployment";
+const DOCS_REFERENCE_CLI = "/docs/reference/cli";
+const DOCS_CONTENT_SOURCES = "/docs/content/sources";
+const DOCS_CONTENT_NAVIGATION = "/docs/content/navigation";
+
 /** Diagnostic code → the docs page that explains it. */
 const DOCS_PATHS: Record<string, string> = {
-  BLUME_ADAPTER_REQUIRED: "/docs/deployment",
-  BLUME_ASSETS_UNCHECKED: "/docs/reference/cli",
-  BLUME_ASSET_FETCH_FAILED: "/docs/content/sources",
-  BLUME_BROKEN_ANCHOR: "/docs/reference/cli",
-  BLUME_BROKEN_ASSET: "/docs/reference/cli",
-  BLUME_BROKEN_LINK: "/docs/reference/cli",
+  BLUME_ADAPTER_REQUIRED: DOCS_DEPLOYMENT,
+  BLUME_ASSETS_UNCHECKED: DOCS_REFERENCE_CLI,
+  BLUME_ASSET_FETCH_FAILED: DOCS_CONTENT_SOURCES,
+  BLUME_BROKEN_ANCHOR: DOCS_REFERENCE_CLI,
+  BLUME_BROKEN_ASSET: DOCS_REFERENCE_CLI,
+  BLUME_BROKEN_LINK: DOCS_REFERENCE_CLI,
   BLUME_CONFIG_INVALID: "/docs/configuration",
   BLUME_CONFIG_LOAD_FAILED: "/docs/configuration",
-  BLUME_CONTENT_ROOT_MISSING: "/docs/content/sources",
-  BLUME_DEAD_LINK: "/docs/reference/cli",
-  BLUME_DUPLICATE_ROUTE: "/docs/content/navigation",
+  BLUME_CONTENT_ROOT_MISSING: DOCS_CONTENT_SOURCES,
+  BLUME_DEAD_LINK: DOCS_REFERENCE_CLI,
+  BLUME_DUPLICATE_ROUTE: DOCS_CONTENT_NAVIGATION,
   BLUME_FRONTMATTER_INVALID: "/docs/reference/frontmatter",
   BLUME_META_INVALID: "/docs/content/meta",
   BLUME_META_LOAD_FAILED: "/docs/content/meta",
-  BLUME_MISSING_SECRET: "/docs/deployment",
-  BLUME_NAV_DUPLICATE_LABEL: "/docs/content/navigation",
-  BLUME_NAV_HIDDEN_IN_SIDEBAR: "/docs/content/navigation",
-  BLUME_NAV_MISSING_PAGE: "/docs/content/navigation",
+  BLUME_MISSING_SECRET: DOCS_DEPLOYMENT,
+  BLUME_NAV_DUPLICATE_LABEL: DOCS_CONTENT_NAVIGATION,
+  BLUME_NAV_HIDDEN_IN_SIDEBAR: DOCS_CONTENT_NAVIGATION,
+  BLUME_NAV_MISSING_PAGE: DOCS_CONTENT_NAVIGATION,
   BLUME_NODE_VERSION: "/docs/quickstart",
-  BLUME_SERVER_FEATURE_REQUIRED: "/docs/deployment",
-  BLUME_SOURCE_FETCH_FAILED: "/docs/content/sources",
-  BLUME_SOURCE_MISCONFIGURED: "/docs/content/sources",
-  BLUME_SOURCE_OFFLINE: "/docs/content/sources",
-  BLUME_SOURCE_SDK_MISSING: "/docs/content/sources",
-  BLUME_SOURCE_UNAVAILABLE: "/docs/content/sources",
+  BLUME_SERVER_FEATURE_REQUIRED: DOCS_DEPLOYMENT,
+  BLUME_SOURCE_FETCH_FAILED: DOCS_CONTENT_SOURCES,
+  BLUME_SOURCE_MISCONFIGURED: DOCS_CONTENT_SOURCES,
+  BLUME_SOURCE_OFFLINE: DOCS_CONTENT_SOURCES,
+  BLUME_SOURCE_SDK_MISSING: DOCS_CONTENT_SOURCES,
+  BLUME_SOURCE_UNAVAILABLE: DOCS_CONTENT_SOURCES,
   BLUME_UNKNOWN_COMPONENT: "/docs/configuration/customization",
-  BLUME_UNKNOWN_ICON: "/docs/content/navigation",
+  BLUME_UNKNOWN_ICON: DOCS_CONTENT_NAVIGATION,
 };
 
 /** The docs URL that explains a diagnostic code, if one is mapped. */
@@ -74,6 +79,29 @@ const escapeRegExp = (value: string): string =>
  * lands under its parent. Array indices are skipped. Returns 1-based line/column,
  * or undefined when nothing matches.
  */
+const stepSegment = (
+  source: string,
+  segment: string | number,
+  cursor: number
+): { index: number; next: number; stop: boolean } => {
+  // A non-string path segment (array index) is skipped without moving on.
+  if (typeof segment !== "string") {
+    return { index: -1, next: cursor, stop: false };
+  }
+  // The negative lookbehind keeps a segment like `title` from matching the
+  // tail of an unrelated key such as `subtitle:`.
+  const matcher = new RegExp(
+    `(?<![\\w$])${escapeRegExp(segment)}\\s*[:=]`,
+    "gu"
+  );
+  matcher.lastIndex = cursor;
+  const match = matcher.exec(source);
+  if (!match) {
+    return { index: -1, next: cursor, stop: true };
+  }
+  return { index: match.index, next: matcher.lastIndex, stop: false };
+};
+
 const locatePath = (
   source: string,
   path: readonly (string | number)[]
@@ -81,22 +109,14 @@ const locatePath = (
   let cursor = 0;
   let found = -1;
   for (const segment of path) {
-    if (typeof segment !== "string") {
-      continue;
-    }
-    // The negative lookbehind keeps a segment like `title` from matching the
-    // tail of an unrelated key such as `subtitle:`.
-    const matcher = new RegExp(
-      `(?<![\\w$])${escapeRegExp(segment)}\\s*[:=]`,
-      "gu"
-    );
-    matcher.lastIndex = cursor;
-    const match = matcher.exec(source);
-    if (!match) {
+    const step = stepSegment(source, segment, cursor);
+    if (step.stop) {
       break;
     }
-    found = match.index;
-    cursor = matcher.lastIndex;
+    cursor = step.next;
+    if (step.index >= 0) {
+      found = step.index;
+    }
   }
   if (found < 0) {
     return;

package/src/core/gitignore.ts

@@ -18,7 +18,10 @@ export const ensureGitignore = async (
   const path = join(root, ".gitignore");
   const existing = existsSync(path) ? await readFile(path, "utf-8") : "";
   const present = new Set(
-    existing.split("\n").map(gitignoreKey).filter(Boolean)
+    existing.split("\n").flatMap((line) => {
+      const key = gitignoreKey(line);
+      return key ? [key] : [];
+    })
   );
   const added = entries.filter((entry) => !present.has(gitignoreKey(entry)));
   if (added.length === 0) {