blume 1.1.4 → 1.2.0

package/src/components/islands/ask-ai.tsx

@@ -65,7 +65,7 @@ const nextId = (): number => {
 
 // The endpoint and page path both honor the deployment `base` so grounding works
 // under a non-root base path (the server matches base-less document routes).
-const ASK_ENDPOINT = joinBase(import.meta.env.BASE_URL, "api/ask");
+const DEFAULT_ASK_ENDPOINT = joinBase(import.meta.env.BASE_URL, "api/ask");
 
 /** The current route with the deployment base stripped, for page-context lookup. */
 const currentPath = (): string =>
@@ -133,10 +133,12 @@ const ANSWER_CLASS =
   "prose prose-sm max-w-none text-foreground [&_a]:inline-flex [&_a]:items-center [&_a]:gap-1 [&_a]:rounded-full [&_a]:bg-muted [&_a]:px-2 [&_a]:py-1 [&_a]:align-middle [&_a]:font-medium [&_a]:text-[0.7rem] [&_a]:leading-none [&_a]:text-muted-foreground! [&_a]:no-underline! [&_a:hover]:text-foreground!";
 
 const AskAI = ({
+  endpoint = DEFAULT_ASK_ENDPOINT,
   icons = EMPTY_ICONS,
   strings,
   suggestions = EMPTY_SUGGESTIONS,
 }: {
+  endpoint?: string;
   icons?: AskIcons;
   strings?: UIStrings["ask"];
   suggestions?: Suggestion[];
@@ -268,7 +270,7 @@ const AskAI = ({
     abortRef.current = controller;
 
     try {
-      const response = await fetch(ASK_ENDPOINT, {
+      const response = await fetch(endpoint, {
         body: JSON.stringify({
           messages: history.map((m) => ({ content: m.content, role: m.role })),
           page: { path: currentPath() },

package/src/components/islands/hooks.ts

@@ -139,7 +139,12 @@ export interface UseAskAI {
   reset: () => void;
 }
 
-const ASK_ENDPOINT = joinBase(import.meta.env.BASE_URL, "api/ask");
+const DEFAULT_ASK_ENDPOINT = joinBase(import.meta.env.BASE_URL, "api/ask");
+
+export interface UseAskAIOptions {
+  /** Existing Ask AI endpoint; defaults to Blume's generated `/api/ask`. */
+  endpoint?: string;
+}
 
 /** Shown as the assistant's answer when the request fails or throws. */
 const ASK_ERROR = "Something went wrong answering that. Please try again.";
@@ -152,7 +157,8 @@ const currentPath = (): string =>
  * Stream answers from the Ask AI endpoint. Mirrors the built-in Ask AI island so
  * a custom chat UI shares the same grounded, page-aware backend.
  */
-export const useAskAI = (): UseAskAI => {
+export const useAskAI = (options: UseAskAIOptions = {}): UseAskAI => {
+  const endpoint = options.endpoint ?? DEFAULT_ASK_ENDPOINT;
   const [messages, setMessages] = useState<AskMessage[]>([]);
   const [loading, setLoading] = useState(false);
   // The stream writes into the conversation via state updates, so `reset()`
@@ -186,7 +192,7 @@ export const useAskAI = (): UseAskAI => {
       setMessages([...history, assistant]);
       setLoading(true);
       try {
-        const response = await fetch(ASK_ENDPOINT, {
+        const response = await fetch(endpoint, {
           body: JSON.stringify({
             messages: history,
             page: { path: currentPath() },
@@ -239,7 +245,7 @@ export const useAskAI = (): UseAskAI => {
         }
       }
     },
-    [loading, messages]
+    [endpoint, loading, messages]
   );
 
   // Retained for the compiler-off opt-out path (`react: { compiler: false }`):

package/src/components/layout/NavTree.astro

@@ -129,29 +129,43 @@ const initialId =
       </div>
       {panels.map((panel) => (
         <div data-nav-panel={panel.id} hidden={panel.id !== initialId}>
-          <div class="mb-3 flex items-center gap-1.5">
-            <button
-              aria-label={n.back}
-              class="-ml-1 flex shrink-0 items-center justify-center rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
-              data-nav-back={panel.parentId}
-              type="button"
-            >
-              <Icon class="rtl:-scale-x-100" name="arrow-left" size={16} />
-            </button>
-            {panel.route ? (
+          {/* The title is the only sidebar link to the section's own page, so
+              a routed panel keeps it as a link; without a route the whole row
+              becomes the back button. Either way every part of the row is
+              interactive. */}
+          {panel.route ? (
+            <div class="mb-3 flex items-center gap-0.5">
+              <button
+                aria-label={n.back}
+                class="-ml-1 flex shrink-0 items-center justify-center self-stretch rounded px-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+                data-nav-back={panel.parentId}
+                type="button"
+              >
+                <Icon class="rtl:-scale-x-100" name="arrow-left" size={16} />
+              </button>
               <a
                 aria-current={panel.route === currentRoute ? "page" : undefined}
-                class="flex-1 truncate font-semibold text-foreground text-sm hover:underline"
+                class="flex-1 truncate rounded px-1 py-1 font-semibold text-foreground text-sm transition-colors hover:bg-muted"
                 href={withBase(panel.route)}
               >
                 {panel.label}
               </a>
-            ) : (
-              <span class="flex-1 truncate font-semibold text-foreground text-sm">
-                {panel.label}
-              </span>
-            )}
-          </div>
+            </div>
+          ) : (
+            <button
+              aria-label={`${n.back}: ${panel.label}`}
+              class="-ml-1 mb-3 flex w-full items-center gap-1.5 rounded p-1 text-left font-semibold text-foreground text-sm transition-colors hover:bg-muted"
+              data-nav-back={panel.parentId}
+              type="button"
+            >
+              <Icon
+                class="shrink-0 text-muted-foreground rtl:-scale-x-100"
+                name="arrow-left"
+                size={16}
+              />
+              <span class="flex-1 truncate">{panel.label}</span>
+            </button>
+          )}
           <Self
             currentRoute={currentRoute}
             depth={1}
@@ -236,7 +250,7 @@ const initialId =
           const open = active || item.collapsed === false;
           return (
             <li class={spacing}>
-              <details class="group" open={open}>
+              <details open={open}>
                 <summary class="flex cursor-pointer list-none items-center gap-1.5 rounded-[0.65rem] px-2.5 py-1.5 text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground [&::-webkit-details-marker]:hidden">
                   {item.route ? (
                     <a
@@ -273,7 +287,11 @@ const initialId =
                       )}
                     </>
                   )}
-                  <span class="shrink-0 text-muted-foreground transition-transform group-open:rotate-90">
+                  {/* Scope the rotation to this group's own `details` — the
+                      `group-open` variant matches any open ancestor `.group`,
+                      so nested chevrons rotated while their own group stayed
+                      closed. */}
+                  <span class="shrink-0 text-muted-foreground transition-transform [details[open]>summary_&]:rotate-90">
                     <Icon name="chevron-right" size={13} />
                   </span>
                 </summary>

package/src/components/layout/ReferenceLayout.astro

@@ -53,6 +53,8 @@ interface Props {
   fontCssVars?: string[];
   searchEnabled: boolean;
   pageTitle: string;
+  /** Keep the reference route out of crawler indexes. */
+  noindex?: boolean;
   /** Active locale code for `<html lang>` (defaults to `en`). */
   locale?: string;
   /** Text direction for `<html dir>` (defaults to `ltr`). */
@@ -74,6 +76,7 @@ const {
   fontCssVars,
   searchEnabled,
   pageTitle,
+  noindex = false,
   locale = "en",
   dir = "ltr",
   ui,
@@ -89,6 +92,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
+    {noindex && <meta name="robots" content="noindex" />}
     <title>{pageTitle}</title>
     <Favicon favicon={favicon} appleIcon={appleIcon} />
     <Fonts cssVars={fontCssVars ?? []} />

package/src/components/layout/RootLayout.astro

@@ -359,7 +359,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
 ---
 
 <!doctype html>
-<html dir={dir} lang={locale}>
+<html data-pagefind-ignore={indexable ? undefined : "all"} dir={dir} lang={locale}>
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />

package/src/components/openapi/SchemaProperty.astro

@@ -99,10 +99,10 @@ const expandable =
   }
   {
     expandable && (
-      <details class="group mt-2" open={expandAll}>
+      <details class="mt-2" open={expandAll}>
         <summary class="cursor-pointer select-none text-accent text-xs hover:underline">
-          <span class="group-open:hidden">Show properties</span>
-          <span class="hidden group-open:inline">Hide properties</span>
+          <span class="[details[open]>summary_&]:hidden">Show properties</span>
+          <span class="hidden [details[open]>summary_&]:inline">Hide properties</span>
         </summary>
         <div class="mt-2 border-border border-l pl-4">
           <SchemaTable

package/src/core/config-input.ts

@@ -1,3 +1,4 @@
+import type { AstroIntegration } from "astro";
 import type { z } from "zod";
 
 import type { ComponentMarkdown } from "../ai/component-markdown.ts";
@@ -290,6 +291,15 @@ export interface NavTabItem {
 
 /** A top-level tab in the header, optionally opening a dropdown of items. */
 export interface NavTab {
+  /**
+   * Where the tab links to, when that differs from `path`. `path` scopes the
+   * sidebar section and matches the active tab; without `href`, a section whose
+   * `path` isn't itself a page falls back to the section's first page, or keeps
+   * `path` when the section has no linkable page at all. Set this to send
+   * readers somewhere else — e.g. a generated `/changelog` index, or a custom
+   * `.astro` landing page, neither of which is part of the content tree.
+   */
+  href?: string;
   /** Lucide icon name shown beside the label. */
   icon?: string;
   /** Dropdown items; omit for a plain link tab. */
@@ -522,6 +532,12 @@ export interface AskConfig {
   baseUrl?: string;
   /** Turn Ask AI on. Defaults to `false`. */
   enabled?: boolean;
+  /**
+   * Existing Ask AI endpoint to call instead of generating one. This keeps a
+   * Blume site static while an API backend owns retrieval, model access, rate
+   * limiting, and streaming. Accepts an absolute URL or root-relative path.
+   */
+  endpoint?: string;
   /** Model id to use. Defaults to `openai/gpt-5.5`. */
   model?: string;
   /** Which backend routes the request. Defaults to `gateway`. */
@@ -1115,6 +1131,8 @@ export interface BlumeConfig {
   github?: GithubConfig;
   /** Internationalization (opt-in multi-locale). */
   i18n?: I18nConfig;
+  /** Astro integrations appended after Blume's built-ins, in declaration order. */
+  integrations?: AstroIntegration[];
   /** "Last updated" timestamps from git history or frontmatter. Defaults to `false`. */
   lastModified?: LastModifiedConfig;
   /** Site logo / brand mark. */

package/src/core/config.ts

@@ -84,6 +84,10 @@ import type { Diagnostic } from "./types.ts";
  * - `analytics` — PostHog, Vercel, or arbitrary `scripts` (Plausible, Fathom,
  *   GA, …).
  *
+ * **Astro**
+ * - `integrations` — Astro integrations appended after Blume's built-ins, in
+ *   declaration order. Install and maintain each integration in the site.
+ *
  * **Deployment & i18n**
  * - `deployment` — `site` URL (needed for absolute links, sitemaps, and OG),
  *   `adapter` (`vercel`/`node`/`netlify`/`cloudflare`), `output`

package/src/core/data.ts

@@ -95,6 +95,7 @@ export interface BlumeDataConfig {
   appleIcon: BlumeFavicon | null;
   /** Ask AI empty-state suggestions, or `null` when Ask AI is off. */
   ask: {
+    endpoint: string | null;
     suggestions: NonNullable<ResolvedConfig["ai"]["ask"]>["suggestions"];
   } | null;
   banner: BlumeBanner | null;

package/src/core/graph.ts

@@ -97,6 +97,7 @@ const buildLocaleNavigation = (
     path.startsWith("/") ? localizeRoute(path, code, i18n) : path;
   const tabs = options.navigation.tabs?.map((tab) => ({
     ...tab,
+    ...(tab.href ? { href: localizePath(tab.href) } : {}),
     items: tab.items?.map((item) => ({
       ...item,
       path: localizePath(item.path),

package/src/core/navigation.ts

@@ -613,10 +613,16 @@ const resolveTabHref = (sidebar: NavNode[], path: string): string => {
   return walk(sidebar) ? path : (first ?? path);
 };
 
-/** Attach a resolved `href` to each tab whose section has no index page. */
+/**
+ * Attach a resolved `href` to each tab whose section has no index page. An
+ * author-declared `href` is the tab's stated target, so it's kept as-is —
+ * resolution only fills in the tabs that didn't declare one. That's what lets a
+ * tab point at a route outside the content tree (a generated `/changelog`
+ * index, a custom `.astro` page), which resolution can't see.
+ */
 const withTabHrefs = (tabs: NavTab[], sidebar: NavNode[]): NavTab[] =>
   tabs.map((tab) => {
-    const href = resolveTabHref(sidebar, tab.path);
+    const href = tab.href ?? resolveTabHref(sidebar, tab.path);
     return href === tab.path ? tab : { ...tab, href };
   });
 
@@ -688,6 +694,7 @@ export const buildNavigation = (
   const tabs = basePath
     ? (options.tabs ?? []).map((tab) => ({
         ...tab,
+        ...(tab.href ? { href: withBasePath(basePath, tab.href) } : {}),
         items: tab.items?.map(rebasePath),
         path: withBasePath(basePath, tab.path),
       }))

package/src/core/schema.ts

@@ -1,3 +1,4 @@
+import type { AstroIntegration } from "astro";
 import { z } from "zod";
 
 import type { ComponentMarkdown } from "../ai/component-markdown.ts";
@@ -78,6 +79,11 @@ const searchMetaSchema = z.strictObject({
   tags: z.array(z.string()).optional(),
 });
 
+const aiMetaSchema = z.strictObject({
+  /** Exclude this page from llms.txt and llms-full.txt. */
+  exclude: z.boolean().default(false),
+});
+
 const changelogMetaSchema = z.strictObject({
   category: z.string().optional(),
   date: dateSchema.optional(),
@@ -105,6 +111,7 @@ const authorSchema = z.union([
 
 /** Frontmatter accepted on any content page. */
 const pageMetaBaseSchema = z.strictObject({
+  ai: aiMetaSchema.default({}),
   /** Post author(s) for blog/changelog content; preserved, not yet rendered. */
   authors: z.union([authorSchema, z.array(authorSchema)]).optional(),
   changelog: changelogMetaSchema.optional(),
@@ -351,6 +358,10 @@ const contentConfigSchema = z.strictObject({
 });
 
 const navTabSchema = z.strictObject({
+  // Rejected empty rather than accepted: an empty `href` would render a link to
+  // nowhere, and it can't mean "resolve it for me" either — that's what
+  // omitting the field does.
+  href: z.string().min(1).optional(),
   icon: iconName.optional(),
   items: z
     .array(
@@ -575,18 +586,44 @@ const mcpConfigSchema = z.strictObject({
   route: z.string().default("/mcp").transform(normalizeRoute),
 });
 
+const askEndpointSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .refine(
+    (value) => {
+      if (value.startsWith("/") && !value.startsWith("//")) {
+        return true;
+      }
+      try {
+        const url = new URL(value);
+        return url.protocol === "http:" || url.protocol === "https:";
+      } catch {
+        return false;
+      }
+    },
+    {
+      message:
+        "ai.ask.endpoint must be an HTTP(S) URL or a root-relative path.",
+    }
+  );
+
 const aiConfigSchema = z.strictObject({
   ask: z
     .strictObject({
       // Name of the env var holding the provider's API key; each provider has
       // a sensible default, so this only needs setting to override it.
       apiKeyEnv: z.string().optional(),
-      // Base URL of the backend. Required for `openai-compatible`; for the
-      // named providers it overrides the built-in preset.
+      // Base URL of the backend. Required for `openai-compatible` only when no
+      // external endpoint is supplied; for named providers it overrides the preset.
       // blume bundles Zod 3; top-level `z.url()` is undefined at runtime.
       // oxlint-disable-next-line react-doctor/zod-v4-prefer-top-level-string-formats
       baseUrl: z.string().url().optional(),
       enabled: z.boolean().default(false),
+      // Optional external endpoint for projects that keep their docs static
+      // and host Ask AI in an existing backend. Absolute URLs and root-relative
+      // paths are both valid; the built-in request/stream contract is unchanged.
+      endpoint: askEndpointSchema.optional(),
       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
@@ -603,7 +640,10 @@ const aiConfigSchema = z.strictObject({
     .superRefine((value, ctx) => {
       // A generic OpenAI-compatible backend has no preset URL, so the user
       // must supply one; the named providers fall back to their preset.
-      if (value.provider === "openai-compatible" && !value.baseUrl) {
+      if (
+        value.provider === "openai-compatible" &&
+        !(value.baseUrl || value.endpoint)
+      ) {
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
           message:
@@ -1118,15 +1158,21 @@ const reactConfigSchema = z.strictObject({
  * `http(s)` URL (OpenAPI for the Blume renderer; OpenAPI or AsyncAPI for Scalar).
  */
 const openapiSourceSchema = z.strictObject({
+  /** Include generated pages from this spec in llms.txt/llms-full.txt. */
+  includeInLlms: z.boolean().default(true),
+  /** Include generated pages from this spec in site search. */
+  includeInSearch: z.boolean().default(true),
   /** Nav/section label for this source. */
   label: z.string().optional(),
+  /** Emit noindex metadata and omit generated pages from the sitemap. */
+  noindex: z.boolean().default(false),
   /** Per-source route; defaults to the block's `route` (or a derived path). */
   route: z.string().optional(),
   /** Local path or `http(s)` URL to the spec. */
   spec: z.string(),
 });
 
-export type OpenApiSource = z.infer<typeof openapiSourceSchema>;
+export type OpenApiSource = z.input<typeof openapiSourceSchema>;
 
 /**
  * Arbitrary Scalar API-reference options forwarded verbatim to the generated
@@ -1283,6 +1329,7 @@ export const blumeConfigSchema = z.strictObject({
   frontmatter: frontmatterConfigSchema.default({}),
   github: githubConfigSchema.optional(),
   i18n: i18nConfigSchema.optional(),
+  integrations: z.array(z.custom<AstroIntegration>()).default([]),
   lastModified: lastModifiedConfigSchema.default(false),
   logo: logoConfigSchema.optional(),
   markdown: markdownConfigSchema.default({}),

package/src/core/server-features.ts

@@ -7,7 +7,7 @@ import type { ResolvedConfig } from "./schema.ts";
  */
 export const serverFeatures = (config: ResolvedConfig): string[] => {
   const features: string[] = [];
-  if (config.ai.ask?.enabled) {
+  if (config.ai.ask?.enabled && !config.ai.ask.endpoint) {
     features.push("Ask AI");
   }
   // The hosted MCP server is a live JSON-RPC endpoint, so it needs a runtime.

package/src/core/types.ts

@@ -201,9 +201,11 @@ export interface NavTab {
    */
   path: string;
   /**
-   * The clickable target. Equals `path` when the section has an index page;
-   * otherwise it's resolved to the section's first page so the tab never links
-   * to a 404. Absent when it matches `path`.
+   * The clickable target. Author-declared when the config sets it; otherwise
+   * equals `path` when the section has an index page, and resolves to the
+   * section's first page when it doesn't, so the tab doesn't link to a 404 as
+   * long as the section has a page to offer — a section with no linkable page at
+   * all keeps `path`. Absent when a resolved target matches `path`.
    */
   href?: string;
   icon?: string;