blume 0.5.3 → 0.6.0

package/src/core/schema.ts

@@ -99,25 +99,15 @@ const pageMetaBaseSchema = z
     deprecated: z.boolean().default(false),
     description: z.string().optional(),
     draft: z.boolean().default(false),
-    groups: z.union([z.string(), z.array(z.string())]).optional(),
     hidden: z.boolean().default(false),
-    hideApiMarker: z.boolean().default(false),
-    hideFooterPagination: z.boolean().optional(),
     icon: iconName.optional(),
-    iconType: z.string().optional(),
-    keywords: z.array(z.string()).optional(),
     /** Overrides the git-derived last-modified date when `lastModified` is on. */
     lastModified: dateSchema.optional(),
-    mode: z.string().optional(),
     noindex: z.boolean().default(false),
-    public: z.boolean().optional(),
-    rss: z.boolean().optional(),
     search: searchMetaSchema.default({}),
     seo: seoMetaSchema.default({}),
     sidebar: sidebarMetaSchema.default({}),
-    sidebarTitle: z.string().optional(),
     slug: z.string().optional(),
-    tag: z.string().optional(),
     title: z.string().optional(),
     type: z.string().default("doc"),
   })
@@ -145,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). */
@@ -160,45 +149,41 @@ export type FolderMeta = z.infer<typeof folderMetaSchema>;
 // Project config (blume.config.ts)
 // ---------------------------------------------------------------------------
 
-const logoConfigSchema = z.union([
+/** The logo mark: a single image path/URL, or light/dark variants with alt text. */
+const logoImageSchema = z.union([
   z.string(),
   z
     .object({
       alt: z.string().optional(),
       dark: z.string().optional(),
-      href: z.string().optional(),
       light: z.string().optional(),
     })
     .strict(),
 ]);
 
-const faviconConfigSchema = z.union([
+/**
+ * Site logo. A bare string is the image shorthand. The object form splits the
+ * brand into an optional `image` mark and optional wordmark `text` so a site can
+ * show an image-only logo (a mark with the wordmark baked in), a text-only logo,
+ * or both. Omit `text` to fall back to the site title; set `text: ""` to render
+ * the mark alone. `href` overrides the brand link (defaults to `/`).
+ */
+const logoConfigSchema = z.union([
   z.string(),
   z
     .object({
-      dark: z.string().optional(),
-      light: z.string().optional(),
+      href: z.string().optional(),
+      image: logoImageSchema.optional(),
+      text: z.string().optional(),
     })
     .strict(),
 ]);
 
-const bannerColorSchema = z
-  .object({
-    dark: z.string().optional(),
-    light: z.string().optional(),
-  })
-  .strict()
-  .refine((value) => value.dark !== undefined || value.light !== undefined, {
-    message: "Banner color requires at least one of light or dark.",
-  });
-
 /** Site-wide announcement banner: a string, or text with an optional link. */
 const bannerConfigSchema = z.union([
   z.string(),
   z
     .object({
-      /** Background color override (Mintlify compatibility). */
-      color: bannerColorSchema.optional(),
       content: z.string(),
       /** Show a dismiss button; the choice is remembered per visitor. */
       dismissible: z.boolean().default(false),
@@ -208,8 +193,6 @@ const bannerConfigSchema = z.union([
         .object({ href: z.string(), text: z.string() })
         .strict()
         .optional(),
-      /** Tone (Mintlify compatibility). */
-      type: z.enum(["info", "warning", "critical"]).optional(),
     })
     .strict(),
 ]);
@@ -329,30 +312,6 @@ const githubReleasesSourceSchema = z
   })
   .strict();
 
-/**
- * In-place Mintlify content (`docs.json` + MDX). Powers "bridge mode": Blume
- * reads an unconverted Mintlify project, transforming each page to Blume MDX at
- * scan time. Injected automatically by `loadConfig` when a `docs.json` is found
- * and no `blume.config.*` exists; can also be configured explicitly.
- */
-const mintlifySourceSchema = z
-  .object({
-    /** Absolute path of the `docs.json`/`mint.json`, watched for changes in dev. */
-    configFile: z.string().optional(),
-    /** Patterns excluded from page discovery (Mintlify defaults are merged in). */
-    exclude: z.array(z.string()).default([]),
-    /** Glob patterns for Mintlify content files. */
-    include: z.array(z.string()).default(["**/*.{md,mdx}"]),
-    /** Namespaces the source's routes under `/<prefix>/`. */
-    prefix: z.string().optional(),
-    /** Content root, absolute or relative to the project root (Mintlify: `.`). */
-    root: z.string().default("."),
-    type: z.literal("mintlify"),
-    /** `docs.json` variables, inlined into content (`{{name}}`) at scan time. */
-    variables: z.record(z.string(), z.string()).default({}),
-  })
-  .strict();
-
 /**
  * A user-provided `ContentSource` instance, passed straight through from
  * `blume.config.ts`. This is the extension point that lets adapters with custom
@@ -377,7 +336,6 @@ const contentSourceSchema = z.discriminatedUnion("type", [
   githubReleasesSourceSchema,
   sanitySourceSchema,
   notionSourceSchema,
-  mintlifySourceSchema,
   customSourceSchema,
 ]);
 
@@ -386,13 +344,6 @@ export type ContentSourceConfig = z.infer<typeof contentSourceSchema>;
 
 const contentConfigSchema = z
   .object({
-    /**
-     * Extra top-level directories (relative to the project root) served as
-     * static assets at the site root, alongside `public/`. Lets projects keep
-     * root-served asset folders in place — e.g. a Mintlify migration keeps
-     * `images/` where it is instead of relocating it under `public/`.
-     */
-    assets: z.array(z.string()).default([]),
     defaultType: z.string().default("doc"),
     exclude: z.array(z.string()).default(["**/_*", "**/.*"]),
     include: z.array(z.string()).default(["**/*.{md,mdx}"]),
@@ -483,25 +434,42 @@ const sidebarItemSchema: z.ZodType<SidebarItemConfig> = z.lazy(() =>
   ])
 );
 
-const variablesConfigSchema = z
-  .record(z.string().regex(/^[A-Za-z0-9-]+$/u), z.string())
-  .default({});
-
 /** A curated Google Font slug (see `theme/fonts.ts`). */
 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(),
-    backgroundDecoration: z.enum(["gradient", "grid", "windows"]).optional(),
-    backgroundImage: z.string().optional(),
-    backgroundImageDark: z.string().optional(),
+    background: perModeValueSchema,
+    backgroundImage: perModeValueSchema,
     fonts: z
       .object({
         body: fontSlug.default("inter"),
@@ -584,7 +552,6 @@ const searchConfigSchema = z
       .default({}),
     mixedbread: mixedbreadSearchSchema.optional(),
     oramaCloud: oramaCloudSearchSchema.optional(),
-    prompt: z.string().optional(),
     provider: z.enum(searchProviders).default("orama"),
     typesense: typesenseSearchSchema.optional(),
   })
@@ -625,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) => {
@@ -644,21 +623,48 @@ const aiConfigSchema = z
   })
   .strict();
 
-const chromeVariantSchema = z
+/**
+ * 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({
-    banner: bannerConfigSchema.optional(),
-    path: z.string(),
+    href: z.string(),
+    icon: iconName.optional(),
+    label: z.string(),
   })
   .strict();
 
 const navigationConfigSchema = z
   .object({
-    chromeVariants: z.array(chromeVariantSchema).default([]),
+    /** 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();
@@ -821,10 +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({
-    metatags: z.record(z.string(), z.string()).default({}),
+    /**
+     * 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),
@@ -1001,17 +1049,6 @@ const tocConfigSchema = z
     };
   });
 
-/**
- * Which icon library bare `icon` names resolve against (mirrors Mintlify's
- * `icons.library`). Names can always opt into a specific set with an explicit
- * `prefix:name` (`lucide:rocket`, `fa6-brands:github`) regardless of this.
- */
-const iconsConfigSchema = z
-  .object({
-    library: z.enum(["lucide", "fontawesome", "tabler"]).default("lucide"),
-  })
-  .strict();
-
 export const blumeConfigSchema = z
   .object({
     ai: aiConfigSchema.default({}),
@@ -1036,11 +1073,9 @@ export const blumeConfigSchema = z
      */
     examples: z.string().default("examples"),
     export: exportConfigSchema.default(false),
-    favicon: faviconConfigSchema.optional(),
     feedback: z.boolean().default(true),
     github: githubConfigSchema.optional(),
     i18n: i18nConfigSchema.optional(),
-    icons: iconsConfigSchema.default({}),
     lastModified: lastModifiedConfigSchema.default(false),
     logo: logoConfigSchema.optional(),
     markdown: markdownConfigSchema.default({}),
@@ -1053,7 +1088,6 @@ export const blumeConfigSchema = z
     theme: themeConfigSchema.default({}),
     title: z.string().default("Documentation"),
     toc: tocConfigSchema,
-    variables: variablesConfigSchema,
   })
   .strict();
 
@@ -1067,3 +1101,7 @@ export type LocaleConfig = z.infer<typeof localeSchema>;
 export type BlumeConfig = 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();

package/src/core/sources/resolve.ts

@@ -7,7 +7,6 @@ import type { ProjectContext } from "../types.ts";
 import { filesystemSource } from "./filesystem.ts";
 import { githubReleasesSource } from "./github-releases.ts";
 import { mdxRemoteSource } from "./mdx-remote.ts";
-import { mintlifySource } from "./mintlify.ts";
 import { notionSource } from "./notion.ts";
 import { sanitySource } from "./sanity.ts";
 import type { ContentSource, SourceContext } from "./types.ts";
@@ -64,18 +63,6 @@ const buildSource = (
       root: def.root,
     });
   }
-  if (def.type === "mintlify") {
-    return mintlifySource({
-      configFile: def.configFile,
-      exclude: def.exclude,
-      include: def.include,
-      name,
-      prefix: def.prefix,
-      projectRoot: context.root,
-      root: def.root,
-      variables: def.variables,
-    });
-  }
   if (def.type === "custom") {
     // A user-provided instance manages its own context/caching; we only ensure
     // its name is unique across the project for id namespacing.

package/src/core/sources/watch.ts

@@ -1,19 +1,51 @@
 import type { WatchListener } from "node:fs";
 
 /**
- * Directory segments a recursive dev watcher must never react to. When a
- * source's content root is the project root — a migrated `.`-rooted project or a
- * Mintlify bridge — a naive recursive `fs.watch` also sees Blume's own `.blume/`
- * output, which the dev server rewrites on every render (e.g.
- * `.blume/.astro/data-store.json`). Left unfiltered, each such write re-triggers
- * a rescan + runtime regeneration whose writes land back under `.blume/` and
- * fire the watcher again: a self-sustaining loop that stalls page renders and
- * floods the console (and, mid-render, corrupts Astro's dev module graph so
- * `astro:server-app.js` fails to load). `.git`/`node_modules` are here for the
- * same reason — churn that is never page content. `fs.watch` has no ignore
+ * Directory segments that are never authored content: VCS, dependency trees,
+ * Blume's own generated project and build output, and framework/deploy caches.
+ * Both the content scan and the dev watcher skip these unconditionally, on top
+ * of the user's `content.exclude`.
+ *
+ * The scan needs them because a broadly-scoped `content.root` — `"."` or an app
+ * dir that also holds `node_modules`/`dist`, the common shape when migrating a
+ * docs app that lives at the repo or app root — would otherwise glob thousands
+ * of stray markdown files out of dependencies and build artifacts. `content.root`
+ * defaults to `docs/` where this rarely bites, but any wider root hits it.
+ *
+ * The watcher needs them because a recursive `fs.watch` rooted at the project
+ * also sees Blume's own `.blume/` output, which the dev server rewrites on every
+ * render (e.g. `.blume/.astro/data-store.json`). Left unfiltered, each such write
+ * re-triggers a rescan + runtime regeneration whose writes land back under
+ * `.blume/` and fire the watcher again: a self-sustaining loop that stalls page
+ * renders and floods the console (and, mid-render, corrupts Astro's dev module
+ * graph so `astro:server-app.js` fails to load). `fs.watch` has no ignore
  * option, so we filter by the changed path in the callback.
  */
-export const BLUME_WATCH_IGNORE_DIRS = [".blume", ".git", "node_modules"];
+export const BLUME_IGNORE_DIRS = [
+  ".blume",
+  ".cache",
+  ".git",
+  ".next",
+  ".turbo",
+  ".vercel",
+  "dist",
+  "node_modules",
+];
+
+/**
+ * Baseline scan-ignore globs applied to every filesystem source, unioned with
+ * the user's `content.exclude`. Kept in sync with the watcher via the shared
+ * {@link BLUME_IGNORE_DIRS} so `load()` and `watch()` never disagree on what is
+ * content. `**\/<dir>/**` matches the directory at the content root or nested.
+ */
+export const baselineScanIgnore = (): string[] =>
+  BLUME_IGNORE_DIRS.map((dir) => `**/${dir}/**`);
+
+/**
+ * Alias retained for the dev watcher's call site and its tests; the watcher and
+ * the scan share the same never-content directory set.
+ */
+export const BLUME_WATCH_IGNORE_DIRS = BLUME_IGNORE_DIRS;
 
 /** Extract single-segment ignore dirs (`foo`) from `foo/**`-style excludes. */
 export const excludeDirSegments = (patterns: readonly string[]): string[] =>

package/src/core/types.ts

@@ -173,25 +173,27 @@ export interface NavSelectorItem {
   tag?: string;
 }
 
-/** Top-level Mintlify-style partition selectors. */
+/** Top-level partition selectors (products, versions, languages). */
 export interface NavSelector {
   label: string;
   kind: "dropdown" | "language" | "product" | "version";
   items: NavSelectorItem[];
 }
 
-/** Chrome overrides used when the current route belongs to a nav partition. */
-export interface NavChromeVariant {
-  path: string;
-  banner?: ResolvedConfig["banner"];
+/** A pinned link rendered above the sidebar sections (external or internal). */
+export interface FeaturedLink {
+  label: string;
+  href: string;
+  icon?: string;
 }
 
 /** The complete navigation model derived from the content graph. */
 export interface Navigation {
   tabs: NavTab[];
   selectors: NavSelector[];
-  chromeVariants: NavChromeVariant[];
   sidebar: NavNode[];
+  /** Pinned links shown above the sidebar sections, unscoped by tab. */
+  featured: FeaturedLink[];
   /** Repo URL for the header link, or null when hidden (`navigation.repo`). */
   repoUrl?: string | null;
 }

package/src/deploy/robots.ts

@@ -1,9 +1,36 @@
 import type { BlumeProject } from "../core/project-graph.ts";
+import type { ContentSignalPolicy, ContentSignals } from "../core/schema.ts";
 
 /**
- * Build a robots.txt that allows all crawlers and points to the sitemap when
- * one is available (a `site` is set and the sitemap is enabled). Returns null
- * when robots generation is disabled.
+ * Ordered mapping from config field to its `Content-Signal` token. The order
+ * fixes the emitted sequence (`search`, then `ai-input`, then `ai-train`).
+ */
+const SIGNAL_TOKENS: [keyof ContentSignalPolicy, string][] = [
+  ["search", "search"],
+  ["aiInput", "ai-input"],
+  ["aiTrain", "ai-train"],
+];
+
+/**
+ * The `Content-Signal:` line declaring how crawlers may reuse the site, or null
+ * when the declaration is disabled (`contentSignals: false`). Otherwise every
+ * signal is emitted with its resolved yes/no value.
+ */
+const contentSignalLine = (signals: ContentSignals): string | null => {
+  if (!signals) {
+    return null;
+  }
+  const tokens = SIGNAL_TOKENS.map(
+    ([key, token]) => `${token}=${signals[key] ? "yes" : "no"}`
+  );
+  return `Content-Signal: ${tokens.join(", ")}`;
+};
+
+/**
+ * Build a robots.txt that allows all crawlers, declares any configured
+ * `Content-Signal` usage preferences, and points to the sitemap when one is
+ * available (a `site` is set and the sitemap is enabled). Returns null when
+ * robots generation is disabled.
  */
 export const buildRobots = (project: BlumeProject): string | null => {
   const { config } = project;
@@ -11,7 +38,13 @@ export const buildRobots = (project: BlumeProject): string | null => {
     return null;
   }
 
-  const lines = ["User-agent: *", "Allow: /"];
+  const lines = ["User-agent: *"];
+  const signal = contentSignalLine(config.seo.contentSignals);
+  if (signal) {
+    lines.push(signal);
+  }
+  lines.push("Allow: /");
+
   const { site } = config.deployment;
   if (site && config.seo.sitemap) {
     lines.push("", `Sitemap: ${site.replace(/\/$/u, "")}/sitemap.xml`);