blume 0.6.6 → 0.7.0

package/dist/types/core/types.d.ts

@@ -162,10 +162,14 @@ export interface NavSelectorItem {
     icon?: string;
     tag?: string;
 }
+/** Context-partition selector kinds (a versioned/localized/multi-product site). */
+type NavSelectorContextKind = "product" | "version";
+/** What a top-level partition selector switches between. */
+type NavSelectorKind = "dropdown" | "language" | NavSelectorContextKind;
 /** Top-level partition selectors (products, versions, languages). */
 export interface NavSelector {
     label: string;
-    kind: "dropdown" | "language" | "product" | "version";
+    kind: NavSelectorKind;
     items: NavSelectorItem[];
 }
 /** A pinned link rendered above the sidebar sections (external or internal). */
@@ -252,3 +256,4 @@ export interface BlumeManifest {
     output: ResolvedConfig["deployment"]["output"];
     routes: RouteManifestEntry[];
 }
+export {};

package/docs/02-deployment.mdx

@@ -54,7 +54,7 @@ blume preview
 
 ## Subpath deploys
 
-Serving docs under a path like `example.com/docs`? Set `deployment.base` — common for GitHub Pages project sites. Internal links and assets are rewritten to include the base path.
+Serving docs under a path like `example.com/docs`? Set `deployment.base` — common for GitHub Pages project sites. The whole site, root included, moves under the base, and internal links and assets are rewritten to include it.
 
 ```ts blume.config.ts lineNumbers
 deployment: {
@@ -62,6 +62,21 @@ deployment: {
 }
 ```
 
+## Mount the docs under a path
+
+`basePath` mounts every generated route under a segment (`/docs/getting-started`) while leaving the sidebar untouched — the top level is your sections, not a wrapper group. Use it when the docs live at `/docs/*` but the site root stays yours (like Docusaurus `routeBasePath` or Fumadocs `baseUrl`).
+
+```ts blume.config.ts lineNumbers
+basePath: "/docs",
+```
+
+Write links as if mounted at root (`/getting-started`); Blume rewrites them, along with redirects, the sitemap, canonical URLs, Open Graph images, `llms.txt`, and the search index. Public assets (images, files under `public/`) stay at the site root.
+
+This is a distinct concept from the two paths above:
+
+- A per-source [`prefix`](/docs/content/sources#multiple-sources) namespaces **one** source and **does** add a sidebar group.
+- `deployment.base` is the host subdirectory the **whole** app is served from. The two compose — with both set, a page lands at `{deployment.base}/{basePath}/page`.
+
 ## Server rendering
 
 Static output covers most docs. Switch to server output when you need request-time features — most notably the [Ask AI](/docs/configuration/ai) endpoint:

package/docs/03-faq.mdx

@@ -87,13 +87,13 @@ We reported it upstream in [oxc-project/oxc#24096](https://github.com/oxc-projec
 
 Patch oxfmt so it preserves the line break that sits directly against a `:::` fence. Blume ships exactly this patch in its own repo, and you can apply the same one in any project.
 
-1. Save the patch as `patches/oxfmt@0.55.0.patch`:
+1. Save the patch as `patches/oxfmt@0.57.0.patch`:
 
-   ```diff patches/oxfmt@0.55.0.patch
-   diff --git a/dist/markdown-Bowe09rB.js b/dist/markdown-Bowe09rB.js
-   index 0fe63ff712e07c9c2188711fa0940f7a7d8f7d74..44435d91a2f5a6711512981c9bcaddedc1760be4 100644
-   --- a/dist/markdown-Bowe09rB.js
-   +++ b/dist/markdown-Bowe09rB.js
+   ```diff patches/oxfmt@0.57.0.patch
+   diff --git a/dist/markdown-B5hFVJKQ.js b/dist/markdown-B5hFVJKQ.js
+   index 58322b247b263f87975c2a97eecfe0b97d7143c4..0f39f1901603026a391c6d343cb838dfaccbfd03 100644
+   --- a/dist/markdown-B5hFVJKQ.js
+   +++ b/dist/markdown-B5hFVJKQ.js
    @@ -1141,7 +1141,14 @@ function Yf(e, r, t) {
     		case "sentence": return Yi(e, t);
     		case "word": return Li(e);
@@ -117,7 +117,7 @@ Patch oxfmt so it preserves the line break that sits directly against a `:::` fe
    ```json package.json
    {
      "patchedDependencies": {
-       "oxfmt@0.55.0": "patches/oxfmt@0.55.0.patch"
+       "oxfmt@0.57.0": "patches/oxfmt@0.57.0.patch"
      }
    }
    ```
@@ -128,5 +128,5 @@ Patch oxfmt so it preserves the line break that sits directly against a `:::` fe
    bun install
    ```
 
-:::warning[Version-pinned] The patch targets oxfmt `0.55.0` — its diff references a file hashed to that build (`dist/markdown-Bowe09rB.js`). When you bump oxfmt, regenerate the patch (e.g. `bun patch oxfmt`) or check whether the upstream fix has landed and the patch is no longer needed.
+:::warning[Version-pinned] The patch targets oxfmt `0.57.0` — its diff references a file hashed to that build (`dist/markdown-B5hFVJKQ.js`). When you bump oxfmt, regenerate the patch (e.g. `bun patch oxfmt`) or check whether the upstream fix has landed and the patch is no longer needed.
 :::

package/docs/configuration/index.mdx

@@ -53,6 +53,12 @@ export default defineConfig({
       icons: true, // language icon in the code-block header
       wrap: false, // wrap long lines instead of scrolling
     },
+    codeBlocks: {
+      theme: {
+        light: "github-light", // any bundled Shiki theme
+        dark: "github-dark",
+      },
+    },
   },
 
   // AI — see the AI guide

package/docs/content/components.mdx

@@ -546,7 +546,33 @@ A card linking to a GitHub repository with its live star and fork counts. Counts
 
 `Component` renders an example file from your project's `examples/` directory as a live preview alongside its highlighted source, in tabs. Point it at a file with `path` — its location under `examples/`, without the extension (so `examples/counter.tsx` is `path="counter"`). React, Vue, Svelte, and Astro examples are all supported; framework examples hydrate, Astro ones render statically. It keeps the preview and the code in sync from a single file.
 
-The directory is configurable — set `examples` in `blume.config.ts` when your examples live elsewhere (e.g. a registry layout). `path` is always relative to it:
+The preview renders in an isolated frame that the docs styles never reach — no prose margins, typography, or theme chrome bleed into your component. The frame gets Tailwind (preflight + utilities scanned from your example files and anything they import), Blume's design tokens so classes like `bg-background` follow the site palette by default, and it follows the site's light/dark toggle live.
+
+To style previews with your own design system — say, shadcn variables — point `examples.css` at a stylesheet. It's injected into every preview frame after Blume's defaults, so your tokens win. Don't `@import "tailwindcss"` in it; the frame already provides Tailwind. Both `.dark` and `[data-theme="dark"]` work for dark-mode overrides:
+
+```ts
+// blume.config.ts
+export default defineConfig({
+  examples: { css: "examples/theme.css" },
+});
+```
+
+```css
+/* examples/theme.css */
+:root {
+  --primary: oklch(0.6 0.2 260);
+}
+
+.dark {
+  --primary: oklch(0.75 0.15 260);
+}
+
+@theme inline {
+  --color-primary: var(--primary);
+}
+```
+
+The directory is configurable too — set `source` (or use the string shorthand, `examples: "..."`) when your examples live elsewhere (e.g. a registry layout). `path` is always relative to it:
 
 ```ts
 // blume.config.ts
@@ -593,6 +619,7 @@ An Astro example renders live with no client JavaScript:
 
 <CodeBlock
   lang="ts"
+  icons={false}
   code={`export const greet = (name: string): string =>
   \`Hello, \${name}!\`;`}
 />
@@ -602,7 +629,7 @@ An Astro example renders live with no client JavaScript:
 import CodeBlock from "blume/components/content/CodeBlock.astro";
 ---
 
-<CodeBlock lang="ts" code={source} />
+<CodeBlock lang="ts" code={source} icons={false} />
 ```
 
 To highlight to an HTML string yourself (e.g. inside your own component), import the underlying helper from `blume/markdown`:

package/docs/content/islands.mdx

@@ -77,6 +77,14 @@ export default function Chart() {
 
 **React works out of the box** — Blume turns it on automatically the moment your project contains a `.tsx`/`.jsx` island.
 
+The [React Compiler](https://react.dev/learn/react-compiler) is on by default whenever React is enabled, so your islands are auto-memoized — no hand-written `useMemo`/`useCallback` needed. It ships with Blume; there's nothing to install. Opt out in `blume.config.ts`:
+
+```ts blume.config.ts
+export default defineConfig({
+  react: { compiler: false },
+});
+```
+
 **Vue and Svelte** are supported too; install the matching Astro integration and Blume wires up the renderer when it sees a `.vue` or `.svelte` island:
 
 ```bash

package/docs/content/syntax.mdx

@@ -33,6 +33,7 @@ For footnote markers, ordinals, and scientific or chemical notation inline.
 
 E = mc^2^ and H~2~O.
 
+{/* prettier-ignore */}
 ```md
 E = mc^2^ and H~2~O.
 ```
@@ -141,6 +142,18 @@ export default defineConfig({
 
 Inline code can be highlighted too: add a `{:lang}` marker inside a backtick span and it's colored like a tiny code block — `useState(){:js}` or `T extends object{:ts}`. It only kicks in when you add the marker, so plain inline code stays untouched — nothing to switch on.
 
+Highlighting uses the `github-light`/`github-dark` themes by default. Swap in any [bundled Shiki theme](https://shiki.style/themes) per color mode with `markdown.codeBlocks.theme` — it colors every code surface at once (fences, inline snippets, `<CodeBlock>`, and `<Diff>`):
+
+```ts blume.config.ts
+export default defineConfig({
+  markdown: {
+    codeBlocks: {
+      theme: { light: "github-light", dark: "vesper" },
+    },
+  },
+});
+```
+
 ### Line numbers
 
 Append `lineNumbers` to render a line-number gutter — on its own or alongside a title:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "0.6.6",
+  "version": "0.7.0",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -89,6 +89,7 @@
     "@vercel/analytics": "^2.0.1",
     "ai": "^5.0.0",
     "astro": "^7.0.2",
+    "babel-plugin-react-compiler": "^1.0.0",
     "citty": "^0.1.6",
     "consola": "^3.4.0",
     "deepmerge": "^4.3.1",

package/src/ai/agent-readability.ts

@@ -1,3 +1,4 @@
+import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ContentSignalPolicy, ContentSignals } from "../core/schema.ts";
 import { buildRssFeeds } from "../deploy/rss.ts";
@@ -42,9 +43,13 @@ export const buildAgentReadability = (
   }
 
   const site = config.deployment.site ?? null;
-  // Concatenate rather than `new URL()` so a subpath deployment's base is kept.
+  // Every artifact is served under `deployment.base`; concatenate rather than
+  // `new URL()` so the subpath is preserved.
+  const deployBase = normalizeBasePath(config.deployment.base);
   const abs = (path: string): string =>
-    site ? `${site.replace(/\/+$/u, "")}${path}` : path;
+    site
+      ? `${site.replace(/\/+$/u, "")}${withBasePath(deployBase, path)}`
+      : path;
 
   const artifacts: Record<string, unknown> = {
     markdown: {

package/src/ai/ask.ts

@@ -30,20 +30,25 @@ interface AskPreset {
  * dedicated AI SDK provider; LLMGateway and Inkeep are OpenAI-compatible
  * endpoints with no dedicated provider, so they reuse `@ai-sdk/openai-compatible`.
  */
+/** The discriminant/name shared by the OpenAI-compatible providers. */
+const OPENAI_COMPATIBLE = "openai-compatible";
+/** The AI SDK provider package the OpenAI-compatible providers install. */
+const OPENAI_COMPATIBLE_DEP = "@ai-sdk/openai-compatible";
+
 const ASK_PRESETS: Record<string, AskPreset> = {
   inkeep: {
     apiKeyEnv: "INKEEP_API_KEY",
     baseUrl: "https://api.inkeep.com/v1",
-    kind: "openai-compatible",
+    kind: OPENAI_COMPATIBLE,
     name: "inkeep",
-    runtimeDep: "@ai-sdk/openai-compatible",
+    runtimeDep: OPENAI_COMPATIBLE_DEP,
   },
   llmgateway: {
     apiKeyEnv: "LLMGATEWAY_API_KEY",
     baseUrl: "https://api.llmgateway.io/v1",
-    kind: "openai-compatible",
+    kind: OPENAI_COMPATIBLE,
     name: "llmgateway",
-    runtimeDep: "@ai-sdk/openai-compatible",
+    runtimeDep: OPENAI_COMPATIBLE_DEP,
   },
   openrouter: {
     apiKeyEnv: "OPENROUTER_API_KEY",
@@ -73,9 +78,9 @@ export const resolveAskBackend = (ask?: AskAiConfig): AskBackend => {
   return {
     apiKeyEnv,
     baseUrl: ask?.baseUrl ?? preset?.baseUrl ?? "",
-    kind: "openai-compatible",
+    kind: OPENAI_COMPATIBLE,
     model,
-    name: preset?.name ?? "openai-compatible",
+    name: preset?.name ?? OPENAI_COMPATIBLE,
   };
 };
 
@@ -89,5 +94,5 @@ export const askBackendRuntimeDep = (ask?: AskAiConfig): string | undefined => {
   if (provider === "gateway") {
     return undefined;
   }
-  return ASK_PRESETS[provider]?.runtimeDep ?? "@ai-sdk/openai-compatible";
+  return ASK_PRESETS[provider]?.runtimeDep ?? OPENAI_COMPATIBLE_DEP;
 };

package/src/ai/llms.ts

@@ -1,13 +1,16 @@
+import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import matter from "../core/frontmatter.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { readEntryText } from "../core/sources/read.ts";
 import type { PageRecord } from "../core/types.ts";
 
-const pageUrl = (route: string, site?: string): string => {
+// Routes carry `basePath`; a `deployment.base` subdirectory is layered on top so
+// the emitted URL matches where the page is served.
+const pageUrl = (route: string, site?: string, base = ""): string => {
   if (!site) {
     return route;
   }
-  return `${site.replace(/\/$/u, "")}${route}`;
+  return `${site.replace(/\/$/u, "")}${withBasePath(base, route)}`;
 };
 
 const orderedPages = (project: BlumeProject): PageRecord[] =>
@@ -26,7 +29,11 @@ const buildIndex = (project: BlumeProject): string => {
   lines.push("", "## Docs", "");
 
   for (const page of orderedPages(project)) {
-    const url = pageUrl(page.route, site);
+    const url = pageUrl(
+      page.route,
+      site,
+      normalizeBasePath(config.deployment.base)
+    );
     const summary = page.description ? `: ${page.description}` : "";
     lines.push(`- [${page.title}](${url})${summary}`);
   }
@@ -43,7 +50,11 @@ const buildFull = async (project: BlumeProject): Promise<string> => {
     pages.map(async (page) => {
       const raw = await readEntryText(project, page);
       const body = matter(raw).content.trim();
-      const url = pageUrl(page.route, config.deployment.site);
+      const url = pageUrl(
+        page.route,
+        config.deployment.site,
+        normalizeBasePath(config.deployment.base)
+      );
       return [`# ${page.title}`, `Source: ${url}`, "", body].join("\n");
     })
   );

package/src/ai/mcp/data.ts

@@ -45,16 +45,20 @@ export const buildMcpData = async (project: BlumeProject): Promise<McpData> => {
     graph.pages.map((page) => [page.id, page.description])
   );
 
-  const routes: McpRoute[] = manifest.routes
-    .filter((route) => !route.hidden)
-    .map((route) => ({
+  const routes: McpRoute[] = [];
+  for (const route of manifest.routes) {
+    if (route.hidden) {
+      continue;
+    }
+    routes.push({
       contentType: route.contentType,
       description: descriptionById.get(route.id),
       indexable: route.indexable,
       lastModified: route.lastModified ?? null,
       route: route.path,
       title: route.title,
-    }));
+    });
+  }
 
   return {
     documents: documents.map((doc) => ({

package/src/ai/mcp/server.ts

@@ -209,6 +209,9 @@ export const createMcpFetchHandler = (
     const server = buildServer(data, index);
     const transport = new WebStandardStreamableHTTPServerTransport({
       enableJsonResponse: true,
+      // The SDK enables stateless mode only when this is `undefined`; `null` is
+      // not an accepted value for the `(() => string) | undefined` option.
+      // oxlint-disable-next-line sonarjs/no-undefined-assignment
       sessionIdGenerator: undefined,
     });
     await server.connect(transport);

package/src/astro/component-slots.ts

@@ -41,6 +41,8 @@ export const layoutOverrides = {};
 const attributeValue = (value: string): string =>
   value.replaceAll(/["\n\r]/gu, " ").trim();
 
+const CLIENT_LOAD = "client:load";
+
 /** Astro client directive for a hydrated override. */
 const directiveFor = (override: NormalizedOverride): string => {
   const framework = override.source?.framework;
@@ -54,15 +56,15 @@ const directiveFor = (override: NormalizedOverride): string => {
     case "media": {
       return override.media
         ? `client:media="${attributeValue(override.media)}"`
-        : "client:load";
+        : CLIENT_LOAD;
     }
     case "only": {
       return framework
         ? `client:only="${attributeValue(framework)}"`
-        : "client:load";
+        : CLIENT_LOAD;
     }
     default: {
-      return "client:load";
+      return CLIENT_LOAD;
     }
   }
 };

package/src/astro/examples.ts

@@ -59,10 +59,10 @@ const GLOB_MAGIC = /[!*?[\]{}]/u;
  */
 const splitGlobBase = (pattern: string): { base: string; rest: string } => {
   const segments = pattern.split("/");
+  // Only called when the pattern contains glob magic (see the caller), and `/`
+  // is never magic, so the magic char always lands in a segment — `findIndex`
+  // is never -1 here.
   const firstMagic = segments.findIndex((segment) => GLOB_MAGIC.test(segment));
-  if (firstMagic === -1) {
-    return { base: pattern, rest: "" };
-  }
   return {
     base: segments.slice(0, firstMagic).join("/"),
     rest: segments.slice(firstMagic).join("/"),
@@ -109,11 +109,13 @@ export const discoverExamples = async (
   const warnings: string[] = [];
   const seen = new Map<string, string>();
 
-  for (const [index, file] of files.entries()) {
+  // Extracted so the two skip paths become early `return`s (one `continue`
+  // budget per loop under the lint rule) instead of `continue` statements.
+  const collectExample = (file: string, source: string): void => {
     const ext = file.match(EXAMPLE_FILE)?.groups?.ext;
     const framework = ext ? FRAMEWORK_BY_EXT[ext] : undefined;
     if (!(ext && framework)) {
-      continue;
+      return;
     }
     // Strip the trailing `.<ext>` to form the `<Component path>` key.
     const path = relative(dir, file).slice(0, -(ext.length + 1));
@@ -122,10 +124,9 @@ export const discoverExamples = async (
       warnings.push(
         `Two examples both resolve to "${path}" ("${existing}" and "${file}"); ignoring the second. Give them distinct paths.`
       );
-      continue;
+      return;
     }
     seen.set(path, file);
-    const source = sources[index] ?? "";
     examples.push({
       client:
         framework === "astro"
@@ -137,6 +138,10 @@ export const discoverExamples = async (
       path,
       source,
     });
+  };
+
+  for (const [index, file] of files.entries()) {
+    collectExample(file, sources[index] ?? "");
   }
 
   return { examples, warnings };