blume 0.7.0 → 1.0.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

@@ -29,6 +29,15 @@ export declare const isInternalPath: (target: string) => boolean;
  * 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

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";
@@ -434,12 +435,45 @@ export interface AskConfig {
     /** 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 {
@@ -589,6 +623,17 @@ export interface SeoConfig {
     sitemap?: boolean;
     /** Emit schema.org JSON-LD in each page's `<head>`. Defaults to `true`. */
     structuredData?: boolean;
+    /**
+     * X (Twitter) attribution for share cards. Handles may omit the `@`. The rest
+     * of the X card is read from the `og:*` tags, so these accounts are the only
+     * values X cannot infer.
+     */
+    x?: {
+        /** Author account (`twitter:creator`); a page can override it via `seo.x.creator` frontmatter. */
+        creator?: string;
+        /** The site's own account (`twitter:site`), e.g. `@blume`. */
+        handle?: string;
+    };
 }
 /** Source repository, powering "Edit this page" links and the header repo link. */
 export interface GithubConfig {

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**

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

@@ -87,6 +87,8 @@ 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. */
@@ -120,6 +122,11 @@ export interface BlumeDataConfig {
     title: string;
     /** Table-of-contents settings: whether to show it and the heading range. */
     toc: ResolvedConfig["toc"];
+    /** X (Twitter) attribution: the site's account, and a default creator. */
+    x: {
+        creator?: string;
+        handle?: string;
+    };
 }
 /**
  * The compact snapshot the layout serializes into the page for React island