blume 0.5.3 → 0.6.0

package/src/components/layout/nav-utils.ts

@@ -161,9 +161,14 @@ const withoutTabSections = (nodes: NavNode[], tabs: NavTab[]): NavNode[] => {
  * Adapters / API / AI tabs) drills each tab into its own pages instead of one
  * global tree, the way Fumadocs' root folders do. On a route under no tab (or
  * the root `/` tab), the tab-owned groups are hidden so the root sidebar shows
- * only pages that don't belong to a tab. Falls back to the full sidebar when a
- * matched tab maps to no group, or when hiding the tab sections would blank the
- * sidebar, so a route is never left empty.
+ * only pages that don't belong to a tab.
+ *
+ * When a matched tab owns no sidebar group — a standalone page like the
+ * generated changelog timeline (`/changelog`), or a tab whose source produced
+ * no pages — the sidebar is empty. It must not fall back to the full tree: that
+ * would leak every *other* tab's section (e.g. the OpenAPI operations) onto the
+ * page. On a route under no tab, hiding the tab sections falls back to the full
+ * sidebar only when it would otherwise blank, so an un-tabbed route stays full.
  */
 export const sidebarForRoute = (
   sidebar: NavNode[],
@@ -172,7 +177,7 @@ export const sidebarForRoute = (
 ): NavNode[] => {
   const tab = activeTab(tabs, route);
   if (tab) {
-    return sectionChildren(sidebar, tab.path) ?? sidebar;
+    return sectionChildren(sidebar, tab.path) ?? [];
   }
   const scoped = withoutTabSections(sidebar, tabs);
   return scoped.length > 0 ? scoped : sidebar;

package/src/components/openapi/ApiOverview.astro

@@ -1,28 +1,18 @@
 ---
 import specs from "blume:openapi";
-import MethodBadge from "./MethodBadge.astro";
 
+// The spec-level metadata block (version + base URLs) at the top of an API
+// overview page. The tag sections that follow are emitted by `overviewMdx` as
+// markdown headings plus `<ApiTagOperations>` lists, so they land in the
+// table of contents.
 interface Props {
   source: string;
 }
 
 const { source } = Astro.props;
 const spec = specs[source];
-const operations = Object.values(spec?.operations ?? {});
 const servers =
   ((spec?.document ?? {}) as { servers?: { url?: string }[] }).servers ?? [];
-
-// Tags in declared order, then any operation tag not listed under `tags`.
-const declaredSlugs = new Set(spec?.tags.map((tag) => tag.slug));
-const extraSlugs = new Set<string>();
-const extraTags: { slug: string; name: string; description: string }[] = [];
-for (const operation of operations) {
-  if (!(declaredSlugs.has(operation.tagSlug) || extraSlugs.has(operation.tagSlug))) {
-    extraSlugs.add(operation.tagSlug);
-    extraTags.push({ description: "", name: operation.tag, slug: operation.tagSlug });
-  }
-}
-const sections = [...(spec?.tags ?? []), ...extraTags];
 ---
 
 {
@@ -43,42 +33,6 @@ const sections = [...(spec?.tags ?? []), ...extraTags];
           ))}
         </div>
       )}
-      {sections.map((tag) => {
-        const ops = operations.filter(
-          (operation) => operation.tagSlug === tag.slug
-        );
-        if (ops.length === 0) {
-          return null;
-        }
-        return (
-          <section class="mb-8">
-            <h2 class="mb-1 font-semibold text-foreground text-xl">
-              {tag.name}
-            </h2>
-            {tag.description && (
-              <div class="mb-3 text-muted-foreground text-sm" set:text={tag.description} />
-            )}
-            <ul class="not-prose flex list-none flex-col gap-2 p-0">
-              {ops.map((operation) => (
-                <li>
-                  <a
-                    class="flex items-center gap-3 rounded-blume border border-border p-3 text-inherit no-underline! transition-colors hover:border-accent hover:bg-muted hover:no-underline!"
-                    href={operation.route}
-                  >
-                    <MethodBadge method={operation.method} />
-                    <span class="font-medium text-foreground text-sm">
-                      {operation.summary || operation.path}
-                    </span>
-                    <code class="ml-auto hidden text-muted-foreground text-xs sm:inline">
-                      {operation.path}
-                    </code>
-                  </a>
-                </li>
-              ))}
-            </ul>
-          </section>
-        );
-      })}
     </div>
   )
 }

package/src/components/openapi/ApiTagOperations.astro

@@ -0,0 +1,42 @@
+---
+import specs from "blume:openapi";
+import MethodBadge from "./MethodBadge.astro";
+
+// The operation-link list for one tag section of an API overview page. The
+// section heading itself is emitted by `overviewMdx` as a markdown `##` — so it
+// flows into the table of contents — and this component renders only the list
+// of operations beneath it.
+interface Props {
+  source: string;
+  /** Tag slug (`ApiOperationRef.tagSlug`) selecting this section's operations. */
+  tag: string;
+}
+
+const { source, tag } = Astro.props;
+const operations = Object.values(specs[source]?.operations ?? {}).filter(
+  (operation) => operation.tagSlug === tag
+);
+---
+
+{
+  operations.length > 0 && (
+    <ul class="not-prose my-4 flex list-none flex-col gap-2 p-0">
+      {operations.map((operation) => (
+        <li>
+          <a
+            class="flex items-center gap-3 rounded-blume border border-border p-3 text-inherit no-underline! transition-colors hover:border-accent hover:bg-muted hover:no-underline!"
+            href={operation.route}
+          >
+            <MethodBadge method={operation.method} />
+            <span class="font-medium text-foreground text-sm">
+              {operation.summary || operation.path}
+            </span>
+            <code class="ml-auto hidden text-muted-foreground text-xs sm:inline">
+              {operation.path}
+            </code>
+          </a>
+        </li>
+      ))}
+    </ul>
+  )
+}

package/src/core/builtin-tags.ts

@@ -8,6 +8,7 @@ export const BUILTIN_MDX_TAGS = new Set<string>([
   "Accordion",
   "AccordionItem",
   "ApiOverview",
+  "ApiTagOperations",
   "AutoTypeTable",
   "Badge",
   "Callout",
@@ -28,10 +29,7 @@ export const BUILTIN_MDX_TAGS = new Set<string>([
   "Math",
   "Operation",
   "Panel",
-  "ParamField",
   "Prompt",
-  "RequestField",
-  "ResponseField",
   "Step",
   "Steps",
   "Tab",

package/src/core/config.ts

@@ -1,7 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
 
-import { detectMintlifyBridge } from "./bridge.ts";
-import type { BridgeDetection } from "./bridge.ts";
 import { applyDeploymentEnv } from "./deployment-env.ts";
 import { BlumeError, diagnosticsFromZod } from "./diagnostics.ts";
 import { createModuleLoader } from "./load-module.ts";
@@ -16,20 +14,11 @@ import type { Diagnostic } from "./types.ts";
  */
 export const defineConfig = (config: BlumeConfig): BlumeConfig => config;
 
-/** Bridge mode info: a foreign docs tool Blume is serving without migrating. */
-export interface ConfigBridge {
-  tool: "mintlify";
-  /** Absolute path of the foreign config file (`docs.json`/`mint.json`). */
-  configFile: string;
-}
-
 /** Result of loading + validating a project config. */
 export interface ConfigLoadResult {
   config: ResolvedConfig;
   /** Absolute path of the config file used, or null when defaults were used. */
   configFile: string | null;
-  /** Set when a foreign docs config (e.g. Mintlify) is being bridged. */
-  bridge: ConfigBridge | null;
   diagnostics: Diagnostic[];
 }
 
@@ -50,9 +39,6 @@ export const loadConfig = async (
 ): Promise<ConfigLoadResult> => {
   const configFile = findConfigFile(root);
 
-  // With no Blume config, a Mintlify `docs.json` activates bridge mode: serve
-  // the unconverted project by synthesizing config + a `mintlify` content source.
-  let bridge: BridgeDetection | null = null;
   let raw: unknown = {};
   if (configFile) {
     try {
@@ -65,30 +51,24 @@ export const loadConfig = async (
         severity: "error",
       });
     }
-  } else {
-    bridge = await detectMintlifyBridge(root);
-    if (bridge) {
-      ({ raw } = bridge);
-    }
   }
 
-  const sourceFile = bridge?.configFile ?? configFile;
   const parsed = blumeConfigSchema.safeParse(raw ?? {});
   if (!parsed.success) {
     // Read the raw config text (when on disk) so errors carry a line/column.
     const source =
-      sourceFile && existsSync(sourceFile)
-        ? readFileSync(sourceFile, "utf-8")
+      configFile && existsSync(configFile)
+        ? readFileSync(configFile, "utf-8")
         : undefined;
     const diagnostics = diagnosticsFromZod(parsed.error, {
       code: "BLUME_CONFIG_INVALID",
-      file: sourceFile ?? undefined,
+      file: configFile ?? undefined,
       source,
     });
     const [first, ...rest] = diagnostics;
     const primary = first ?? {
       code: "BLUME_CONFIG_INVALID",
-      file: sourceFile ?? undefined,
+      file: configFile ?? undefined,
       message: "Invalid Blume config.",
       severity: "error" as const,
     };
@@ -115,15 +95,12 @@ export const loadConfig = async (
   const ogEnabled = config.seo.og.enabled ?? Boolean(site);
 
   return {
-    bridge: bridge
-      ? { configFile: bridge.configFile, tool: bridge.tool }
-      : null,
     config: {
       ...config,
       deployment: { ...config.deployment, site },
       seo: { ...config.seo, og: { ...config.seo.og, enabled: ogEnabled } },
     },
-    configFile: sourceFile,
+    configFile,
     diagnostics: [],
   };
 };

package/src/core/data.ts

@@ -17,6 +17,8 @@ export interface BlumeLogo {
   dark?: string;
   alt: string;
   href: string;
+  /** Wordmark text beside the mark; `undefined` falls back to the site title. */
+  text?: string;
 }
 
 /** A favicon or apple-touch-icon: a link href plus an optional MIME type. */
@@ -86,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;
@@ -93,8 +99,6 @@ export interface BlumeDataConfig {
   favicon: BlumeFavicon;
   feedback: boolean;
   i18n: BlumeDataI18n | null;
-  /** Default icon library for bare `icon` names. */
-  icons: ResolvedConfig["icons"];
   /** `markdown.imageZoom`: click-to-zoom content images. */
   imageZoom: boolean;
   logo: BlumeLogo | null;

package/src/core/graph.ts

@@ -60,7 +60,7 @@ export const buildContentGraph = (
     }
 
     // Each locale gets an independent tree from its own pages and folder meta,
-    // so navigation may diverge per language (Mintlify-style).
+    // so navigation may diverge per language.
     for (const { code } of i18n.locales) {
       // Localize internal tab paths so a header tab points to its in-locale
       // route (e.g. `/docs` -> `/fr/docs`); external paths pass through.
@@ -89,7 +89,8 @@ export const buildContentGraph = (
       }
 
       navigationByLocale[code] = buildNavigation(localePages, {
-        chromeVariants: options.navigation.chromeVariants,
+        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
@@ -100,23 +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] ?? {
-      chromeVariants: [],
+      featured: [],
       selectors: [],
       sidebar: [],
       tabs: [],
     };
   } else {
     navigation = buildNavigation(pages, {
-      chromeVariants: options.navigation.chromeVariants,
+      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/links.ts

@@ -2,7 +2,6 @@ import { existsSync } from "node:fs";
 
 import { basename, join } from "pathe";
 
-import type { AssetMount } from "./assets.ts";
 import type {
   ContentGraph,
   Diagnostic,
@@ -38,25 +37,15 @@ interface ExternalRef extends LinkSite {
 /** Lookups derived once from the content graph. */
 interface LinkContext {
   anchors: Map<string, Set<string>>;
-  /** `content.assets` mounts served alongside `public/` (checked in place). */
-  assetMounts: AssetMount[];
   publicDir: string | null;
   /** Normalized `redirect.from` paths — valid targets that resolve at runtime. */
   redirects: Set<string>;
   routes: Set<string>;
 }
 
-/** Whether a resolved asset path exists under `public/` or an asset mount. */
-const assetIsPresent = (resolved: string, ctx: LinkContext): boolean => {
-  if (ctx.publicDir && existsSync(join(ctx.publicDir, resolved))) {
-    return true;
-  }
-  return ctx.assetMounts.some(
-    (mount) =>
-      (resolved === mount.url || resolved.startsWith(`${mount.url}/`)) &&
-      existsSync(join(mount.dir, resolved.slice(mount.url.length)))
-  );
-};
+/** Whether a resolved asset path exists under `public/`. */
+const assetIsPresent = (resolved: string, ctx: LinkContext): boolean =>
+  ctx.publicDir !== null && existsSync(join(ctx.publicDir, resolved));
 
 /** Outcome of classifying one link target. */
 type LinkResult = Diagnostic | "asset-unchecked" | null;
@@ -165,8 +154,8 @@ const checkPathLink = (
     if (assetIsPresent(resolved, ctx)) {
       return null;
     }
-    // Nowhere to look: no `public/` and no asset mounts configured.
-    if (ctx.publicDir === null && ctx.assetMounts.length === 0) {
+    // Nowhere to look: no `public/` directory.
+    if (ctx.publicDir === null) {
       return "asset-unchecked";
     }
     return {
@@ -347,15 +336,12 @@ export const validateLinks = async (
   options: {
     publicDir: string | null;
     checkExternal?: boolean;
-    /** `content.assets` mounts served alongside `public/`. */
-    assetMounts?: AssetMount[];
     /** Configured redirects; their `from` paths count as valid link targets. */
     redirects?: { from: string }[];
   }
 ): Promise<Diagnostic[]> => {
   const ctx: LinkContext = {
     anchors: buildAnchorIndex(graph.pages),
-    assetMounts: options.assetMounts ?? [],
     publicDir: options.publicDir,
     redirects: new Set(
       (options.redirects ?? []).map((redirect) => toRoute(redirect.from))

package/src/core/meta.ts

@@ -39,7 +39,7 @@ export const discoverFolderMeta = async (
     absolute: true,
     cwd: contentRoot,
     // Never descend into dependencies or build output — relevant when the
-    // content root is the project root (e.g. a migrated Mintlify project).
+    // content root is the project root (e.g. a `.`-rooted or all-staged project).
     ignore: ["**/node_modules/**", "**/.blume/**", "**/dist/**"],
     onlyFiles: true,
   });

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,7 +6,7 @@ import type {
   SidebarItemConfig,
 } from "./schema.ts";
 import type {
-  NavChromeVariant,
+  FeaturedLink,
   NavNode,
   Navigation,
   NavSelector,
@@ -59,7 +59,6 @@ interface MutableGroup {
   label: string;
   icon?: string;
   collapsed?: boolean;
-  display?: SidebarDisplay;
   order: number;
   children: MutableNode[];
   index: Map<string, MutableGroup>;
@@ -141,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]));
@@ -175,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,
@@ -189,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,
@@ -204,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);
 
@@ -247,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 => {
@@ -276,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[] = [];
 
@@ -301,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,8 +363,10 @@ const buildConfigSidebar = (
 export const buildNavigation = (
   pages: PageRecord[],
   options: {
-    chromeVariants?: NavChromeVariant[];
     folderMeta: Map<string, FolderMeta>;
+    /** Global display mode for every sidebar group (default `flat`). */
+    display?: SidebarDisplay;
+    featured?: FeaturedLink[];
     selectors?: NavSelector[];
     tabs?: NavTab[];
     sidebar?: SidebarItemConfig[];
@@ -363,9 +382,10 @@ export const buildNavigation = (
     sharedFolderMeta?: Map<string, FolderMeta>;
   }
 ): Navigation => {
-  const chromeVariants = options.chromeVariants ?? [];
+  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(
@@ -377,21 +397,22 @@ export const buildNavigation = (
 
   if (options.sidebar) {
     return {
-      chromeVariants,
+      featured,
       selectors,
-      sidebar: buildConfigSidebar(options.sidebar, byRoute),
+      sidebar: buildConfigSidebar(options.sidebar, byRoute, display),
       tabs,
     };
   }
 
   return {
-    chromeVariants,
+    featured,
     selectors,
     sidebar: buildFileSystemSidebar(
       pages,
       options.folderMeta,
       sharedFolderMeta,
-      metaPrefix
+      metaPrefix,
+      display
     ),
     tabs,
   };

package/src/core/project-graph.ts

@@ -1,5 +1,4 @@
 import { loadConfig } from "./config.ts";
-import type { ConfigBridge } from "./config.ts";
 import { buildContentGraph } from "./graph.ts";
 import { i18nDiagnostics } from "./i18n.ts";
 import {
@@ -69,8 +68,6 @@ export interface BlumeProject {
   diagnostics: Diagnostic[];
   /** The instantiated content sources, for lazy entry reads (search/AI/raw). */
   sources: ContentSource[];
-  /** Set when serving a foreign docs config (e.g. Mintlify) without migrating. */
-  bridge: ConfigBridge | null;
 }
 
 /**
@@ -97,7 +94,6 @@ export const scanProject = async (
   const configResult = await loadConfig(root, {
     devServerUrl: options.devServerUrl,
   });
-  const { bridge } = configResult;
   const config = applyConfigOverrides(configResult.config, options.overrides);
   const context = resolveProjectContext(root, config, {
     runtimeDir: options.runtimeDir,
@@ -179,7 +175,6 @@ export const scanProject = async (
   const i18nWarnings = config.i18n ? i18nDiagnostics(pages, config.i18n) : [];
 
   return {
-    bridge,
     config,
     context,
     diagnostics: [