blume 0.5.4 → 0.6.1

package/src/core/config.ts

@@ -1,16 +1,139 @@
 import { existsSync, readFileSync } from "node:fs";
 
+import type { BlumeConfig } from "./config-input.ts";
 import { applyDeploymentEnv } from "./deployment-env.ts";
 import { BlumeError, diagnosticsFromZod } from "./diagnostics.ts";
 import { createModuleLoader } from "./load-module.ts";
 import { findConfigFile } from "./project.ts";
 import { blumeConfigSchema } from "./schema.ts";
-import type { BlumeConfig, ResolvedConfig } from "./schema.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 const defineConfig = (config: BlumeConfig): BlumeConfig => config;
 

package/src/core/data.ts

@@ -88,6 +88,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/src/core/graph.ts

@@ -89,6 +89,8 @@ export const buildContentGraph = (
       }
 
       navigationByLocale[code] = buildNavigation(localePages, {
+        display: options.navigation.sidebar.display,
+        featured: options.navigation.featured,
         folderMeta: options.folderMeta,
         // Meta files live in locale directories only under the `dir` parser
         // (`fr/guides/meta.ts` -> key `fr/guides`). Under `dot`, translations
@@ -99,21 +101,24 @@ export const buildContentGraph = (
         refByLogical: true,
         selectors: options.navigation.selectors,
         sharedFolderMeta: options.sharedFolderMeta,
-        sidebar: options.navigation.sidebar,
+        sidebar: options.navigation.sidebar.items,
         tabs,
       });
     }
     navigation = navigationByLocale[i18n.defaultLocale] ?? {
+      featured: [],
       selectors: [],
       sidebar: [],
       tabs: [],
     };
   } else {
     navigation = buildNavigation(pages, {
+      display: options.navigation.sidebar.display,
+      featured: options.navigation.featured,
       folderMeta: options.folderMeta,
       selectors: options.navigation.selectors,
       sharedFolderMeta: options.sharedFolderMeta,
-      sidebar: options.navigation.sidebar,
+      sidebar: options.navigation.sidebar.items,
       tabs: options.navigation.tabs,
     });
   }

package/src/core/i18n-ui.ts

@@ -19,6 +19,7 @@ const uiStringsObject = z.object({
       connectMcp: z.string().default("Connect to MCP"),
       copied: z.string().default("Copied!"),
       copyClaudeCode: z.string().default("Copy Claude Code command"),
+      copyCodex: z.string().default("Copy Codex command"),
       copyMarkdown: z.string().default("Copy as Markdown"),
       copyServerUrl: z.string().default("Copy server URL"),
       edit: z.string().default("Edit on GitHub"),
@@ -28,11 +29,15 @@ const uiStringsObject = z.object({
     .default({}),
   ask: z
     .object({
+      clear: z.string().default("Clear conversation"),
+      close: z.string().default("Close"),
+      copy: z.string().default("Copy conversation"),
       empty: z.string().default("Ask a question about the docs."),
       error: z.string().default("Sorry, something went wrong."),
       label: z.string().default("Ask a question"),
       placeholder: z.string().default("Ask a question…"),
       send: z.string().default("Send"),
+      tip: z.string().default("Tip: You can open and close chat with"),
       title: z.string().default("Ask AI"),
     })
     .default({}),

package/src/core/nav-diagnostics.ts

@@ -42,6 +42,9 @@ const collectIcons = (
       push(item.icon, `selector "${item.label}"`);
     }
   }
+  for (const link of navigation.featured) {
+    push(link.icon, `featured link "${link.label}"`);
+  }
   const sidebars = [navigation.sidebar];
   for (const sidebar of sidebars) {
     for (const node of flattenNodes(sidebar)) {
@@ -90,6 +93,10 @@ export const validateNavTargets = (
     ...navigation.selectors.flatMap((selector) =>
       selector.items.map((item) => ({ label: item.label, path: item.path }))
     ),
+    ...navigation.featured.map((link) => ({
+      label: link.label,
+      path: link.href,
+    })),
   ];
   const diagnostics: Diagnostic[] = [];
   const seen = new Set<string>();

package/src/core/navigation.ts

@@ -6,6 +6,7 @@ import type {
   SidebarItemConfig,
 } from "./schema.ts";
 import type {
+  FeaturedLink,
   NavNode,
   Navigation,
   NavSelector,
@@ -58,7 +59,6 @@ interface MutableGroup {
   label: string;
   icon?: string;
   collapsed?: boolean;
-  display?: SidebarDisplay;
   order: number;
   children: MutableNode[];
   index: Map<string, MutableGroup>;
@@ -140,7 +140,6 @@ const applyFolderMeta = (
     group.icon = meta.icon ?? group.icon;
     group.order = meta.order ?? group.order;
     group.collapsed = meta.collapsed ?? group.collapsed;
-    group.display = meta.display ?? group.display;
 
     if (meta.pages) {
       const rank = new Map(meta.pages.map((key, i) => [key, i]));
@@ -174,7 +173,21 @@ const sortNodes = (nodes: MutableNode[]): void => {
   }
 };
 
-const toNavNode = (node: MutableNode): NavNode => {
+/**
+ * In flat display a group renders as a plain section header, so a loose page
+ * sorted after a group would visually read as that group's last child. Hoist
+ * pages above groups at every level (relative order otherwise preserved).
+ */
+const hoistPages = (nodes: MutableNode[]): void => {
+  const pages = nodes.filter((node) => node.kind === "page");
+  const groups = nodes.filter((node) => node.kind === "group");
+  nodes.splice(0, nodes.length, ...pages, ...groups);
+  for (const group of groups) {
+    hoistPages(group.children);
+  }
+};
+
+const toNavNode = (node: MutableNode, display: SidebarDisplay): NavNode => {
   if (node.kind === "page") {
     return {
       badge: node.badge,
@@ -188,9 +201,9 @@ const toNavNode = (node: MutableNode): NavNode => {
     };
   }
   return {
-    children: node.children.map(toNavNode),
+    children: node.children.map((child) => toNavNode(child, display)),
     collapsed: node.collapsed,
-    display: node.display,
+    display,
     icon: node.icon,
     kind: "group",
     label: node.label,
@@ -203,7 +216,8 @@ const buildFileSystemSidebar = (
   pages: PageRecord[],
   folderMeta: Map<string, FolderMeta>,
   sharedMeta: Map<string, FolderMeta>,
-  metaPrefix: string
+  metaPrefix: string,
+  display: SidebarDisplay
 ): NavNode[] => {
   const root = createGroup("", "", "", 0);
 
@@ -246,7 +260,10 @@ const buildFileSystemSidebar = (
 
   applyFolderMeta(root, folderMeta, sharedMeta, metaPrefix);
   sortNodes(root.children);
-  return root.children.map(toNavNode);
+  if (display === "flat") {
+    hoistPages(root.children);
+  }
+  return root.children.map((child) => toNavNode(child, display));
 };
 
 const normalizeRef = (ref: string): string => {
@@ -275,7 +292,8 @@ const routeForRef = (
 /** Build the sidebar tree from an explicit config spec. */
 const buildConfigSidebar = (
   items: SidebarItemConfig[],
-  byRoute: Map<string, PageRecord>
+  byRoute: Map<string, PageRecord>,
+  display: SidebarDisplay
 ): NavNode[] => {
   const nodes: NavNode[] = [];
 
@@ -300,10 +318,10 @@ const buildConfigSidebar = (
     if (item.items) {
       nodes.push({
         badge: item.badge,
-        children: buildConfigSidebar(item.items, byRoute),
+        children: buildConfigSidebar(item.items, byRoute, display),
         collapsed: item.collapsed,
         directory: item.directory,
-        display: item.display,
+        display: item.display ?? display,
         icon: item.icon,
         kind: "group",
         label: item.label,
@@ -346,6 +364,9 @@ export const buildNavigation = (
   pages: PageRecord[],
   options: {
     folderMeta: Map<string, FolderMeta>;
+    /** Global display mode for every sidebar group (default `flat`). */
+    display?: SidebarDisplay;
+    featured?: FeaturedLink[];
     selectors?: NavSelector[];
     tabs?: NavTab[];
     sidebar?: SidebarItemConfig[];
@@ -361,8 +382,10 @@ export const buildNavigation = (
     sharedFolderMeta?: Map<string, FolderMeta>;
   }
 ): Navigation => {
+  const featured = options.featured ?? [];
   const selectors = options.selectors ?? [];
   const tabs = options.tabs ?? [];
+  const display = options.display ?? "flat";
   const metaPrefix = options.metaPrefix ?? "";
   const sharedFolderMeta = options.sharedFolderMeta ?? new Map();
   const byRoute = new Map(
@@ -374,19 +397,22 @@ export const buildNavigation = (
 
   if (options.sidebar) {
     return {
+      featured,
       selectors,
-      sidebar: buildConfigSidebar(options.sidebar, byRoute),
+      sidebar: buildConfigSidebar(options.sidebar, byRoute, display),
       tabs,
     };
   }
 
   return {
+    featured,
     selectors,
     sidebar: buildFileSystemSidebar(
       pages,
       options.folderMeta,
       sharedFolderMeta,
-      metaPrefix
+      metaPrefix,
+      display
     ),
     tabs,
   };

package/src/core/schema.ts

@@ -135,7 +135,6 @@ export type SidebarDisplay = z.infer<typeof sidebarDisplaySchema>;
 export const folderMetaSchema = z
   .object({
     collapsed: z.boolean().optional(),
-    display: sidebarDisplaySchema.optional(),
     icon: iconName.optional(),
     order: z.number().optional(),
     /** Explicit child ordering by slug segment (without numeric prefix). */
@@ -440,15 +439,37 @@ const fontSlug = z.string().refine(isFontSlug, (value) => ({
   message: `Unknown font "${value}". Supported fonts: ${FONT_SLUGS.join(", ")}.`,
 }));
 
+/**
+ * An optional per-mode theme value: a string applies to both color modes; a
+ * `{ light, dark }` object sets each mode individually (either may be
+ * omitted to override a single mode).
+ */
+const perModeValueSchema = z
+  .union([
+    z.string(),
+    z
+      .object({ dark: z.string().optional(), light: z.string().optional() })
+      .strict(),
+  ])
+  .optional()
+  .transform((value) =>
+    typeof value === "string" ? { dark: value, light: value } : value
+  );
+
 const themeConfigSchema = z
   .object({
-    accent: z.string().default("blue"),
-    accentDark: z.string().optional(),
+    accent: z
+      .union([
+        z.string(),
+        z.object({ dark: z.string(), light: z.string() }).strict(),
+      ])
+      .default("blue")
+      .transform((value) =>
+        typeof value === "string" ? { dark: value, light: value } : value
+      ),
     action: z.string().optional(),
-    background: z.string().optional(),
-    backgroundDark: z.string().optional(),
-    backgroundImage: z.string().optional(),
-    backgroundImageDark: z.string().optional(),
+    background: perModeValueSchema,
+    backgroundImage: perModeValueSchema,
     fonts: z
       .object({
         body: fontSlug.default("inter"),
@@ -571,6 +592,18 @@ const aiConfigSchema = z
         enabled: z.boolean().default(false),
         model: z.string().default("openai/gpt-5.5"),
         provider: z.enum(askAiProviders).default("gateway"),
+        // Empty-state prompts shown before the first question. Each renders as a
+        // clickable suggestion; `icon` is an optional Lucide name beside it.
+        suggestions: z
+          .array(
+            z
+              .object({
+                icon: iconName.optional(),
+                label: z.string().min(1),
+              })
+              .strict()
+          )
+          .default([]),
       })
       .strict()
       .superRefine((value, ctx) => {
@@ -590,13 +623,48 @@ const aiConfigSchema = z
   })
   .strict();
 
+/**
+ * A pinned link rendered above the sidebar sections — a blog, changelog, or
+ * contact page that should always be reachable, regardless of the active tab.
+ * `href` may be an external URL or an internal route.
+ */
+const featuredLinkSchema = z
+  .object({
+    href: z.string(),
+    icon: iconName.optional(),
+    label: z.string(),
+  })
+  .strict();
+
 const navigationConfigSchema = z
   .object({
+    /** Pinned links shown above the generated sidebar sections. */
+    featured: z.array(featuredLinkSchema).default([]),
     /** Show a GitHub repo link in the header (requires `github` configured). */
     repo: z.boolean().default(true),
     selectors: z.array(navSelectorSchema).default([]),
-    /** Explicit sidebar override; when omitted the sidebar is generated. */
-    sidebar: z.array(sidebarItemSchema).optional(),
+    /**
+     * Sidebar behavior. `display` sets how every group renders (a group in an
+     * explicit `items` config may still override it); `items` is an explicit
+     * sidebar — when omitted the sidebar is generated from the content tree.
+     * A bare array is shorthand for `{ items }`.
+     */
+    sidebar: z
+      .union([
+        z.array(sidebarItemSchema),
+        z
+          .object({
+            display: sidebarDisplaySchema.default("flat"),
+            items: z.array(sidebarItemSchema).optional(),
+          })
+          .strict(),
+      ])
+      .default({})
+      .transform((value) =>
+        Array.isArray(value)
+          ? { display: "flat" as const, items: value }
+          : value
+      ),
     tabs: z.array(navTabSchema).optional(),
   })
   .strict();
@@ -759,9 +827,52 @@ const rssConfigSchema = z
   })
   .strict();
 
+/**
+ * robots.txt `Content-Signal` preferences — the emerging content-usage
+ * declaration for how crawlers may reuse the site. Each field maps to one
+ * signal:
+ * - `search` → `search` (traditional and AI search indexing)
+ * - `aiInput` → `ai-input` (grounding / RAG use at answer time)
+ * - `aiTrain` → `ai-train` (model training)
+ */
+const contentSignalsObjectSchema = z
+  .object({
+    aiInput: z.boolean().default(true),
+    aiTrain: z.boolean().default(true),
+    search: z.boolean().default(true),
+  })
+  .strict();
+
+/**
+ * Content signals accept a boolean shorthand or a per-signal object, and
+ * normalize to `{ search, aiInput, aiTrain }` — or `null` when disabled, so
+ * robots.txt omits the declaration entirely. On by default (`true`): Blume
+ * declares the docs open to search and agents. `false` opts out; an object
+ * restricts individual signals (unset signals stay `yes`).
+ */
+const contentSignalsSchema = z
+  .union([z.boolean(), contentSignalsObjectSchema])
+  .transform((value) => {
+    if (value === true) {
+      return contentSignalsObjectSchema.parse({});
+    }
+    if (value === false) {
+      return null;
+    }
+    return value;
+  });
+
 /** Discoverability features: OG images, feeds, sitemap, structured data. */
 const seoConfigSchema = z
   .object({
+    /**
+     * Emit `agent-readability.json` at the site root: a manifest that indexes
+     * the agent-facing surface (llms.txt, Markdown mirrors, MCP server, feeds)
+     * so agents can discover it without scraping HTML.
+     */
+    agentReadability: z.boolean().default(true),
+    /** robots.txt `Content-Signal` usage declaration (on by default). */
+    contentSignals: contentSignalsSchema.default(true),
     og: ogConfigSchema.default({}),
     /** Generate robots.txt (with a Sitemap reference when available). */
     robots: z.boolean().default(true),
@@ -814,12 +925,6 @@ const codeConfigSchema = z
      * …). On by default; recognized languages only.
      */
     icons: z.boolean().default(true),
-    /**
-     * Syntax-highlight inline `` `code{:lang}` `` snippets. Off by default — most
-     * inline code (flags, file names) reads better plain; opt a snippet in with
-     * a trailing `{:lang}` marker.
-     */
-    inline: z.boolean().default(false),
     /**
      * Wrap long lines instead of scrolling horizontally. Off by default, so
      * code keeps its original line breaks and overflows into a scroll area.
@@ -844,11 +949,6 @@ const markdownConfigSchema = z
      * opt a single image out with `data-no-zoom`.
      */
     imageZoom: z.boolean().default(true),
-    /**
-     * Enable LaTeX math (`$…$` inline, `$$…$$` block) rendered with KaTeX.
-     * Off by default since `$` is common in prose, shell, and code. MDX only.
-     */
-    math: z.boolean().default(false),
   })
   .strict();
 
@@ -986,7 +1086,15 @@ export type ResolvedConfig = z.infer<typeof blumeConfigSchema>;
 export type ResolvedI18nConfig = z.infer<typeof i18nConfigSchema>;
 /** A configured locale with display metadata. */
 export type LocaleConfig = z.infer<typeof localeSchema>;
-/** User-authored config: the shape accepted by `defineConfig`. */
-export type BlumeConfig = z.input<typeof blumeConfigSchema>;
+/**
+ * User-authored config, straight off the schema. The public, hand-documented
+ * authoring type is `BlumeConfig` in `./config-input.ts`, which a compile-time
+ * guard keeps structurally identical to this.
+ */
+export type BlumeConfigInput = z.input<typeof blumeConfigSchema>;
 /** A configured search backend. */
 export type SearchProvider = (typeof searchProviders)[number];
+/** Resolved robots.txt `Content-Signal` preferences (`null` when disabled). */
+export type ContentSignals = z.infer<typeof contentSignalsSchema>;
+/** The resolved per-signal policy object (present when signals are enabled). */
+export type ContentSignalPolicy = NonNullable<ContentSignals>;

package/src/core/sources/filesystem.ts

@@ -8,6 +8,7 @@ import { BlumeError } from "../diagnostics.ts";
 import matter from "../frontmatter.ts";
 import type { ContentSource, SourceEntry, SourceLoadResult } from "./types.ts";
 import {
+  baselineScanIgnore,
   BLUME_WATCH_IGNORE_DIRS,
   excludeDirSegments,
   ignoringWatchListener,
@@ -45,7 +46,10 @@ export const filesystemSource = (
     const files = await glob(options.include, {
       absolute: true,
       cwd: contentRoot,
-      ignore: options.exclude,
+      // Union the user's `exclude` with the baseline never-content dirs so a
+      // broadly-scoped root (`.` or an app dir) can't glob `node_modules`,
+      // `dist`, `.blume`, etc. — even when the user overrode `exclude`.
+      ignore: [...options.exclude, ...baselineScanIgnore()],
       onlyFiles: true,
     });
     files.sort();