blume 0.5.4 → 0.6.1

package/src/core/sources/watch.ts

@@ -1,20 +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 `.`-rooted layout, or an
- * all-staged project (openapi/notion/github-releases/…) with no filesystem
- * source — 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

@@ -180,11 +180,20 @@ export interface NavSelector {
   items: NavSelectorItem[];
 }
 
+/** 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[];
   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/adapter-output.ts

@@ -0,0 +1,82 @@
+import { existsSync } from "node:fs";
+import { cp, mkdir, rm } from "node:fs/promises";
+
+import { dirname, join } from "pathe";
+
+import type { ResolvedConfig } from "../core/schema.ts";
+import type { ProjectContext } from "../core/types.ts";
+
+type Adapter = NonNullable<ResolvedConfig["deployment"]["adapter"]>;
+
+/**
+ * Server adapters whose deploy bundle lands *outside* Astro's `outDir`, at a
+ * path relative to the Astro project root. Blume points the Astro root at the
+ * hidden `<root>/.blume` runtime, so these adapters write their bundle to
+ * `<root>/.blume/<path>` — where the deploy platform never looks. Each value is
+ * the sub-path to surface up to the real project root.
+ *
+ * `vercel` writes a Build Output API v3 tree at `.vercel/output`; only that
+ * subtree is moved, so a `vercel pull`-ed `.vercel/project.json` sitting at the
+ * project root survives the relocation. `netlify` owns its whole `.netlify`
+ * dir. `node` and `cloudflare` emit into `dist/` (already at the project root),
+ * so they are absent here and need no relocation.
+ */
+export const ADAPTER_OUTPUT_PATHS: Partial<Record<Adapter, string>> = {
+  netlify: ".netlify",
+  vercel: ".vercel/output",
+};
+
+/**
+ * Directory whose contents the deploy platform serves as static files. Build
+ * artifacts (robots.txt, sitemap.xml, llms.txt, …) must be written here to be
+ * served. For a Vercel server build that is the adapter's
+ * `.vercel/output/static`; every other build serves `dist/`.
+ */
+export const deployStaticDir = (
+  config: ResolvedConfig,
+  context: ProjectContext
+): string => {
+  const { adapter, output } = config.deployment;
+  if (output === "server" && adapter === "vercel") {
+    return join(context.root, ".vercel", "output", "static");
+  }
+  return context.distDir ?? join(context.root, "dist");
+};
+
+/** Outcome of {@link surfaceAdapterOutput}, for logging and `.gitignore`. */
+export type SurfaceResult =
+  | { moved: false }
+  | { from: string; ignore: string; moved: true; to: string };
+
+/**
+ * Move a server adapter's deploy bundle out of the hidden `.blume` runtime and
+ * up to the project root, where the deploy platform (and `vercel deploy
+ * --prebuilt`) expects it. A no-op for static builds, for adapters that emit
+ * into `dist/`, and when the expected output is absent.
+ */
+export const surfaceAdapterOutput = async (
+  config: ResolvedConfig,
+  context: ProjectContext
+): Promise<SurfaceResult> => {
+  const { adapter, output } = config.deployment;
+  if (output !== "server" || !adapter) {
+    return { moved: false };
+  }
+  const rel = ADAPTER_OUTPUT_PATHS[adapter];
+  if (!rel) {
+    return { moved: false };
+  }
+  const from = join(context.outDir, rel);
+  const to = join(context.root, rel);
+  if (!existsSync(from)) {
+    return { moved: false };
+  }
+  await mkdir(dirname(to), { recursive: true });
+  await rm(to, { force: true, recursive: true });
+  await cp(from, to, { recursive: true });
+  await rm(from, { force: true, recursive: true });
+  // The `.gitignore` entry is the surfaced top-level dir (`.vercel`/`.netlify`),
+  // never the moved sub-path — Vercel's own `.vercel/project.json` lives there
+  // too and must also be ignored.
+  return { from, ignore: `${rel.split("/")[0]}/`, moved: true, to };
+};

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`);

package/src/index.ts

@@ -22,8 +22,8 @@ export type {
   FolderMetaFactory,
 } from "./core/define-meta.ts";
 export type { UIStrings } from "./core/i18n-ui.ts";
+export type { BlumeConfig } from "./core/config-input.ts";
 export type {
-  BlumeConfig,
   FolderMeta,
   HydrationMode,
   ResolvedConfig,

package/src/markdown/index.ts

@@ -46,15 +46,16 @@ type HastPlugin = NonNullable<
 
 /**
  * Hast plugins enabled by config. Inline `` `code`{:lang} `` highlighting is
- * opt-in; self-linking heading anchors (`<h2>`–`<h6>` wrapped in an `<a>` to
- * their own id) are on unless `markdown.headingAnchors` is `false`. Inline code
- * runs first so the anchor wrap re-refs already-highlighted code.
+ * always on: it only fires on an explicit trailing `{:lang}` marker, so plain
+ * inline code is untouched and there's nothing to opt out of. Self-linking
+ * heading anchors (`<h2>`–`<h6>` wrapped in an `<a>` to their own id) are on
+ * unless `markdown.headingAnchors` is `false`. Inline code runs first so the
+ * anchor wrap re-refs already-highlighted code.
  */
 const blumeHastPlugins = (options: BlumeMarkdownOptions): HastPlugin[] => {
-  const plugins: HastPlugin[] = [];
-  if (options.inline) {
-    plugins.push(inlineCodeHighlightPlugin() as unknown as HastPlugin);
-  }
+  const plugins: HastPlugin[] = [
+    inlineCodeHighlightPlugin() as unknown as HastPlugin,
+  ];
   if (options.headingAnchors !== false) {
     plugins.push(headingAnchorPlugin() as unknown as HastPlugin);
   }
@@ -204,8 +205,6 @@ export interface BlumeMarkdownOptions {
    * On unless explicitly `false`.
    */
   headingAnchors?: boolean;
-  /** Highlight inline `` `code`{:lang} `` snippets (`markdown.code.inline`). */
-  inline?: boolean;
 }
 
 /** Sätteri processor for plain `.md`, with Blume's curated feature set. */
@@ -215,38 +214,37 @@ export const blumeMarkdownProcessor = (options: BlumeMarkdownOptions = {}) =>
     hastPlugins: blumeHastPlugins(options),
   });
 
-export interface BlumeMdxOptions extends BlumeMarkdownOptions {
-  /** Enable KaTeX math parsing and rendering. */
-  math?: boolean;
-}
+export type BlumeMdxOptions = BlumeMarkdownOptions;
 
 /**
  * Sätteri MDX processor: Blume's feature set plus the MDAST plugins that target
  * components — `package-install` → package-manager tabs, `:::note` →
- * `<Callout>`, and ` ```mermaid ` → a `<blume-mermaid>` element. Used as the
- * `processor` for `@astrojs/mdx` so these apply to
- * `.mdx` only (plain `.md` uses {@link blumeMarkdownProcessor}). Math is opt-in
- * via config since `$` is common in prose and code.
+ * `<Callout>`, ` ```mermaid ` → a `<blume-mermaid>` element, and block math
+ * (`$$…$$`) → the `<Math>` component. Used as the `processor` for
+ * `@astrojs/mdx` so these apply to `.mdx` only (plain `.md` uses
+ * {@link blumeMarkdownProcessor}).
+ *
+ * Math is always on but block-only: `singleDollarTextMath: false` keeps a bare
+ * `$` (currency, shell, code) as literal text and only parses `$$…$$`. The
+ * generated runtime imports the `<Math>` component (and KaTeX's stylesheet) only
+ * when content actually uses `$$`, so a math-free site ships no KaTeX CSS.
  *
  * The plugins are modeled with minimal structural types; bridge them to
  * Satteri's full `MdastPlugin` type at this single boundary.
  */
-export const blumeMdxProcessor = (options: BlumeMdxOptions = {}) => {
-  const plugins: unknown[] = [
-    packageInstallPlugin(),
-    directiveToCalloutPlugin(),
-    mermaidPlugin(),
-  ];
-  if (options.math) {
-    plugins.push(mathPlugin());
-  }
-  return satteri({
+export const blumeMdxProcessor = (options: BlumeMdxOptions = {}) =>
+  satteri({
     features: {
       ...FEATURES,
       directive: true,
-      ...(options.math ? { math: true } : {}),
+      // Block-only: `$$…$$` parses, a bare `$` stays literal text.
+      math: { singleDollarTextMath: false },
     },
     hastPlugins: blumeHastPlugins(options),
-    mdastPlugins: plugins as unknown as MdastPlugin[],
+    mdastPlugins: [
+      packageInstallPlugin(),
+      directiveToCalloutPlugin(),
+      mermaidPlugin(),
+      mathPlugin(),
+    ] as unknown as MdastPlugin[],
   });
-};

package/src/markdown/math.ts

@@ -8,8 +8,9 @@ interface MathNode extends MdastNode {
 /**
  * Satteri MDAST plugin that turns math nodes into Blume's `<Math>` component,
  * which renders them with KaTeX at build time. Block math (`$$…$$`) becomes a
- * block element; inline math (`$…$`) stays inline. Only active when math is
- * enabled in config, so `$` is otherwise left as literal text.
+ * block element. Blume runs the parser block-only (`singleDollarTextMath:
+ * false`), so a bare `$` stays literal and no `inlineMath` nodes are produced;
+ * the `inlineMath` visitor remains as a harmless safety net.
  */
 export const mathPlugin = () => ({
   inlineMath(node: MathNode, ctx: MdastVisitorContext) {

package/src/openapi/scalar.ts

@@ -61,7 +61,7 @@ const themeConfiguration = (
   const accent = resolveAccent(config.theme);
   const radius = resolveRadius(config.theme);
   return {
-    customCss: `:root,.light-mode,.dark-mode{--scalar-color-accent:${accent};--scalar-radius:${radius};}`,
+    customCss: `:root,.light-mode,.dark-mode{--scalar-color-accent:${accent.light};--scalar-radius:${radius};}.dark-mode{--scalar-color-accent:${accent.dark};}`,
     ...darkModeConfig(config.theme.mode),
   };
 };

package/src/registry/eject.ts

@@ -12,6 +12,7 @@ import {
   buildRuntimeData,
   collectStaged,
   detectNeedsReact,
+  detectUsesMath,
 } from "../astro/generate.ts";
 import { discoverIslands } from "../astro/islands.ts";
 import { customOgRoutes, discoverPages, routeIsTaken } from "../astro/pages.ts";
@@ -102,19 +103,25 @@ export const eject = async (root: string): Promise<string[]> => {
   const exportPdf = config.export.pdf;
   const exportEpub = config.export.epub;
 
-  const [pages, needsReactRaw, userTheme, rawMarkdown, islands, examples] =
-    await Promise.all([
-      context.pagesRoot
-        ? discoverPages(context.pagesRoot)
-        : Promise.resolve([]),
-      detectNeedsReact(root),
-      context.themeFile
-        ? readFile(context.themeFile, "utf-8")
-        : Promise.resolve(""),
-      buildRawMarkdown(project),
-      discoverIslands(root),
-      discoverExamples(root, config.examples),
-    ]);
+  const [
+    pages,
+    needsReactRaw,
+    usesMath,
+    userTheme,
+    rawMarkdown,
+    islands,
+    examples,
+  ] = await Promise.all([
+    context.pagesRoot ? discoverPages(context.pagesRoot) : Promise.resolve([]),
+    detectNeedsReact(root),
+    detectUsesMath(root),
+    context.themeFile
+      ? readFile(context.themeFile, "utf-8")
+      : Promise.resolve(""),
+    buildRawMarkdown(project),
+    discoverIslands(root),
+    discoverExamples(root, config.examples),
+  ]);
   // Island/example frameworks drive which Astro renderers the ejected config
   // wires in; React also switches on for project `.tsx`/`.jsx` and Ask AI.
   const frameworks = new Set<string>([
@@ -192,7 +199,7 @@ export const eject = async (root: string): Promise<string[]> => {
         askEnabled,
         exportEpub,
         exportPdf,
-        mathEnabled: config.markdown.math,
+        mathEnabled: usesMath,
         needsReact,
       }),
       path: join(srcDir, "pages", "[...slug].astro"),

package/src/search/documents.ts

@@ -114,10 +114,15 @@ const buildCrumbIndex = (sidebar: NavNode[]): Map<string, Crumbs> => {
  * Pass `includeWhenDisabled` to index pages on their content merits even when
  * the search provider is `none` — used by the MCP server, which is a separate
  * feature from on-page search.
+ *
+ * `content` selects the extraction: `"plain"` (default) strips Markdown to bare
+ * searchable text; `"markdown"` keeps the body's Markdown — code blocks, lists,
+ * headings — for Ask AI grounding, where fenced examples are often the answer
+ * and stripping them makes the model unable to cite content the docs do contain.
  */
 export const buildSearchDocuments = async (
   project: BlumeProject,
-  options?: { includeWhenDisabled?: boolean }
+  options?: { includeWhenDisabled?: boolean; content?: "markdown" | "plain" }
 ): Promise<SearchDocument[]> => {
   const pageById = new Map(project.graph.pages.map((page) => [page.id, page]));
 
@@ -148,7 +153,9 @@ export const buildSearchDocuments = async (
     indexable.map(async (route) => {
       const page = pageById.get(route.id);
       const raw = page ? await readEntryText(project, page) : "";
-      const body = raw ? toPlainText(matter(raw).content) : "";
+      const source = raw ? matter(raw).content : "";
+      const body =
+        options?.content === "markdown" ? source.trim() : toPlainText(source);
       const tags = page?.meta?.search?.tags;
       const crumb = crumbs.get(route.path);
       return {

package/src/theme/entry.ts

@@ -435,6 +435,10 @@ blume-diff {
   font-size: 0.8125rem;
 }
 
+.prose :where(td, th) :not(pre) > code {
+  white-space: nowrap;
+}
+
 blume-tabs pre,
 .not-prose > div > pre {
   background: var(--blume-code-background);
@@ -610,9 +614,9 @@ pre:has(.line.focused):hover .line:not(.focused) {
   content: none;
 }
 
-/* Inline code highlighting (markdown.code.inline): Shiki colors the tokens of a
-   \`code\`{:lang} snippet via the same dual-theme CSS variables as fenced blocks,
-   keeping the inline pill background. */
+/* Inline code highlighting: Shiki colors the tokens of a \`code\`{:lang} snippet
+   via the same dual-theme CSS variables as fenced blocks, keeping the inline
+   pill background. Always on — it only fires on the trailing {:lang} marker. */
 .prose code.blume-inline-code span {
   color: var(--shiki-light);
 }

package/src/theme/palette.ts

@@ -67,10 +67,12 @@ const themeRootCss = (
       "--blume-action-foreground",
       options.action ? "oklch(1 0 0)" : null
     ),
-    ...cssToken("--blume-background", safeColorOrNull(theme.background)),
+    ...cssToken("--blume-background", safeColorOrNull(theme.background?.light)),
     ...cssToken(
       "--blume-background-image",
-      theme.backgroundImage ? backgroundImageCss(theme.backgroundImage) : null
+      theme.backgroundImage?.light
+        ? backgroundImageCss(theme.backgroundImage.light)
+        : null
     ),
     `  --blume-radius: ${options.radius};`,
   ]
@@ -96,11 +98,11 @@ const themeDarkCss = (
       "--blume-action-foreground",
       options.action ? "oklch(1 0 0)" : null
     ),
-    ...cssToken("--blume-background", safeColorOrNull(theme.backgroundDark)),
+    ...cssToken("--blume-background", safeColorOrNull(theme.background?.dark)),
     ...cssToken(
       "--blume-background-image",
-      theme.backgroundImageDark
-        ? backgroundImageCss(theme.backgroundImageDark)
+      theme.backgroundImage?.dark
+        ? backgroundImageCss(theme.backgroundImage.dark)
         : null
     ),
   ].filter(Boolean);
@@ -111,12 +113,18 @@ ${tokens.join("\n")}
 };
 
 /**
- * Resolve the configured accent to a CSS color. A named accent resolves to its
- * preset; any other value is treated as a raw CSS color so users can pass
- * arbitrary colors without a config change.
+ * Resolve the configured accent to per-mode CSS colors. A named accent
+ * resolves to its preset; any other value is treated as a raw CSS color so
+ * users can pass arbitrary colors without a config change. A string accent
+ * has already been normalized by the config schema to the same color for
+ * both modes.
  */
-export const resolveAccent = (theme: ResolvedConfig["theme"]): string =>
-  presetOrColor(theme.accent);
+export const resolveAccent = (
+  theme: ResolvedConfig["theme"]
+): { dark: string; light: string } => ({
+  dark: presetOrColor(theme.accent.dark),
+  light: presetOrColor(theme.accent.light),
+});
 
 /** Resolve the configured radius preset to a CSS length. */
 export const resolveRadius = (theme: ResolvedConfig["theme"]): string =>
@@ -128,17 +136,16 @@ export const resolveRadius = (theme: ResolvedConfig["theme"]): string =>
  * arbitrary colors without a config change.
  */
 export const buildThemeCss = (theme: ResolvedConfig["theme"]): string => {
-  const accent = presetOrColor(theme.accent);
-  const accentDark = theme.accentDark ? presetOrColor(theme.accentDark) : null;
+  const accent = resolveAccent(theme);
   const action = theme.action ? presetOrColor(theme.action) : null;
   const radius = RADII[theme.radius];
   const root = themeRootCss(theme, {
-    accent,
+    accent: accent.light,
     action,
     radius,
   });
   const dark = themeDarkCss(theme, {
-    accent: accentDark ?? accent,
+    accent: accent.dark,
     action,
   });