blume 0.3.0 → 0.5.0

package/docs/reference/cli.mdx

@@ -9,19 +9,19 @@ blume <command> [options]
 
 ## Commands
 
-| Command                | Description                                            |
-| ---------------------- | ------------------------------------------------------ |
-| `blume init`           | Scaffold a minimal project.                            |
-| `blume dev`            | Start the dev server with hot reload.                  |
-| `blume build`          | Build the static (or server) site.                     |
-| `blume preview`        | Preview the last build.                                |
-| `blume add <item>`     | Install a source component from the registry.          |
-| `blume migrate <tool>` | Migrate from Mintlify, Starlight, Nextra, or Fumadocs. |
-| `blume sync`           | Re-fetch remote content sources and regenerate.        |
-| `blume eject`          | Promote the runtime into a standalone Astro app.       |
-| `blume check`          | Type-check the site with `astro check`.                |
-| `blume doctor`         | Diagnose config and content problems.                  |
-| `blume validate`       | Validate links across your content.                    |
+| Command | Description |
+| --- | --- |
+| `blume init` | Scaffold a minimal project. |
+| `blume dev` | Start the dev server with hot reload. |
+| `blume build` | Build the static (or server) site. |
+| `blume preview` | Preview the last build. |
+| `blume add <item>` | Install a source component from the registry. |
+| [`blume migrate <tool>`](/docs/advanced/migrate) | Migrate from Mintlify, Starlight, Nextra, or Fumadocs. |
+| `blume sync` | Re-fetch remote content sources and regenerate. |
+| `blume eject` | Promote the runtime into a standalone Astro app. |
+| `blume check` | Type-check the site with `astro check`. |
+| `blume doctor` | Diagnose config and content problems. |
+| `blume validate` | Validate links across your content. |
 
 ## Common flags
 
@@ -37,25 +37,47 @@ blume <command> [options]
 - `blume build --output static|server --adapter vercel|node|netlify|cloudflare --base /docs` — override the deployment output, adapter, and base path from `blume.config.ts`.
 - `blume build --analyze` — print the client JavaScript bundle sizes (largest first) after the build.
 - `blume build --budget-js <kb> --budget-css <kb>` — fail the build when total client JavaScript/CSS exceeds the budget, turning a performance target into a CI gate.
+- `blume build --isolated` — build into a throwaway `.blume-verify/` runtime (and its own `dist/`) instead of `.blume/`, so a running `blume dev` server and your real `dist/` are left untouched. See [Verifying while the dev server runs](#verifying-while-the-dev-server-runs).
 - `blume preview --host --port <n>` — bind the preview server.
 - `blume sync --force` — re-fetch remote sources, dropping the cached snapshot first.
 - `blume add <item> --force` — overwrite files that already exist.
 - `blume check --preview` — include drafts and unpublished CMS content when checking.
 - `blume check --strict` — fail on content diagnostics as well as type errors.
+- `blume check --isolated` — type-check in a throwaway `.blume-verify/` runtime so a running `blume dev` server is left untouched. See [Verifying while the dev server runs](#verifying-while-the-dev-server-runs).
 - `blume eject --yes` — skip the confirmation prompt.
 - `blume validate --external` — also check external links over the network.
 - `blume validate --strict` — exit non-zero on warnings too.
-- `blume validate --json` / `blume doctor --json` — emit diagnostics as JSON on
-  stdout (with `code`, `severity`, `file`, `line`/`column`, and `docsUrl`) for CI
-  and editor integrations.
+- `blume validate --json` / `blume doctor --json` — emit diagnostics as JSON on stdout (with `code`, `severity`, `file`, `line`/`column`, and `docsUrl`) for CI and editor integrations.
+
+## Verifying while the dev server runs
+
+`blume dev` serves a live Astro server rooted at the generated `.blume/` runtime and regenerates it on every change. `blume build` and `blume check` regenerate the _same_ `.blume/`, so running either while the dev server is live would corrupt it — both refuse with an error and exit non-zero:
+
+```
+A `blume dev` server is running against .blume; building would corrupt it.
+Stop the dev server, or re-run with --isolated to build/verify against
+.blume-verify without touching it.
+```
+
+The `--isolated` flag is the escape hatch. It relocates the entire generated runtime (and, for `build`, its output `dist/`) to a sibling `.blume-verify/` directory, so the verification never writes anything the dev server — or your real `dist/` — depends on:
+
+```bash
+# In a second terminal, while `blume dev` is running:
+blume check --isolated   # fast: type-check the .astro/config changes
+blume build --isolated   # thorough: full production render into .blume-verify/dist
+```
+
+`check --isolated` is the quick path (Astro type + template diagnostics, no `dist/`); `build --isolated` is the heavier one that also catches runtime render errors. Isolated builds skip the deploy post-steps (search index, hosted-provider sync, `llms.txt`, sitemap/robots, redirects) — a verify only needs to confirm the site compiles and renders, not publish it. Blume adds `.blume-verify/` to your `.gitignore` automatically.
+
+This is especially useful when a coding agent needs to verify changes while you keep the dev server open. To make plain `blume build`/`blume check` isolate without the flag — for example in an agent's shell — set `BLUME_RUNTIME_DIR` to the runtime directory to use:
+
+```bash
+export BLUME_RUNTIME_DIR=.blume-verify
+```
 
 ## Type-checking
 
-`blume check` runs [`astro check`](https://docs.astro.build/en/reference/cli-reference/#astro-check)
-over your project. It regenerates the `.blume` runtime, syncs Astro's content
-types, then reports any TypeScript errors — in your `blume.config.ts`, in custom
-`.astro` pages, and in the components they import. It exits non-zero when there
-are errors, so it works as a `typecheck` step in CI:
+`blume check` runs [`astro check`](https://docs.astro.build/en/reference/cli-reference/#astro-check) over your project. It regenerates the `.blume` runtime, syncs Astro's content types, then reports any TypeScript errors — in your `blume.config.ts`, in custom `.astro` pages, and in the components they import. It exits non-zero when there are errors, so it works as a `typecheck` step in CI:
 
 ```json title="package.json"
 {
@@ -65,8 +87,7 @@ are errors, so it works as a `typecheck` step in CI:
 }
 ```
 
-Add a `tsconfig.json` extending Astro's config to your project root so authored
-pages resolve `blume/*` imports and virtual modules like `blume:data`:
+Add a `tsconfig.json` extending Astro's config to your project root so authored pages resolve `blume/*` imports and virtual modules like `blume:data`:
 
 ```json title="tsconfig.json"
 {
@@ -81,11 +102,7 @@ Without a project `tsconfig.json`, only the generated runtime is checked.
 
 `blume validate` checks every link discovered in your content:
 
-- **Internal page links** (`/guides/intro`, `./sibling`) must resolve to a real
-  page — broken ones are reported as errors.
-- **Anchor links** (`#section`, `/guides/intro#setup`) must match a heading on
-  the target page — misses are warnings.
+- **Internal page links** (`/guides/intro`, `./sibling`) must resolve to a real page — broken ones are reported as errors.
+- **Anchor links** (`#section`, `/guides/intro#setup`) must match a heading on the target page — misses are warnings.
 - **Asset links** (`/logo.png`) are checked against the `public/` directory.
-- **External links** are only checked with `--external` (off by default since it
-  requires the network); dead links (404/410/unreachable) are errors, while
-  rate-limited or transient responses (403/429/5xx/timeout) are warnings.
+- **External links** are only checked with `--external` (off by default since it requires the network); dead links (404/410/unreachable) are errors, while rate-limited or transient responses (403/429/5xx/timeout) are warnings.

package/docs/reference/frontmatter.mdx

@@ -18,6 +18,11 @@ Every page accepts the following frontmatter. All fields are optional.
       type: "string",
       description: "Publish date for blog/changelog feeds (ISO or YAML date).",
     },
+    authors: {
+      type: "string | string[] | object[]",
+      description:
+        "Post author(s) for blog/changelog content — a name, or objects with a name plus optional avatar/url and any extra fields. Preserved as-is.",
+    },
     slug: { type: "string", description: "Override the generated slug." },
     draft: {
       type: "boolean",
@@ -64,8 +69,7 @@ search:
 
 ## Changelog
 
-Changelog entries (`type: changelog`) accept an optional `changelog` object for
-richer feed and display metadata:
+Changelog entries (`type: changelog`) accept an optional `changelog` object for richer feed and display metadata:
 
 ```yaml lineNumbers
 type: changelog
@@ -75,8 +79,6 @@ changelog:
   category: Features
 ```
 
-`date` may live here or at the top level — both feed the
-[changelog RSS feed](/docs/content#feeds). See [Changelog](/docs/advanced/changelog) for the
-generated timeline page and feed.
+`date` may live here or at the top level — both feed the [changelog RSS feed](/docs/content#feeds). See [Changelog](/docs/advanced/changelog) for the generated timeline page and feed.
 
 Schemas are exported from `blume/schema` for editor and migration tooling.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -50,6 +50,7 @@
     "./components": "./src/components/index.ts",
     "./components/*": "./src/components/*",
     "./core/*": "./src/core/*",
+    "./openapi/*": "./src/openapi/*",
     "./sources/*": "./src/core/sources/*",
     "./theme/*": "./src/theme/*",
     "./package.json": "./package.json"
@@ -69,10 +70,19 @@
     "@astrojs/node": "^11.0.0",
     "@astrojs/react": "^6.0.0",
     "@astrojs/vercel": "^11.0.0",
+    "@iconify-json/fa6-brands": "^1.2.6",
+    "@iconify-json/fa6-regular": "^1.2.4",
+    "@iconify-json/fa6-solid": "^1.2.4",
+    "@iconify-json/lucide": "^1.2.115",
+    "@iconify-json/tabler": "^1.2.35",
+    "@iconify/types": "^2.0.0",
+    "@iconify/utils": "^3.1.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@orama/orama": "^3.1.18",
     "@pierre/diffs": "^1.2.11",
     "@scalar/astro": "^0.4.5",
+    "@scalar/openapi-parser": "^0.28.8",
+    "@scalar/openapi-types": "^0.9.1",
     "@shikijs/transformers": "^4.2.0",
     "@shikijs/twoslash": "^4.2.0",
     "@tailwindcss/typography": "^0.5.20",

package/src/astro/generate.ts

@@ -36,11 +36,9 @@ import type { ResolvedConfig } from "../core/schema.ts";
 import { resolveTsconfigAliases } from "../core/tsconfig-aliases.ts";
 import type { Navigation } from "../core/types.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
-import {
-  buildReferenceFiles,
-  hasReferences,
-  referenceTabs,
-} from "../openapi/scalar.ts";
+import { hasScalarReferences, referenceTabs } from "../openapi/references.ts";
+import { buildReferenceFiles } from "../openapi/scalar.ts";
+import { isOpenApiSource } from "../openapi/source.ts";
 import { registry } from "../registry/registry.ts";
 import { buildSearchDocuments } from "../search/documents.ts";
 import { searchProviderMeta, servesStaticIndex } from "../search/providers.ts";
@@ -582,8 +580,9 @@ export const buildRuntimeData = (project: BlumeProject): string => {
 
   const { i18n } = config;
 
-  // API reference routes (Scalar) surface as header tabs alongside the
-  // content-derived ones, so the reference stays discoverable in every locale.
+  // API reference routes surface as header tabs alongside the content-derived
+  // ones (Blume-rendered references also own a tab-scoped sidebar of operations),
+  // so the reference stays discoverable in every locale.
   const withReferenceTabs = (nav: Navigation): Navigation => ({
     ...nav,
     repoUrl: config.navigation.repo && repoUrl ? repoUrl : null,
@@ -650,6 +649,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
             })),
           }
         : null,
+      icons: config.icons,
       imageZoom: config.markdown.imageZoom,
       logo: resolveLogo(project),
       mcp: config.mcp.enabled
@@ -912,6 +912,7 @@ export const generateRuntime = async (
   const themePath = join(srcDir, "generated", "app.css");
   const searchClientPath = join(srcDir, "generated", "search-client.ts");
   const examplesPath = join(srcDir, "generated", "examples.ts");
+  const openapiPath = join(srcDir, "generated", "openapi.json");
 
   // Record every file this pass writes so orphans (from a now-disabled feature)
   // can be pruned afterwards. `write` wraps the atomic writer and tracks paths.
@@ -987,6 +988,7 @@ export const generateRuntime = async (
         needsReact,
         needsSvelte,
         needsVue,
+        openapiPath,
         pages,
         searchClientPath,
         themePath,
@@ -1235,7 +1237,7 @@ export const generateRuntime = async (
   // React ships with Blume; Vue/Svelte islands need their Astro integration
   // installed by the project. Warn early rather than let Vite fail to resolve it.
   warnings.push(...islandFrameworkWarnings(frameworks, context.root));
-  if (hasReferences(config)) {
+  if (hasScalarReferences(config)) {
     const references = await buildReferenceFiles({
       config,
       contentRoutes: new Set(project.graph.pages.map((page) => page.route)),
@@ -1254,6 +1256,14 @@ export const generateRuntime = async (
     join(srcDir, "generated", "data.json"),
     buildRuntimeData(project)
   );
+  // The parsed OpenAPI specs behind the `blume:openapi` alias. Always written
+  // (even as `{}`) so the alias resolves whether or not a reference is enabled;
+  // the source parsed the specs during the scan, so this is just serialization.
+  const openApiSource = project.sources.find(isOpenApiSource);
+  await write(
+    openapiPath,
+    `${JSON.stringify(openApiSource ? openApiSource.openApiData() : {})}\n`
+  );
   await write(
     join(out, "blume.manifest.json"),
     `${JSON.stringify(project.manifest, null, 2)}\n`

package/src/astro/integration.ts

@@ -1,10 +1,13 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { fileURLToPath } from "node:url";
 
 import type { AstroIntegration } from "astro";
 
+import type { AssetMount } from "../core/assets.ts";
 import { enrichDiagnostic } from "../core/diagnostics.ts";
 import type { Diagnostic } from "../core/types.ts";
 import { markdownVariantUrl, prefersMarkdown } from "./markdown-negotiation.ts";
+import { copyAssetMounts, serveAssetMounts } from "./static-assets.ts";
 
 /** The dev server's HMR channel — either `.ws` (Vite ≤5) or `.hot` (Vite 6+). */
 interface OverlayChannel {
@@ -72,6 +75,13 @@ export interface BlumeIntegrationOptions {
   pages: BlumePageRoute[];
   /** Page routes that have a raw-Markdown variant (the content manifest). */
   contentRoutes: string[];
+  /** Configured `deployment.base`, stripped from dev URLs before matching. */
+  base?: string;
+  /**
+   * `content.assets` mounts: top-level dirs served at the site root in dev and
+   * copied into the build output, so root-served assets need no relocation.
+   */
+  assets?: AssetMount[];
 }
 
 /**
@@ -83,13 +93,13 @@ export interface BlumeIntegrationOptions {
  * keep serving HTML.
  */
 const negotiateMarkdown =
-  (routes: ReadonlySet<string>) =>
+  (routes: ReadonlySet<string>, base?: string) =>
   (req: IncomingMessage, res: ServerResponse, next: () => void): void => {
     if (
       (req.method === "GET" || req.method === "HEAD") &&
       prefersMarkdown(req.headers.accept)
     ) {
-      const variant = markdownVariantUrl(req.url, routes);
+      const variant = markdownVariantUrl(req.url, routes, base);
       if (variant) {
         res.setHeader("Vary", "Accept");
         req.url = variant;
@@ -108,6 +118,12 @@ export const blumeIntegration = (
   options: BlumeIntegrationOptions
 ): AstroIntegration => ({
   hooks: {
+    "astro:build:done": async ({ dir }) => {
+      // Copy in-place asset mounts into the build output, mirroring publicDir.
+      if (options.assets?.length) {
+        await copyAssetMounts(options.assets, fileURLToPath(dir));
+      }
+    },
     "astro:config:setup": ({ injectRoute }) => {
       for (const page of options.pages) {
         injectRoute({
@@ -124,9 +140,16 @@ export const blumeIntegration = (
       // Prepend so the rewrite happens before Astro's own request handler,
       // letting the rewritten URL resolve to the `.md` endpoint.
       server.middlewares.stack.unshift({
-        handle: negotiateMarkdown(new Set(options.contentRoutes)),
+        handle: negotiateMarkdown(new Set(options.contentRoutes), options.base),
         route: "",
       });
+      // Serve `content.assets` mounts (Astro only serves publicDir in dev).
+      if (options.assets?.length) {
+        server.middlewares.stack.unshift({
+          handle: serveAssetMounts(options.assets),
+          route: "",
+        });
+      }
     },
   },
   name: "blume",

package/src/astro/islands.ts

@@ -105,9 +105,13 @@ export const discoverIslands = async (
       continue;
     }
     const name = base.replace(ISLAND_FILE, "");
-    if (!/^[A-Z]/u.test(name)) {
+    // The name is used verbatim as both an MDX tag and an unquoted object key
+    // in the generated island map, so it must be a plain PascalCase identifier
+    // — a `-`, `.`, or space (e.g. `Time-Picker.tsx`) would otherwise emit a
+    // syntax-error module and fail the whole build with no pointer to the file.
+    if (!/^[A-Z][A-Za-z0-9_]*$/u.test(name)) {
       warnings.push(
-        `Island "${file}" must have a PascalCase filename to be used in MDX (e.g. Counter.tsx → <Counter />); skipping it.`
+        `Island "${file}" must have a PascalCase identifier filename to be used in MDX (letters, digits, and underscores only, e.g. Counter.tsx → <Counter />); skipping it.`
       );
       continue;
     }

package/src/astro/markdown-negotiation.ts

@@ -50,7 +50,8 @@ export const prefersMarkdown = (accept: string | null | undefined): boolean => {
  */
 export const markdownVariantUrl = (
   rawUrl: string | null | undefined,
-  routes: ReadonlySet<string>
+  routes: ReadonlySet<string>,
+  base?: string
 ): string | null => {
   if (!rawUrl) {
     return null;
@@ -58,11 +59,24 @@ export const markdownVariantUrl = (
   const queryIndex = rawUrl.indexOf("?");
   const query = queryIndex === -1 ? "" : rawUrl.slice(queryIndex);
   const rawPath = queryIndex === -1 ? rawUrl : rawUrl.slice(0, queryIndex);
+
+  // A non-root `deployment.base` prefixes the dev-server URL but not the logical
+  // content routes, so strip it before matching and re-add it to the variant.
+  const prefix = base && base !== "/" ? base.replace(/\/$/u, "") : "";
+  let path = rawPath;
+  if (prefix) {
+    if (path === prefix || path.startsWith(`${prefix}/`)) {
+      path = path.slice(prefix.length) || "/";
+    } else {
+      return null;
+    }
+  }
+
   const pathname =
-    rawPath !== "/" && rawPath.endsWith("/") ? rawPath.slice(0, -1) : rawPath;
+    path !== "/" && path.endsWith("/") ? path.slice(0, -1) : path;
   if (!routes.has(pathname)) {
     return null;
   }
   const target = pathname === "/" ? "/index" : pathname;
-  return `${target}.md${query}`;
+  return `${prefix}${target}.md${query}`;
 };

package/src/astro/pages.ts

@@ -21,7 +21,12 @@ export const discoverPages = async (
   return files.map((file) => {
     const rel = relative(pagesRoot, file);
     const withoutExt = rel.slice(0, rel.length - extname(rel).length);
-    const parts = withoutExt.split("/").filter((part) => part !== "index");
+    const parts = withoutExt.split("/");
+    // Only a trailing `index` maps to its parent dir; a folder literally named
+    // `index` (e.g. `index/foo.astro`) must keep its segment.
+    if (parts.at(-1) === "index") {
+      parts.pop();
+    }
     const pattern = parts.length === 0 ? "/" : `/${parts.join("/")}`;
     return { entrypoint: file, pattern };
   });

package/src/astro/static-assets.ts

@@ -0,0 +1,117 @@
+import { createReadStream, existsSync, statSync } from "node:fs";
+import type { Stats } from "node:fs";
+import { cp } from "node:fs/promises";
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import { extname, join, relative, resolve, sep } from "pathe";
+
+import type { AssetMount } from "../core/assets.ts";
+
+/** Content types for the asset extensions a docs project commonly serves. */
+const MIME_TYPES: Record<string, string> = {
+  ".avif": "image/avif",
+  ".css": "text/css; charset=utf-8",
+  ".gif": "image/gif",
+  ".ico": "image/x-icon",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".mp4": "video/mp4",
+  ".otf": "font/otf",
+  ".pdf": "application/pdf",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".ttf": "font/ttf",
+  ".txt": "text/plain; charset=utf-8",
+  ".webm": "video/webm",
+  ".webp": "image/webp",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+};
+
+const mimeType = (file: string): string =>
+  MIME_TYPES[extname(file).toLowerCase()] ?? "application/octet-stream";
+
+/** Whether `child` is `parent` itself or a path nested under it. */
+const isContained = (parent: string, child: string): boolean => {
+  const rel = relative(parent, child);
+  return rel === "" || (!rel.startsWith("..") && !rel.startsWith(sep));
+};
+
+/** Resolve a request URL to an on-disk file within one of the mounts, if any. */
+const resolveRequest = (url: string, mounts: AssetMount[]): string | null => {
+  const pathname = decodeURIComponent(
+    (url.split("?")[0] ?? "").split("#")[0] ?? ""
+  );
+  for (const mount of mounts) {
+    if (pathname !== mount.url && !pathname.startsWith(`${mount.url}/`)) {
+      continue;
+    }
+    // `.` + rel keeps the join relative so an absolute-looking suffix can't
+    // escape the mount; the containment check rejects `..` traversal outright.
+    const file = resolve(mount.dir, `.${pathname.slice(mount.url.length)}`);
+    if (isContained(mount.dir, file)) {
+      return file;
+    }
+  }
+  return null;
+};
+
+/** `statSync` that returns null instead of throwing on a missing file. */
+const statFile = (file: string): Stats | null => {
+  try {
+    return statSync(file);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * A dev-server middleware that serves `content.assets` mounts (top-level dirs
+ * kept in place, e.g. a migrated `images/`) at their site URL. Astro only serves
+ * `publicDir` in dev, so without this those references would 404. Non-matching
+ * requests, and any path that isn't a real file, fall through to Astro. Stat is
+ * synchronous — this is dev-only middleware and mirrors how sirv serves statics.
+ */
+export const serveAssetMounts =
+  (mounts: AssetMount[]) =>
+  (req: IncomingMessage, res: ServerResponse, next: () => void): void => {
+    if ((req.method !== "GET" && req.method !== "HEAD") || !req.url) {
+      next();
+      return;
+    }
+    const file = resolveRequest(req.url, mounts);
+    const stats = file ? statFile(file) : null;
+    if (!(file && stats?.isFile())) {
+      next();
+      return;
+    }
+    res.setHeader("Content-Type", mimeType(file));
+    res.setHeader("Content-Length", String(stats.size));
+    if (req.method === "HEAD") {
+      res.end();
+      return;
+    }
+    createReadStream(file).pipe(res);
+  };
+
+/**
+ * Copy every asset mount into the build output, mirroring what Astro does with
+ * `publicDir`. Runs on `astro:build:done` so in-place asset dirs ship in the
+ * final `dist/`. A missing source dir is skipped (it may be referenced but
+ * absent); `cp` handles both directories and single files.
+ */
+export const copyAssetMounts = async (
+  mounts: AssetMount[],
+  outDir: string
+): Promise<void> => {
+  for (const mount of mounts) {
+    if (!existsSync(mount.dir)) {
+      continue;
+    }
+    const dest = join(outDir, mount.url.replace(/^\/+/u, ""));
+    // oxlint-disable-next-line no-await-in-loop -- sequential fs copies
+    await cp(mount.dir, dest, { recursive: true });
+  }
+};