blume 0.5.4 → 0.6.1

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

@@ -1,8 +1,131 @@
-import type { BlumeConfig, ResolvedConfig } from "./schema.ts";
+import type { BlumeConfig } from "./config-input.ts";
+import type { ResolvedConfig } from "./schema.ts";
 import type { Diagnostic } from "./types.ts";
 /**
- * Identity helper for authoring `blume.config.ts`. Exists for type inference
- * and a stable future home for plugin hooks; it does not transform input.
+ * Define a Blume site's configuration with full type-checking and editor
+ * autocomplete. Place the call in `blume.config.ts` at your project root and
+ * `export default` the result:
+ *
+ * ```ts
+ * import { defineConfig } from "blume";
+ *
+ * export default defineConfig({
+ *   title: "Acme Docs",
+ *   description: "Everything you need to build with Acme.",
+ * });
+ * ```
+ *
+ * Every field is optional — an empty `defineConfig({})` produces a working
+ * site from the Markdown/MDX in your `docs/` directory. Configure only what you
+ * want to change; sensible defaults fill in the rest.
+ *
+ * This is an identity helper: it returns its input unchanged and exists purely
+ * for type inference (and as a stable home for future plugin hooks). The object
+ * is validated against the Blume schema when the CLI loads it.
+ *
+ * ## Top-level fields
+ *
+ * **Site identity**
+ * - `title` — site title, shown in the header, `<title>`, and OG images.
+ *   Defaults to `"Documentation"`.
+ * - `description` — default meta description, used where a page sets none.
+ * - `logo` — brand mark. A string is an image path/URL; the object form splits
+ *   an `image` mark from wordmark `text` and can override the brand `href`.
+ * - `banner` — site-wide announcement bar; a string, or `{ content, link,
+ *   dismissible }`.
+ *
+ * **Content & navigation**
+ * - `content` — where content lives (`root`, defaults to `docs`) and pluggable
+ *   `sources` (filesystem, remote MDX, GitHub Releases, Sanity, Notion, or a
+ *   custom `ContentSource`). Omit `sources` and the top-level `root` becomes one
+ *   implicit filesystem source.
+ * - `navigation` — sidebar, header `tabs`, `selectors` (version/language/product
+ *   switchers), pinned `featured` links, and the `repo` link toggle. Omit
+ *   `sidebar` to generate it from the content tree.
+ * - `redirects` — `{ from, to, status }` rules (301 by default).
+ * - `github` — `{ owner, repo, branch, dir }`, powering "Edit this page" links
+ *   and the header repo link.
+ *
+ * **Appearance**
+ * - `theme` — `accent` color, `fonts` (curated Google Font slugs), `radius`,
+ *   `mode` (`system`/`light`/`dark`), `background`, and `strict` token mode.
+ * - `markdown` — `code` (language icons, inline highlighting, line wrap),
+ *   `headingAnchors`, `imageZoom`, and opt-in KaTeX `math`.
+ * - `toc` — on-page table of contents; `true`/`false` or a heading-level range.
+ * - `lastModified` — "Last updated" stamps from `git` history or frontmatter.
+ * - `feedback` — the per-page "Was this helpful?" widget (on by default).
+ * - `export` — reader-facing PDF/EPUB export actions (off by default).
+ *
+ * **Reference docs**
+ * - `openapi` — native OpenAPI reference: one real page per operation, woven
+ *   into the sidebar and search. Point `sources`/`spec` at your spec.
+ * - `asyncapi` — AsyncAPI reference via the embedded Scalar renderer.
+ *
+ * **Search & AI**
+ * - `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`).
+ * - `mcp` — expose the docs as an MCP server for connecting agents.
+ *
+ * **SEO, feeds & analytics**
+ * - `seo` — `og` images, `sitemap`, `robots`, `rss` feeds, `structuredData`
+ *   JSON-LD, `agentReadability`, and robots `contentSignals`.
+ * - `analytics` — PostHog, Vercel, or arbitrary `scripts` (Plausible, Fathom,
+ *   GA, …).
+ *
+ * **Deployment & i18n**
+ * - `deployment` — `site` URL (needed for absolute links, sitemaps, and OG),
+ *   `adapter` (`vercel`/`node`/`netlify`/`cloudflare`), `output`
+ *   (`static`/`server`), and `base` path. Auto-detected on Vercel/Netlify/
+ *   Cloudflare from the platform env.
+ * - `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).
+ *
+ * @example Zero-config — just render the Markdown under `docs/`.
+ * ```ts
+ * export default defineConfig({});
+ * ```
+ *
+ * @example A production docs site with theming, search, and deployment.
+ * ```ts
+ * export default defineConfig({
+ *   title: "Acme Docs",
+ *   description: "Build faster with Acme.",
+ *   logo: { image: "/logo.svg", text: "Acme" },
+ *   github: { owner: "acme", repo: "acme" },
+ *   theme: { accent: "violet", fonts: { body: "inter" }, radius: "lg" },
+ *   navigation: {
+ *     tabs: [
+ *       { label: "Guides", path: "/guides" },
+ *       { label: "API", path: "/api" },
+ *     ],
+ *   },
+ *   search: { provider: "orama" },
+ *   deployment: { site: "https://docs.acme.com", adapter: "vercel" },
+ * });
+ * ```
+ *
+ * @example An OpenAPI reference with the Ask AI assistant enabled.
+ * ```ts
+ * export default defineConfig({
+ *   title: "Acme API",
+ *   openapi: {
+ *     enabled: true,
+ *     route: "/reference",
+ *     sources: [{ label: "Core", spec: "./openapi.json" }],
+ *   },
+ *   ai: { ask: { enabled: true }, llmsTxt: true },
+ * });
+ * ```
+ *
+ * @param config - The site configuration. All fields are optional.
+ * @returns The same config object, typed for inference.
+ * @see https://useblume.dev/docs for the full configuration reference.
  */
 export declare const defineConfig: (config: BlumeConfig) => BlumeConfig;
 /** Result of loading + validating a project config. */

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

@@ -82,6 +82,10 @@ export interface BlumeDataConfig {
     analytics: NonNullable<ResolvedConfig["analytics"]> | null;
     /** Apple touch icon, or `null` when none is configured/detected. */
     appleIcon: BlumeFavicon | null;
+    /** Ask AI empty-state suggestions, or `null` when Ask AI is off. */
+    ask: {
+        suggestions: NonNullable<ResolvedConfig["ai"]["ask"]>["suggestions"];
+    } | null;
     banner: BlumeBanner | null;
     /** `markdown.code.wrap`: wrap long code lines instead of scrolling. */
     codeWrap: boolean;

package/dist/types/core/i18n-ui.d.ts

@@ -16,6 +16,7 @@ declare const uiStringsObject: z.ZodObject<{
         connectMcp: z.ZodDefault<z.ZodString>;
         copied: z.ZodDefault<z.ZodString>;
         copyClaudeCode: z.ZodDefault<z.ZodString>;
+        copyCodex: z.ZodDefault<z.ZodString>;
         copyMarkdown: z.ZodDefault<z.ZodString>;
         copyServerUrl: z.ZodDefault<z.ZodString>;
         edit: z.ZodDefault<z.ZodString>;
@@ -33,6 +34,7 @@ declare const uiStringsObject: z.ZodObject<{
         edit: string;
         openInChat: string;
         scrollToTop: string;
+        copyCodex: string;
     }, {
         addToCursor?: string | undefined;
         addToVscode?: string | undefined;
@@ -45,13 +47,18 @@ declare const uiStringsObject: z.ZodObject<{
         edit?: string | undefined;
         openInChat?: string | undefined;
         scrollToTop?: string | undefined;
+        copyCodex?: string | undefined;
     }>>;
     ask: z.ZodDefault<z.ZodObject<{
+        clear: z.ZodDefault<z.ZodString>;
+        close: z.ZodDefault<z.ZodString>;
+        copy: z.ZodDefault<z.ZodString>;
         empty: z.ZodDefault<z.ZodString>;
         error: z.ZodDefault<z.ZodString>;
         label: z.ZodDefault<z.ZodString>;
         placeholder: z.ZodDefault<z.ZodString>;
         send: z.ZodDefault<z.ZodString>;
+        tip: z.ZodDefault<z.ZodString>;
         title: z.ZodDefault<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         empty: string;
@@ -60,6 +67,10 @@ declare const uiStringsObject: z.ZodObject<{
         placeholder: string;
         send: string;
         title: string;
+        clear: string;
+        close: string;
+        copy: string;
+        tip: string;
     }, {
         empty?: string | undefined;
         error?: string | undefined;
@@ -67,6 +78,10 @@ declare const uiStringsObject: z.ZodObject<{
         placeholder?: string | undefined;
         send?: string | undefined;
         title?: string | undefined;
+        clear?: string | undefined;
+        close?: string | undefined;
+        copy?: string | undefined;
+        tip?: string | undefined;
     }>>;
     feedback: z.ZodDefault<z.ZodObject<{
         no: z.ZodDefault<z.ZodString>;
@@ -165,6 +180,7 @@ declare const uiStringsObject: z.ZodObject<{
         edit: string;
         openInChat: string;
         scrollToTop: string;
+        copyCodex: string;
     };
     ask: {
         empty: string;
@@ -173,6 +189,10 @@ declare const uiStringsObject: z.ZodObject<{
         placeholder: string;
         send: string;
         title: string;
+        clear: string;
+        close: string;
+        copy: string;
+        tip: string;
     };
     feedback: {
         no: string;
@@ -219,6 +239,7 @@ declare const uiStringsObject: z.ZodObject<{
         edit?: string | undefined;
         openInChat?: string | undefined;
         scrollToTop?: string | undefined;
+        copyCodex?: string | undefined;
     } | undefined;
     ask?: {
         empty?: string | undefined;
@@ -227,6 +248,10 @@ declare const uiStringsObject: z.ZodObject<{
         placeholder?: string | undefined;
         send?: string | undefined;
         title?: string | undefined;
+        clear?: string | undefined;
+        close?: string | undefined;
+        copy?: string | undefined;
+        tip?: string | undefined;
     } | undefined;
     feedback?: {
         no?: string | undefined;
@@ -269,6 +294,7 @@ export declare const uiStringsSchema: z.ZodDefault<z.ZodObject<{
         connectMcp: z.ZodDefault<z.ZodString>;
         copied: z.ZodDefault<z.ZodString>;
         copyClaudeCode: z.ZodDefault<z.ZodString>;
+        copyCodex: z.ZodDefault<z.ZodString>;
         copyMarkdown: z.ZodDefault<z.ZodString>;
         copyServerUrl: z.ZodDefault<z.ZodString>;
         edit: z.ZodDefault<z.ZodString>;
@@ -286,6 +312,7 @@ export declare const uiStringsSchema: z.ZodDefault<z.ZodObject<{
         edit: string;
         openInChat: string;
         scrollToTop: string;
+        copyCodex: string;
     }, {
         addToCursor?: string | undefined;
         addToVscode?: string | undefined;
@@ -298,13 +325,18 @@ export declare const uiStringsSchema: z.ZodDefault<z.ZodObject<{
         edit?: string | undefined;
         openInChat?: string | undefined;
         scrollToTop?: string | undefined;
+        copyCodex?: string | undefined;
     }>>;
     ask: z.ZodDefault<z.ZodObject<{
+        clear: z.ZodDefault<z.ZodString>;
+        close: z.ZodDefault<z.ZodString>;
+        copy: z.ZodDefault<z.ZodString>;
         empty: z.ZodDefault<z.ZodString>;
         error: z.ZodDefault<z.ZodString>;
         label: z.ZodDefault<z.ZodString>;
         placeholder: z.ZodDefault<z.ZodString>;
         send: z.ZodDefault<z.ZodString>;
+        tip: z.ZodDefault<z.ZodString>;
         title: z.ZodDefault<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         empty: string;
@@ -313,6 +345,10 @@ export declare const uiStringsSchema: z.ZodDefault<z.ZodObject<{
         placeholder: string;
         send: string;
         title: string;
+        clear: string;
+        close: string;
+        copy: string;
+        tip: string;
     }, {
         empty?: string | undefined;
         error?: string | undefined;
@@ -320,6 +356,10 @@ export declare const uiStringsSchema: z.ZodDefault<z.ZodObject<{
         placeholder?: string | undefined;
         send?: string | undefined;
         title?: string | undefined;
+        clear?: string | undefined;
+        close?: string | undefined;
+        copy?: string | undefined;
+        tip?: string | undefined;
     }>>;
     feedback: z.ZodDefault<z.ZodObject<{
         no: z.ZodDefault<z.ZodString>;
@@ -418,6 +458,7 @@ export declare const uiStringsSchema: z.ZodDefault<z.ZodObject<{
         edit: string;
         openInChat: string;
         scrollToTop: string;
+        copyCodex: string;
     };
     ask: {
         empty: string;
@@ -426,6 +467,10 @@ export declare const uiStringsSchema: z.ZodDefault<z.ZodObject<{
         placeholder: string;
         send: string;
         title: string;
+        clear: string;
+        close: string;
+        copy: string;
+        tip: string;
     };
     feedback: {
         no: string;
@@ -472,6 +517,7 @@ export declare const uiStringsSchema: z.ZodDefault<z.ZodObject<{
         edit?: string | undefined;
         openInChat?: string | undefined;
         scrollToTop?: string | undefined;
+        copyCodex?: string | undefined;
     } | undefined;
     ask?: {
         empty?: string | undefined;
@@ -480,6 +526,10 @@ export declare const uiStringsSchema: z.ZodDefault<z.ZodObject<{
         placeholder?: string | undefined;
         send?: string | undefined;
         title?: string | undefined;
+        clear?: string | undefined;
+        close?: string | undefined;
+        copy?: string | undefined;
+        tip?: string | undefined;
     } | undefined;
     feedback?: {
         no?: string | undefined;