blume 0.7.0 → 1.0.0

package/src/core/i18n.ts

@@ -74,12 +74,16 @@ export const detectLocale = (
   parts: string[],
   i18n: ResolvedI18nConfig
 ): { locale: string; rest: string[] } => {
-  const [first] = parts;
-  const isNonDefault = i18n.locales.some(
-    (locale) => locale.code !== i18n.defaultLocale && locale.code === first
+  // BCP 47 codes are case-insensitive: a conventional lowercase folder
+  // (`pt-br/`) must match a configured `pt-BR`. The configured casing is what
+  // flows into routes and labels.
+  const first = parts[0]?.toLowerCase();
+  const matched = i18n.locales.find(
+    (locale) =>
+      locale.code !== i18n.defaultLocale && locale.code.toLowerCase() === first
   );
-  if (first !== undefined && isNonDefault) {
-    return { locale: first, rest: parts.slice(1) };
+  if (matched) {
+    return { locale: matched.code, rest: parts.slice(1) };
   }
   return { locale: i18n.defaultLocale, rest: parts };
 };
@@ -116,11 +120,15 @@ export const localePlacement = (
     // authoring `intro.en.mdx` + `intro.fr.mdx` shares one translation key
     // instead of routing the default file to a literal `/intro.en`.
     if (lastDot > base.lastIndexOf("/")) {
-      const suffix = base.slice(lastDot + 1);
-      const matched = i18n.locales.some((locale) => locale.code === suffix);
+      // Case-insensitive, like `detectLocale`: `intro.pt-br.mdx` matches a
+      // configured `pt-BR` and adopts its casing.
+      const suffix = base.slice(lastDot + 1).toLowerCase();
+      const matched = i18n.locales.find(
+        (locale) => locale.code.toLowerCase() === suffix
+      );
       if (matched) {
         return {
-          locales: [suffix],
+          locales: [matched.code],
           navPath: `${base.slice(0, lastDot)}${ext}`,
         };
       }

package/src/core/last-modified.ts

@@ -42,16 +42,23 @@ export const parseGitLog = (output: string): Map<string, string> => {
 
 /**
  * Resolve each source file's last-modified date from git history, keyed by
- * absolute source path. Runs a single `git log` over the content tree and maps
- * repo-root-relative paths back to the given absolute paths (monorepo-safe via
- * `rev-parse --show-toplevel`). Returns an empty map if git is unavailable or
- * the project isn't a repo — the feature then simply shows no dates.
+ * absolute source path. Runs a single `git log` over the given content roots
+ * (each filesystem source's own root, which may diverge from `content.root`)
+ * and maps repo-root-relative paths back to the given absolute paths
+ * (monorepo-safe via `rev-parse --show-toplevel`). Returns an empty map if git
+ * is unavailable or the project isn't a repo — the feature then simply shows
+ * no dates.
  */
 export const gitLastModifiedTimes = (
   root: string,
-  contentRoot: string,
+  contentRoots: string[],
   sourcePaths: string[]
 ): Map<string, string> => {
+  // Nothing to date — don't pay for a git scan (an empty pathspec list would
+  // log the entire repository).
+  if (sourcePaths.length === 0) {
+    return new Map();
+  }
   try {
     const gitRoot = execFileSync(
       // oxlint-disable-next-line sonarjs/no-os-command-from-path -- git is a required dev-tool dependency resolved from PATH
@@ -71,7 +78,7 @@ export const gitLastModifiedTimes = (
         "--format=%x00%cI",
         "--name-only",
         "--",
-        contentRoot,
+        ...contentRoots,
       ],
       { encoding: "utf-8", maxBuffer: 256 * 1024 * 1024 }
     );

package/src/core/links.ts

@@ -49,6 +49,9 @@ interface LinkContext {
   anchors: Map<string, Set<string>>;
   /** Site-wide route mount point (`""` or `/seg`); routes carry it, assets don't. */
   basePath: string;
+  /** Servable routes outside the graph (custom pages, generated routes); their
+   * headings are unknown, so anchors there are accepted unchecked. */
+  extraRoutes: Set<string>;
   publicDir: string | null;
   /** Normalized `redirect.from` paths — valid targets that resolve at runtime. */
   redirects: Set<string>;
@@ -62,16 +65,24 @@ const assetIsPresent = (resolved: string, ctx: LinkContext): boolean =>
 /** Outcome of classifying one link target. */
 type LinkResult = Diagnostic | "asset-unchecked" | null;
 
+// Mirrors the ordering-prefix strip in `sources/normalize.ts`: route mapping
+// drops the prefix before recognizing `index`, so `01-index.mdx` is an index.
+const NUMERIC_PREFIX = /^\d+[-_.]/u;
+
 /**
- * Whether a page is a directory index (`…/index.md(x)`). Its route already *is*
- * its directory, so a relative link must resolve against the route itself, not
- * its parent — otherwise `./sibling` from `guides/index.mdx` (route `/guides`)
- * would resolve to `/sibling` and be falsely flagged as broken.
+ * Whether a page is a directory index (`…/index.md(x)`, ordering prefix
+ * ignored). Its route already *is* its directory, so a relative link must
+ * resolve against the route itself, not its parent — otherwise `./sibling`
+ * from `guides/index.mdx` (route `/guides`) would resolve to `/sibling` and be
+ * falsely flagged as broken. Tested against `navPath` — the locale-stripped
+ * path — so a dot-parser localized index (`index.fr.mdx`) and a shared
+ * locale-agnostic one (`index.$.mdx`) count too, matching how route mapping
+ * recognizes them.
  */
-const isIndexPage = (page: PageRecord): boolean => {
-  const ref = page.source?.ref ?? page.sourcePath ?? "";
-  return /^index\.(?:md|mdx)$/iu.test(basename(ref));
-};
+const isIndexPage = (page: PageRecord): boolean =>
+  /^index\.(?:md|mdx)$/iu.test(
+    basename(page.navPath).replace(NUMERIC_PREFIX, "")
+  );
 
 /** Apply one relative-path segment to the accumulated route segments. */
 const applyRelativePart = (segments: string[], part: string): void => {
@@ -162,6 +173,11 @@ const checkPathLink = (
   if (ctx.routes.has(route)) {
     return fragment ? checkAnchor(route, fragment, site, ctx) : null;
   }
+  // A custom `.astro` page or generated route serves this path, but its
+  // headings aren't indexed — accept any fragment rather than false-flag it.
+  if (ctx.extraRoutes.has(route)) {
+    return null;
+  }
   // A configured `redirect.from` resolves at runtime, so it's a valid target.
   // Its destination (and any anchor there) is validated on its own page, so we
   // don't follow the redirect to check the fragment here.
@@ -365,6 +381,13 @@ export const validateLinks = async (
   options: {
     /** Site-wide route mount point (`""` or `/seg`); routes and redirects carry it. */
     basePath?: string;
+    /**
+     * Servable routes the graph can't know: custom `.astro` pages and generated
+     * routes (e.g. the `/changelog` index). Mounted outside `basePath` (they're
+     * injected at their pattern), so they are *not* based here — mirroring the
+     * full-route-set resolution in `nav-diagnostics.ts`/`generateRuntime`.
+     */
+    extraRoutes?: string[];
     publicDir: string | null;
     checkExternal?: boolean;
     /** Configured redirects; their `from` paths count as valid link targets. */
@@ -375,6 +398,7 @@ export const validateLinks = async (
   const ctx: LinkContext = {
     anchors: buildAnchorIndex(graph.pages),
     basePath,
+    extraRoutes: new Set((options.extraRoutes ?? []).map(toRoute)),
     publicDir: options.publicDir,
     redirects: new Set(
       (options.redirects ?? []).map((redirect) =>

package/src/core/navigation.ts

@@ -38,6 +38,14 @@ const segmentKey = (raw: string): string => {
   return (group ?? raw).replace(NUMERIC_PREFIX, "");
 };
 
+/**
+ * Whether a filename stem is a directory index, ignoring an ordering prefix:
+ * route mapping strips the prefix before dropping `index`, so `01-index` routes
+ * exactly like `index` and must be treated as one here too.
+ */
+const isIndexStem = (stem: string): boolean =>
+  stem.replace(NUMERIC_PREFIX, "") === "index";
+
 interface MutablePage {
   kind: "page";
   key: string;
@@ -106,7 +114,7 @@ const pageOrder = (page: PageRecord, filename: string): number => {
   if (page.meta.sidebar.order !== undefined) {
     return page.meta.sidebar.order;
   }
-  if (filename.replace(extname(filename), "") === "index") {
+  if (isIndexStem(filename.replace(extname(filename), ""))) {
     return Number.NEGATIVE_INFINITY;
   }
   // Changelog entries read newest-first, matching the generated timeline. Sort
@@ -277,8 +285,9 @@ const buildFileSystemSidebar = (
     // An index page's route IS its folder's route (no page segment to drop),
     // and `(group)` folders contribute no route segment at all.
     const routeSegments = page.route.split("/").filter(Boolean);
-    const folderParts =
-      stem === "index" ? routeSegments : routeSegments.slice(0, -1);
+    const folderParts = isIndexStem(stem)
+      ? routeSegments
+      : routeSegments.slice(0, -1);
     const routeDirCount = dirs.filter((dir) => !GROUP_FOLDER.test(dir)).length;
     const offset = Math.max(0, folderParts.length - routeDirCount);
 
@@ -447,6 +456,13 @@ export const buildNavigation = (
     refByLogical?: boolean;
     /** Shared `meta.$.*` meta, keyed by locale-stripped dir path. */
     sharedFolderMeta?: Map<string, FolderMeta>;
+    /**
+     * The tree's root route before `basePath` (`"/"`, or the locale prefix
+     * under i18n, e.g. `/fr` — tab paths arrive already localized). The tab
+     * pointing here spans the whole tree, so it is excluded from tab-section
+     * scoping.
+     */
+    localizedRoot?: string;
   }
 ): Navigation => {
   const basePath = options.basePath ?? "";
@@ -511,6 +527,13 @@ export const buildNavigation = (
     };
   }
 
+  // A tab pointing at the tree root spans the whole sidebar rather than one
+  // section, so it must not feed tab-section hoisting. `tabs` carries final
+  // paths (localized, then based), so the root is compared in the same space —
+  // a root-level `(group)` folder's routePath is exactly the based/localized
+  // prefix (`/docs`, `/fr`) and a bare `"/"` check would miss the match (or,
+  // under a base, falsely scope a group named like the prefix).
+  const rootTabPath = withBasePath(basePath, options.localizedRoot ?? "/");
   return {
     featured,
     selectors,
@@ -520,7 +543,9 @@ export const buildNavigation = (
       sharedFolderMeta,
       metaPrefix,
       display,
-      new Set(tabs.flatMap((tab) => (tab.path === "/" ? [] : [tab.path])))
+      new Set(
+        tabs.flatMap((tab) => (tab.path === rootTabPath ? [] : [tab.path]))
+      )
     ),
     tabs,
   };

package/src/core/package-json.ts

@@ -15,8 +15,22 @@ export const toPackageName = (raw: string): string =>
  * dependency pinned to the installed version plus `dev`/`build`/`doctor`
  * scripts, so `npm install && npm run dev` works immediately. Shared by
  * `blume init` and the migrators, which scaffold one when a project has none.
+ * `extraDeps` adds source SDKs (e.g. `@notionhq/client`) beside `blume`.
  */
-export const blumePackageJson = (name: string): string => `{
+export const blumePackageJson = (
+  name: string,
+  extraDeps: Record<string, string> = {}
+): string => {
+  const dependencies = Object.entries({
+    blume: `^${getBlumeVersion()}`,
+    ...extraDeps,
+  })
+    .toSorted(([a], [b]) => (a < b ? -1 : 1))
+    .map(
+      ([dep, range]) => `    ${JSON.stringify(dep)}: ${JSON.stringify(range)}`
+    )
+    .join(",\n");
+  return `{
   "name": ${JSON.stringify(name)},
   "private": true,
   "type": "module",
@@ -26,7 +40,8 @@ export const blumePackageJson = (name: string): string => `{
     "doctor": "blume doctor"
   },
   "dependencies": {
-    "blume": "^${getBlumeVersion()}"
+${dependencies}
   }
 }
 `;
+};

package/src/core/project-graph.ts

@@ -1,6 +1,7 @@
 import { relative } from "pathe";
 
 import { loadConfig } from "./config.ts";
+import { applyDeploymentEnv } from "./deployment-env.ts";
 import { buildContentGraph } from "./graph.ts";
 import { i18nDiagnostics } from "./i18n.ts";
 import {
@@ -108,7 +109,7 @@ const entryIdDiagnostics = (
         message: `Content source "${page.source.name}" is rooted outside the docs collection base, so ${page.route} resolves entry id "${entryId}" but the collection would generate "${expected}" — the page would 404 at runtime.`,
         severity: "error",
         suggestion:
-          "Give each filesystem source a root under content.root, or use a single filesystem source so the collection can root at it.",
+          "Use a single filesystem source (the docs collection roots at it), or root every filesystem source at content.root and partition them with include globs — a root at a subdirectory of content.root still mismatches.",
       });
     }
   }
@@ -139,7 +140,13 @@ export const scanProject = async (
   const configResult = await loadConfig(root, {
     devServerUrl: options.devServerUrl,
   });
-  const config = applyConfigOverrides(configResult.config, options.overrides);
+  // Re-run platform detection after CLI overrides: `loadConfig` already ran it,
+  // but adapter inference keys off `deployment.output`, which `--output server`
+  // only sets here. Idempotent for already-resolved fields — `deployment.site`
+  // keeps loadConfig's explicit > platform env > devServerUrl precedence.
+  const config = applyDeploymentEnv(
+    applyConfigOverrides(configResult.config, options.overrides)
+  );
   const context = resolveProjectContext(root, config, {
     runtimeDir: options.runtimeDir,
   });
@@ -217,11 +224,13 @@ export const scanProject = async (
     const fsPaths = pages
       .map((page) => page.sourcePath)
       .filter((path): path is string => path !== undefined);
-    const gitTimes = gitLastModifiedTimes(
-      context.root,
-      context.contentRoot,
-      fsPaths
+    // The git pathspecs must cover where the pages actually live: each
+    // filesystem source's own root, which diverges from the global
+    // `content.root` when a source configures a non-default `root`.
+    const contentRoots = sources.flatMap((source) =>
+      source.staged || !source.contentRoot ? [] : [source.contentRoot]
     );
+    const gitTimes = gitLastModifiedTimes(context.root, contentRoots, fsPaths);
     for (const page of pages) {
       if (!page.lastModified && page.sourcePath) {
         page.lastModified = gitTimes.get(page.sourcePath);

package/src/core/schema.ts

@@ -1,5 +1,8 @@
 import { z } from "zod";
 
+import type { ComponentMarkdown } from "../ai/component-markdown.ts";
+import { normalizeRoute } from "../openapi/references.ts";
+import { normalizeXHandle } from "../seo/x-handle.ts";
 import { FONT_SLUGS, isFontSlug } from "../theme/fonts.ts";
 import { normalizeBasePath } from "./base-path.ts";
 import { uiLocaleOverridesSchema } from "./i18n-ui.ts";
@@ -45,6 +48,14 @@ const sidebarMetaSchema = z.strictObject({
   order: z.number().optional(),
 });
 
+/**
+ * An X handle, normalized to a leading `@` — `twitter:site`/`twitter:creator`
+ * require it, and a handle configured without one is the obvious typo to absorb
+ * rather than reject. The layouts normalize again on the way out, since a page's
+ * `seo.x.creator` reaches them straight from unvalidated frontmatter.
+ */
+const xHandleSchema = z.string().transform(normalizeXHandle).optional();
+
 const seoMetaSchema = z.strictObject({
   // blume bundles Zod 3; top-level `z.url()` is undefined at runtime and
   // schemas must stay dual-compatible with consumer projects on Zod 4.
@@ -54,6 +65,8 @@ const seoMetaSchema = z.strictObject({
   image: z.string().optional(),
   noindex: z.boolean().default(false),
   title: z.string().optional(),
+  /** Per-page X attribution — a guest post credits its own author. */
+  x: z.strictObject({ creator: xHandleSchema }).optional(),
 });
 
 const searchMetaSchema = z.strictObject({
@@ -575,7 +588,38 @@ const aiConfigSchema = z.strictObject({
       }
     })
     .optional(),
-  llmsTxt: z.boolean().default(true),
+  /**
+   * `llms.txt`/`llms-full.txt` emission. A bare boolean toggles it; the object
+   * form adds `openapi: false` to keep generated API reference pages out of
+   * both files (e.g. when the configured spec is example content).
+   */
+  llmsTxt: z
+    .union([
+      z.boolean(),
+      z.strictObject({
+        enabled: z.boolean().default(true),
+        openapi: z.boolean().default(true),
+      }),
+    ])
+    .default(true)
+    .transform((value) =>
+      typeof value === "boolean" ? { enabled: value, openapi: true } : value
+    ),
+  // Serializers for the agent-facing Markdown downlevel (the `.md` mirror,
+  // llms-full.txt, MCP get_page), keyed by JSX name. Functions live here —
+  // not in components.tsx — because the config file is executed at build
+  // time while the components file is only statically analyzed. A same-name
+  // entry replaces the built-in serializer.
+  // Two-argument `z.record` — the single-argument form throws at
+  // schema-construction time under Zod 4 (see uiStringsOverrideSchema).
+  markdownComponents: z
+    .record(
+      z.string(),
+      z.custom<ComponentMarkdown>((value) => typeof value === "function", {
+        message: "Expected a serializer function.",
+      })
+    )
+    .default({}),
 });
 
 /**
@@ -641,7 +685,11 @@ const mcpConfigSchema = z.strictObject({
   instructions: z.string().optional(),
   /** Server name shown to clients; defaults to the site title. */
   name: z.string().optional(),
-  route: z.string().default("/mcp"),
+  /**
+   * Normalized like `openapi.route`: a slash-less value would otherwise be
+   * string-concatenated onto the site origin (`https://acme.comdocs-mcp`).
+   */
+  route: z.string().default("/mcp").transform(normalizeRoute),
 });
 
 /** A configured locale: ISO-ish code plus display metadata for the switcher. */
@@ -739,6 +787,19 @@ const redirectSchema = z.strictObject({
   to: z.string(),
 });
 
+/**
+ * X (Twitter) attribution. The account fields feed `twitter:site` (the site's
+ * account) and `twitter:creator` (the author's), which is the one piece of X
+ * card metadata with no Open Graph equivalent to fall back to — everything else
+ * on the card is read from `og:*`.
+ */
+const xConfigSchema = z.strictObject({
+  /** The author's account, overridable per page via `seo.x.creator`. */
+  creator: xHandleSchema,
+  /** The site's own account, e.g. `@blume`. */
+  handle: xHandleSchema,
+});
+
 const ogConfigSchema = z.strictObject({
   /**
    * Generate a per-page Open Graph image. Defaults to on once a deployment
@@ -808,6 +869,8 @@ const seoConfigSchema = z.strictObject({
   sitemap: z.boolean().default(true),
   /** Emit schema.org JSON-LD in each page's <head>. */
   structuredData: z.boolean().default(true),
+  /** X (Twitter) account attribution for share cards. */
+  x: xConfigSchema.default({}),
 });
 
 const githubConfigSchema = z.strictObject({
@@ -984,6 +1047,12 @@ const tocConfigSchema = z
       maxLevel: value.maxHeadingLevel ?? 3,
       minLevel: value.minHeadingLevel ?? 2,
     };
+  })
+  // Checked after defaults apply, so `{ minHeadingLevel: 5 }` (default max 3)
+  // is caught too — an inverted range would silently render an empty TOC.
+  .refine((value) => value.minLevel <= value.maxLevel, {
+    message:
+      "toc.minHeadingLevel must be less than or equal to toc.maxHeadingLevel.",
   });
 
 export const blumeConfigSchema = z.strictObject({

package/src/core/sources/assets.ts

@@ -68,7 +68,12 @@ export const materializeAssets = async (
           throw new Error(`${res.status}`);
         }
         const bytes = new Uint8Array(await res.arrayBuffer());
-        const file = `${hashText(url)}${extFor(url)}`;
+        // Hash the query-less URL (as `extFor` does): CMS asset URLs are
+        // pre-signed, so the query changes on every fetch of the same image —
+        // hashing it would mint a new file each refresh and re-dirty the
+        // content digest. Two real assets sharing scheme+host+path and
+        // differing only in query are rare enough to accept colliding.
+        const file = `${hashText(url.split("?")[0] ?? url)}${extFor(url)}`;
         await mkdir(ctx.assetsDir, { recursive: true });
         await writeFile(join(ctx.assetsDir, file), bytes);
         rewrites.set(url, `${ctx.assetsBaseUrl}/${file}`);

package/src/core/sources/filesystem.ts

@@ -63,6 +63,10 @@ export const filesystemSource = (
         return {
           body: { format, text: parsed.content },
           data: parsed.data,
+          // The unstripped text: lets `normalizeEntry` offset link line numbers
+          // by the frontmatter block's height, so diagnostics point at the real
+          // file line (and spares a re-read on the frontmatter-error path).
+          raw: source,
           ref: relative(contentRoot, file),
           sourcePath: file,
         };

package/src/core/sources/mdx-remote.ts

@@ -170,6 +170,21 @@ export const mdxRemoteSource = (
   const cache = snapshotCache(ctx.cacheDir);
   let snapshot = new Map<string, SourceEntry>();
 
+  // Validated up front in `load`, *before* the cached-fetch path: thrown from
+  // inside `loadWithCache`'s fetch callback, a misconfiguration would be masked
+  // as BLUME_SOURCE_FETCH_FAILED (no cache) or downgraded to a stale-cache
+  // BLUME_SOURCE_OFFLINE warning (cache present).
+  const assertConfigured = (): void => {
+    if (options.github || (options.files && options.url)) {
+      return;
+    }
+    throw new BlumeError({
+      code: "BLUME_SOURCE_MISCONFIGURED",
+      message: `Source "${options.name}" needs either { github } or { url, files }.`,
+      severity: "error",
+    });
+  };
+
   const enumerate = async (): Promise<{
     refs: RemoteRef[];
     truncated: boolean;
@@ -177,20 +192,13 @@ export const mdxRemoteSource = (
     if (options.github) {
       return await enumerateGithub(options.github, options.include, doFetch);
     }
-    if (options.files && options.url) {
-      const base = options.url.replace(/\/$/u, "");
-      const refs = options.files.flatMap((ref) =>
-        matchesInclude(ref, options.include)
-          ? [{ editUrl: `${base}/${ref}`, fetchUrl: `${base}/${ref}`, ref }]
-          : []
-      );
-      return { refs, truncated: false };
-    }
-    throw new BlumeError({
-      code: "BLUME_SOURCE_MISCONFIGURED",
-      message: `Source "${options.name}" needs either { github } or { url, files }.`,
-      severity: "error",
-    });
+    const base = (options.url ?? "").replace(/\/$/u, "");
+    const refs = (options.files ?? []).flatMap((ref) =>
+      matchesInclude(ref, options.include)
+        ? [{ editUrl: `${base}/${ref}`, fetchUrl: `${base}/${ref}`, ref }]
+        : []
+    );
+    return { refs, truncated: false };
   };
 
   const fetchEntry = async (item: RemoteRef): Promise<SourceEntry> => {
@@ -216,6 +224,7 @@ export const mdxRemoteSource = (
   const load = async (
     refresh = ctx.refresh ?? true
   ): Promise<SourceLoadResult> => {
+    assertConfigured();
     const skipped: Diagnostic[] = [];
     const result = await loadWithCache(
       options.name,