blume 1.3.0 → 1.3.1

package/docs/configuration/ai.mdx

@@ -63,7 +63,7 @@ The `.md` variant _downlevels_ components to plain Markdown for consumers that c
 
 ### Content negotiation
 
-Agents don't need to know the `.md` convention: requesting a page's own URL with an [`Accept: text/markdown`](https://acceptmarkdown.com) header serves the Markdown variant at the same address, with `Vary: Accept` so caches keep the two apart. The dev server honors the header out of the box, and a [Vercel server build](/docs/deployment#server-rendering) wires the same negotiation into the deploy's routing rules automatically — no configuration needed. Other deploy targets serve prerendered pages from a static layer with no request-time hook, so agents there fetch the `.md` URL directly; the [agent readability manifest](#agent-readability) advertises `contentNegotiation` only on deployments that honor the header.
+Agents don't need to know the `.md` convention: requesting a page's own URL with an [`Accept: text/markdown`](https://acceptmarkdown.com) header serves the Markdown variant at the same address, with `Vary: Accept` so caches keep the two apart. The dev server honors the header out of the box, and a [Vercel server build](/docs/deployment#server-rendering) wires the same negotiation into the deploy's routing rules automatically — no configuration needed. The homepage always negotiates, even when it's a custom landing page rather than a content page: its Markdown mirror falls back to the [`llms.txt`](#llmstxt) index, so an agent asking the site root for Markdown gets the machine-readable map of the site. Markdown responses also carry an `x-markdown-tokens` header — an estimated token count (~4 characters per token), following the convention of [Cloudflare's Markdown for Agents](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/) — on every surface where Blume controls response headers: the dev server, server-rendered responses, and the negotiated homepage on Vercel. Other deploy targets serve prerendered pages from a static layer with no request-time hook, so agents there fetch the `.md` URL directly; the [agent readability manifest](#agent-readability) advertises `contentNegotiation` only on deployments that honor the header.
 
 ### Custom component serializers
 
@@ -324,7 +324,7 @@ Link: </agent-readability.json>; rel="describedby"; type="application/json",
   </index.md>; rel="alternate"; type="text/markdown"
 ```
 
-Each entry appears only when its feature is on, and the `alternate` link only when your homepage is a content page with a [raw Markdown](#raw-markdown) mirror. Sites that publish APIs also get a `rel="api-catalog"` entry pointing at the [generated API catalog](#api-catalog). The header rides on every surface Blume controls: the dev server (check it with `curl -I localhost:4321`), static builds via the emitted `_headers` file (Netlify and Cloudflare), and Vercel server builds via the deploy's routing rules. Hosts that ignore `_headers` on static output (GitHub Pages, S3) can't send custom response headers at all — there, agents still find everything through `llms.txt` and `agent-readability.json` at the site root.
+Each entry appears only when its feature is on. The `alternate` link points at the homepage's Markdown mirror — the page's own [raw Markdown](#raw-markdown) when the home route is a content page, or the synthesized `llms.txt` fallback when it's a landing page. Sites that publish APIs also get a `rel="api-catalog"` entry pointing at the [generated API catalog](#api-catalog). The header rides on every surface Blume controls: the dev server (check it with `curl -I localhost:4321`), static builds via the emitted `_headers` file (Netlify and Cloudflare), and Vercel server builds via the deploy's routing rules. Hosts that ignore `_headers` on static output (GitHub Pages, S3) can't send custom response headers at all — there, agents still find everything through `llms.txt` and `agent-readability.json` at the site root.
 
 ### API catalog
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",

package/src/ai/link-headers.ts

@@ -40,9 +40,10 @@ export const buildHomeLinkHeader = (
       `<${deployBase}/llms.txt>; rel="describedby"; type="text/plain"`
     );
   }
-  // Same home-mirror condition as the Vercel negotiation routes: "/" is a
-  // content route only when the docs sit at the site root (no `basePath`) and
-  // the root page is real content, so `/index.md` exists exactly then.
+  // Same route list as the negotiation surfaces (`markdownRoutePaths`): "/"
+  // always has a mirror — the page's own source when the home route is a
+  // content page, the synthesized llms.txt fallback otherwise — so callers
+  // passing that list always advertise `/index.md` here.
   if (routePaths.includes("/")) {
     links.push(
       `<${deployBase}/index.md>; rel="alternate"; type="text/markdown"`

package/src/ai/llms.ts

@@ -60,8 +60,10 @@ const indexedNavigations = (
  * Build the compact `llms.txt` index: title and summary, then the sidebar tree
  * rendered as sections — group labels become headings, pages become link lists —
  * so the file mirrors how the docs are organized rather than one flat blob.
+ * Also serves as the homepage's synthesized Markdown mirror when the home
+ * route is a landing page (see `buildRawMarkdown`).
  */
-const buildIndex = (project: BlumeProject): string => {
+export const buildLlmsIndex = (project: BlumeProject): string => {
   const { config } = project;
   const { site } = config.deployment;
   const base = normalizeBasePath(config.deployment.base);
@@ -222,5 +224,5 @@ export const buildLlmsFiles = async (
   project: BlumeProject
 ): Promise<{ index: string; full: string }> => ({
   full: await buildFull(project),
-  index: buildIndex(project),
+  index: buildLlmsIndex(project),
 });

package/src/ai/markdown.ts

@@ -9,6 +9,7 @@ import {
   downlevelComponents,
   exampleComponentSerializers,
 } from "./component-markdown.ts";
+import { buildLlmsIndex } from "./llms.ts";
 import { applyAgentVisibility } from "./visibility.ts";
 
 /** One route's raw-Markdown variants. */
@@ -28,6 +29,16 @@ export interface RawMarkdownEntry {
 export const agentMarkdown = (entry: RawMarkdownEntry): string =>
   entry.md ?? entry.mdx;
 
+/**
+ * Estimated token count of a Markdown document, for the `x-markdown-tokens`
+ * response header (the convention Cloudflare's Markdown for Agents ships; the
+ * tokenizer is unspecified there too, so this is the common ~4-characters-
+ * per-token estimate). Kept in sync with the inline computation in
+ * `rawMarkdownEndpointTemplate`, which can't import build-time code.
+ */
+export const markdownTokenCount = (text: string): number =>
+  Math.ceil(text.length / 4);
+
 /**
  * Map every route to its raw source Markdown. Powers the `<route>.md` and
  * `<route>.mdx` endpoints: `.mdx` serves the original source so tools can see
@@ -79,5 +90,27 @@ export const buildRawMarkdown = async (
       return [route.path, entry] as const;
     })
   );
-  return Object.fromEntries(entries);
+  const map = Object.fromEntries(entries);
+  // A landing-page homepage (user `.astro` page, or no home route at all) has
+  // no Markdown source, but agents negotiating `Accept: text/markdown` on `/`
+  // still expect a Markdown answer. The llms.txt index — the machine-readable
+  // representation of the site a landing page fronts — becomes its mirror, so
+  // `/index.md` always exists (see `markdownRoutePaths`).
+  if (!map["/"]) {
+    map["/"] = { mdx: buildLlmsIndex(project) };
+  }
+  return map;
+};
+
+/**
+ * Every route path with a raw-Markdown mirror: the manifest routes, plus the
+ * homepage when its mirror is the synthesized llms.txt fallback (see
+ * `buildRawMarkdown`). This is the route list the negotiation surfaces (dev
+ * middleware, Vercel routing config) and the homepage `Link` header build
+ * from, so `Accept: text/markdown` on `/` resolves even when the homepage is
+ * a landing page.
+ */
+export const markdownRoutePaths = (project: BlumeProject): string[] => {
+  const paths = project.manifest.routes.map((route) => route.path);
+  return paths.includes("/") ? paths : [...paths, "/"];
 };

package/src/astro/generate.ts

@@ -19,7 +19,7 @@ import { glob } from "tinyglobby";
 
 import { buildAskData } from "../ai/ask-data.ts";
 import { resolveAskBackend } from "../ai/ask.ts";
-import { buildRawMarkdown } from "../ai/markdown.ts";
+import { buildRawMarkdown, markdownRoutePaths } from "../ai/markdown.ts";
 import { buildMcpData } from "../ai/mcp/data.ts";
 import { buildMcpDiscovery, buildMcpServerCard } from "../ai/mcp/discovery.ts";
 import { normalizeBasePath } from "../core/base-path.ts";
@@ -1608,7 +1608,7 @@ export const generateRuntime = async (
           aliases: resolveTsconfigAliases(context.root),
           askPath,
           config,
-          contentRoutes: project.manifest.routes.map((route) => route.path),
+          contentRoutes: markdownRoutePaths(project),
           contentWatchesRuntimeDir: contentWatchesRuntimeDir(
             hasFilesystemSource,
             docsCollection.base,

package/src/astro/integration.ts

@@ -116,7 +116,9 @@ const isHomeUrl = (rawUrl: string | undefined, base?: string): boolean => {
  * the same negotiation from routing rules spliced into the Build Output config
  * (see `deploy/vercel-negotiation.ts`); every other build exposes the same
  * content at the `.md` URL. Only routes with a Markdown variant are rewritten,
- * so landing pages and user `.astro` pages keep serving HTML. The same
+ * so user `.astro` pages keep serving HTML — except the homepage, whose
+ * variant falls back to the synthesized llms.txt mirror when it's a landing
+ * page (see `markdownRoutePaths`). The same
  * middleware also stamps the homepage agent-discovery `Link` header, mirroring
  * what the deployed site sends via `_headers` / the Vercel routing config.
  */

package/src/astro/templates.ts

@@ -1181,10 +1181,15 @@ export function getStaticPaths() {
 export function GET({ props }: { props: { route: string } }) {
   const entries = raw as Record<string, { md?: string; mdx?: string }>;
   const entry = entries[props.route];
-  return new Response(entry ? ${
+  const body = entry ? ${
     kind === "md" ? '(entry.md ?? entry.mdx ?? "")' : '(entry.mdx ?? "")'
-  } : "", {
-    headers: { "Content-Type": "text/markdown; charset=utf-8" },
+  } : "";
+  return new Response(body, {
+    headers: {
+      "Content-Type": "text/markdown; charset=utf-8",
+      // ~4 characters per token; keep in sync with markdownTokenCount.
+      "x-markdown-tokens": String(Math.ceil(body.length / 4)),
+    },
   });
 }
 `;

package/src/cli/commands/build.ts

@@ -14,6 +14,12 @@ import {
 } from "../../ai/api-catalog.ts";
 import { buildHomeLinkHeader } from "../../ai/link-headers.ts";
 import { buildLlmsFiles } from "../../ai/llms.ts";
+import {
+  agentMarkdown,
+  buildRawMarkdown,
+  markdownRoutePaths,
+  markdownTokenCount,
+} from "../../ai/markdown.ts";
 import {
   AGENT_SKILLS_DIR,
   buildSkillsIndex,
@@ -146,10 +152,7 @@ const emitHeaderFiles = async (
     join(distDir, "_headers"),
     buildNetlifyHeaders(
       config,
-      buildHomeLinkHeader(
-        config,
-        project.manifest.routes.map((route) => route.path)
-      )
+      buildHomeLinkHeader(config, markdownRoutePaths(project))
     ),
     "utf-8"
   );
@@ -253,10 +256,11 @@ const emitWellKnownFiles = async (
  * straight to the project root (see `withAdapterRoot`).
  */
 const emitVercelNegotiation = async (
-  config: ResolvedConfig,
+  project: BlumeProject,
   routePaths: string[],
   root: string
 ): Promise<void> => {
+  const { config } = project;
   const configPath = join(root, ".vercel", "output", "config.json");
   if (!existsSync(configPath)) {
     return;
@@ -269,11 +273,17 @@ const emitVercelNegotiation = async (
       ? { [SIGNATURES_DIRECTORY_PATH.slice(1)]: SIGNATURES_DIRECTORY_TYPE }
       : {}),
   };
+  // The homepage rewrite serves `/index.md` from the static layer, so its
+  // `x-markdown-tokens` estimate has to ride the routing config; the runtime
+  // endpoint stamps it on dev/server-rendered responses itself.
+  const rawMarkdown = await buildRawMarkdown(project);
+  const home = rawMarkdown["/"];
   const injected = injectNegotiationRoutes(
     await readFile(configPath, "utf-8"),
     routePaths,
     buildHomeLinkHeader(config, routePaths),
-    overrides
+    overrides,
+    home ? markdownTokenCount(agentMarkdown(home)) : undefined
   );
   if (injected === null) {
     logger.warn(
@@ -709,11 +719,7 @@ export const buildCommand = defineCommand({
     }
 
     if (project.config.deployment.output === "server" && adapter === "vercel") {
-      await emitVercelNegotiation(
-        project.config,
-        project.manifest.routes.map((route) => route.path),
-        root
-      );
+      await emitVercelNegotiation(project, markdownRoutePaths(project), root);
     }
 
     await publishBuildArtifacts(

package/src/deploy/vercel-negotiation.ts

@@ -85,9 +85,12 @@ const chunkPatterns = (patterns: readonly string[]): string[][] => {
 export interface NegotiationRoutes {
   /**
    * `Vary: Accept` for the plain-HTML side of every negotiated URL, so shared
-   * caches keep the two variants apart. Spliced *after* `handle: "filesystem"`
-   * — routes there run against filesystem matches (the same slot the Vercel
-   * adapter uses for its `_astro` cache headers).
+   * caches keep the two variants apart. Spliced *before* `handle:
+   * "filesystem"` with `continue`: main-phase headers accumulate and ride on
+   * whatever ultimately serves the request. Routes placed after the filesystem
+   * marker are the miss phase — they run only when no static file matches, and
+   * every Blume content page is a prerendered static file, so a header route
+   * there never fires.
    */
   headerRoutes: VercelRoute[];
   /**
@@ -102,10 +105,15 @@ export interface NegotiationRoutes {
  * Build the routes for the given content-route paths (the routes that have a
  * raw-Markdown mirror, straight from the manifest). Paths are matched with an
  * optional trailing slash and rewritten `/{route}` → `/{route}.md`; the home
- * page's mirror lives at `/index.md`.
+ * page's mirror lives at `/index.md`. When `homeTokens` is given, the home
+ * rewrite also stamps `x-markdown-tokens` — the estimated token count of the
+ * homepage mirror (Cloudflare's Markdown for Agents convention). Only the home
+ * route can carry it: the other rewrites are chunked alternations spanning
+ * many pages, and a count is per-page.
  */
 export const buildNegotiationRoutes = (
-  routePaths: readonly string[]
+  routePaths: readonly string[],
+  homeTokens?: number
 ): NegotiationRoutes => {
   const home = routePaths.includes("/");
   const rest = routePaths
@@ -118,7 +126,10 @@ export const buildNegotiationRoutes = (
         {
           dest: "/index.md",
           has: ACCEPT_MARKDOWN_CONDITION,
-          headers: VARY_ACCEPT,
+          headers:
+            homeTokens === undefined
+              ? VARY_ACCEPT
+              : { ...VARY_ACCEPT, "x-markdown-tokens": String(homeTokens) },
           src: "^/$",
         },
       ]
@@ -170,9 +181,9 @@ const isNegotiationRoute = (route: VercelRoute): boolean =>
 /**
  * Splice the negotiation routes into a Build Output `config.json`, plus — when
  * given — a homepage `Link` header route for agent discovery (see
- * `ai/link-headers.ts`), applied the same way the `Vary` routes are: after
- * `handle: "filesystem"` with `continue`, so the header rides on the
- * prerendered homepage response. `contentTypeOverrides` maps static-dir
+ * `ai/link-headers.ts`), applied the same way the `Vary` routes are: in the
+ * main phase before `handle: "filesystem"` with `continue`, so the header
+ * rides on the prerendered homepage response. `contentTypeOverrides` maps static-dir
  * relative paths to media types via the Build Output `overrides` field — the
  * platform's mechanism for extensionless static files (e.g. the Web Bot Auth
  * signature directory). Returns the updated JSON text (tab-indented, like the
@@ -184,7 +195,8 @@ export const injectNegotiationRoutes = (
   configText: string,
   routePaths: readonly string[],
   homeLinkHeader?: string | null,
-  contentTypeOverrides?: Record<string, string>
+  contentTypeOverrides?: Record<string, string>,
+  homeTokens?: number
 ): string | null => {
   const overrideEntries = Object.entries(contentTypeOverrides ?? {});
   if (
@@ -218,7 +230,10 @@ export const injectNegotiationRoutes = (
   if (filesystemIndex === -1) {
     return null;
   }
-  const { headerRoutes, rewriteRoutes } = buildNegotiationRoutes(routePaths);
+  const { headerRoutes, rewriteRoutes } = buildNegotiationRoutes(
+    routePaths,
+    homeTokens
+  );
   if (homeLinkHeader) {
     headerRoutes.push({
       continue: true,
@@ -226,8 +241,10 @@ export const injectNegotiationRoutes = (
       src: HOME_SRC,
     });
   }
-  routes.splice(filesystemIndex + 1, 0, ...headerRoutes);
-  routes.splice(filesystemIndex, 0, ...rewriteRoutes);
+  // Headers first: `continue` routes accumulate, so a request the rewrite
+  // route then terminates (Markdown negotiation on the homepage) still carries
+  // the Link header.
+  routes.splice(filesystemIndex, 0, ...headerRoutes, ...rewriteRoutes);
   config.routes = routes;
   return `${JSON.stringify(config, null, "\t")}\n`;
 };

package/src/theme/fonts.ts

@@ -210,7 +210,9 @@ export const slugifyFontName = (name: string): string =>
   name
     .toLowerCase()
     .replaceAll(/[^a-z0-9]+/gu, "-")
-    .replaceAll(/^-+|-+$/gu, "");
+    // The collapse above leaves only single dashes, so no quantifiers needed
+    // (an unanchored `-+$` backtracks quadratically on long dash runs).
+    .replaceAll(/^-|-$/gu, "");
 
 /** The CSS variable Astro populates for a given font (shared across roles). */
 const fontVar = (slug: string): string => `--blume-ff-${slug}`;