blume 0.5.4 → 0.6.0

package/src/components/layout/RootLayout.astro

@@ -18,6 +18,7 @@ import Favicon from "./Favicon.astro";
 import Fonts from "./Fonts.astro";
 import { bannerInitScript, themeInitScript } from "./head-scripts.ts";
 import Header from "./Header.astro";
+import Icon from "../Icon.astro";
 import {
   findBreadcrumbs,
   flattenPages,
@@ -342,11 +343,56 @@ const bannerScript = banner?.dismissible
     >
       <slot name="ask" slot="ask" />
     </HeaderSlot>
-    <div class:list={["mx-auto grid grid-cols-1 items-start", gridClass]}>
+    <div
+      class:list={["mx-auto grid grid-cols-1 items-start", gridClass]}
+      data-blume-doc-grid
+    >
       <aside
         aria-label="Primary"
         class="fixed top-[var(--blume-drawer-top,4rem)] start-0 z-[35] h-[calc(100dvh-var(--blume-drawer-top,4rem))] w-64 max-w-[80vw] -translate-x-[105%] overflow-y-auto border-border border-e bg-background px-5 pt-4 pb-6 transition-transform rtl:translate-x-[105%] [:where([data-blume-nav-open])_&]:translate-x-0! lg:sticky lg:top-16 lg:z-auto lg:h-[calc(100dvh-4rem)] lg:w-auto lg:max-w-none lg:translate-x-0! lg:border-e-0 lg:bg-transparent lg:px-4"
       >
+        {
+          // Pinned links (blog, changelog, contact…) sit above every section on
+          // all breakpoints, outside the tab-scoped sidebar so they never change
+          // with the active tab. External hrefs open in a new tab.
+          navigation.featured.length > 0 && (
+            <nav aria-label="Featured" class="mb-4 border-border border-b pb-4">
+              <ul class="m-0 list-none p-0">
+                {navigation.featured.map((link) => {
+                  const external = /^https?:\/\//u.test(link.href);
+                  return (
+                    <li>
+                      <a
+                        class="block rounded-[0.65rem] px-2.5 py-1.5 text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground"
+                        href={link.href}
+                        rel={external ? "noreferrer" : undefined}
+                        target={external ? "_blank" : undefined}
+                      >
+                        <span class="flex items-center gap-2">
+                          {link.icon && (
+                            <Icon
+                              class="shrink-0 text-muted-foreground"
+                              name={link.icon}
+                              size={14}
+                            />
+                          )}
+                          <span class="flex-1 truncate">{link.label}</span>
+                          {external && (
+                            <Icon
+                              class="shrink-0 text-muted-foreground opacity-60"
+                              name="arrow-up-right"
+                              size={12}
+                            />
+                          )}
+                        </span>
+                      </a>
+                    </li>
+                  );
+                })}
+              </ul>
+            </nav>
+          )
+        }
         {
           // The header's tab bar is hidden below `md`, so the drawer is the only
           // way to move between sections on mobile: list the tabs above the
@@ -427,6 +473,7 @@ const bannerScript = banner?.dismissible
           <aside
             aria-label={strings.toc.title}
             class="sticky top-16 hidden h-[calc(100dvh-4rem)] overflow-y-auto px-4 pt-6 pb-10 text-sm xl:block"
+            data-blume-toc
           >
             <TableOfContentsSlot
               headings={tocHeadings}
@@ -434,7 +481,6 @@ const bannerScript = banner?.dismissible
               variant="desktop"
             />
             <PageActions
-              askEnabled={askEnabled}
               editUrl={editUrl}
               exportEpub={exportEpub}
               exportPdf={exportPdf}

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),
@@ -990,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/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/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/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),
   };
 };