blume 0.6.7 → 0.8.0

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

@@ -0,0 +1,34 @@
+/** Evaluated props plus whether any attribute resisted static evaluation. */
+interface EvaluatedProps {
+    lossy: boolean;
+    props: Record<string, unknown>;
+}
+/** A child component extracted by name (e.g. each `<Step>` under `<Steps>`). */
+export interface ComponentMarkdownChild extends EvaluatedProps {
+    /** The child's body, downleveled and dedented. */
+    children: string;
+}
+/** What a serializer receives for one component usage. */
+export interface ComponentMarkdownContext extends EvaluatedProps {
+    /** Direct child components of `name`, each with evaluated props and body. */
+    childComponents: (name: string) => ComponentMarkdownChild[];
+    /** The element's body, downleveled and dedented (empty if self-closing). */
+    children: string;
+}
+/**
+ * A component's Markdown serializer. Return the replacement Markdown, or
+ * `null` to leave the component's JSX in the output verbatim (the safe
+ * fallback when the props can't be recovered statically).
+ */
+export type ComponentMarkdown = (context: ComponentMarkdownContext) => string | null;
+/**
+ * Downlevel supported components in an MDX source to plain Markdown. Sources
+ * with no supported components — and sources Satteri can't parse as MDX, e.g.
+ * plain `.md` with literal `<`/`{` — are returned byte-identical.
+ *
+ * `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.
+ */
+export declare const downlevelComponents: (source: string, components?: Record<string, ComponentMarkdown>) => string;
+export {};

package/dist/types/components/content/youtube.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Helpers for the `<YouTube>` content component. Kept in a sibling `.ts` (like
+ * `diff.ts`/`github-info.ts`) so the id parsing and embed-URL building are pure,
+ * unit-testable functions — the `.astro` file stays a thin presentational shell.
+ */
+/**
+ * Resolve a YouTube video id from either a bare id or a full URL. Returns `null`
+ * when nothing that looks like an id can be found, so the component can render
+ * nothing rather than a broken embed.
+ */
+export declare const parseYouTubeId: (input: string) => string | null;
+/**
+ * Build a privacy-enhanced (`youtube-nocookie.com`) embed URL, optionally
+ * starting at `start` seconds.
+ */
+export declare const youtubeEmbedUrl: (id: string, options?: {
+    start?: number;
+}) => string;

package/dist/types/core/base-path.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The site-wide `basePath` — a mount point that prepends a segment to every
+ * generated route (`/docs/getting-started`) while staying invisible to the
+ * navigation tree (see `core/navigation.ts`, which builds groups from a page's
+ * base-less `navPath` and takes URLs from its based `route`). This is distinct
+ * from a per-source `prefix` (a namespace that *does* create a sidebar group)
+ * and from `deployment.base` (Astro's host-subdirectory base); the two compose,
+ * stacking as `{deployment.base}/{basePath}/page`.
+ *
+ * These helpers run server-side (config, route construction, the link checker,
+ * redirects, the markdown link plugin). The client-side counterpart lives in
+ * `components/islands/base-path.ts` and serves `deployment.base` via `BASE_URL`.
+ */
+/**
+ * Canonicalize a configured base path to either `""` (none) or `/seg[/seg…]`
+ * (leading slash, no trailing slash, collapsed inner slashes). A blank value or
+ * bare `/` normalizes to `""`, so an unset/`"/"` base is a clean no-op.
+ */
+export declare const normalizeBasePath: (input?: string) => string;
+/**
+ * Whether a link target is a root-relative internal path (`/x`) — the only
+ * shape a base path applies to. Protocol-relative (`//host`), absolute URLs,
+ * other schemes (`mailto:`), fragments (`#x`), and relative paths are excluded.
+ */
+export declare const isInternalPath: (target: string) => boolean;
+/**
+ * Idempotently prepend `basePath` to a root-relative route. A route already
+ * equal to or nested under the base is returned unchanged, so authors who write
+ * the base by hand (`/docs/x`) aren't double-prefixed to `/docs/docs/x`.
+ */
+export declare const withBasePath: (basePath: string, route: string) => string;
+/**
+ * {@link withBasePath} for the composed `deployment.base` + `basePath` stack
+ * (`/base` + `/docs` serves pages at `/base/docs/x`). The hand-written-base
+ * promise applies per layer: authors write `basePath` by hand (see
+ * `markdown/base-links.ts`), so a `/docs/x` link gains only the deployment base
+ * (`/base/docs/x`) rather than being double-prefixed to `/base/docs/docs/x`,
+ * and a route already under the full composite is returned unchanged.
+ */
+export declare const withComposedBasePath: (deployBase: string, basePath: string, route: string) => string;
+/**
+ * Remove `basePath` from the front of a route (`/docs/guide` -> `/guide`,
+ * `/docs` -> `/`). A route not under the base is returned unchanged. Inverse of
+ * {@link withBasePath}; used to resolve public assets, which live at the site
+ * root regardless of the base.
+ */
+export declare const stripBasePath: (basePath: string, route: string) => string;

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

@@ -1,3 +1,4 @@
+import type { ComponentMarkdown } from "../ai/component-markdown.ts";
 import type { FontSlug } from "../theme/fonts.ts";
 import type { OpenApiSource, SearchProvider, SidebarDisplay, SidebarItemConfig } from "./schema.ts";
 import type { ContentSource } from "./sources/types.ts";
@@ -264,11 +265,15 @@ 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;
 }
@@ -323,6 +328,10 @@ export interface FontsConfig {
     mono?: LiteralUnion<FontSlug>;
 }
 /** 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
@@ -346,7 +355,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;
 }
 /** Public credentials for the Algolia backend (the sync key stays an env var). */
 export interface AlgoliaSearch {
@@ -403,6 +412,9 @@ export interface AskSuggestion {
     label: string;
 }
 /** 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
@@ -419,16 +431,49 @@ 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>;
 }
 /** An arbitrary analytics `<script>`; set exactly one of `src` or `content`. */
 export interface AnalyticsScript {
@@ -501,9 +546,12 @@ 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`. */
@@ -514,12 +562,16 @@ 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;
 }
@@ -594,7 +646,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?: {
@@ -612,6 +667,15 @@ export interface MarkdownConfig {
     /** Make content images click-to-zoom (lightbox). Defaults to `true`. */
     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 reference. By default (`renderer: "blume"`) Blume renders its own UI:
  * one real page per operation, grouped by tag in the sidebar and included in
@@ -653,6 +717,24 @@ export interface AsyncApiConfig {
     /** Scalar theme name. */
     theme?: string;
 }
+/** `<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`.
@@ -696,6 +778,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). */
@@ -703,11 +795,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`. */
@@ -728,6 +824,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/dist/types/core/config.d.ts

@@ -65,8 +65,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**
@@ -83,8 +84,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

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

@@ -87,6 +87,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;