blume 2.0.1 → 2.0.2

package/src/core/safe-href.ts

@@ -11,6 +11,58 @@ const SAFE_SCHEMES = new Set(["http", "https", "mailto", "tel"]);
 
 const SCHEME = /^(?<scheme>[a-z][\d+.a-z-]*):/iu;
 
+// Markdown decodes a destination before the browser sees it: a backslash
+// escape (`javascript\:`) and a character reference (`java&#115;cript:`,
+// `javascript&colon;`) both reach the `href` as the plain character, so the
+// check reads the destination decoded. Of HTML's named references, these are
+// the only ones that decode to a scheme character, a colon, or a character
+// the URL parser strips; every other one leaves the scheme a browser reads
+// unchanged.
+const MARKDOWN_DECODED =
+  /\\(?<escaped>[!-/:-@[-`{-~])|&(?:#[Xx](?<hex>[\dA-Fa-f]{1,6})|#(?<decimal>\d{1,7})|(?<named>colon|fjlig|NewLine|period|plus|Tab));/gu;
+
+const NAMED_REFERENCES = new Map([
+  ["colon", ":"],
+  ["fjlig", "fj"],
+  ["NewLine", "\n"],
+  ["period", "."],
+  ["plus", "+"],
+  ["Tab", "\t"],
+]);
+
+const MAX_CODE_POINT = 0x10_ff_ff;
+const SURROGATES = { end: 0xdf_ff, start: 0xd8_00 };
+
+/** A numeric reference's character; U+FFFD for NUL, surrogates, and overflow. */
+const fromReference = (code: number): string =>
+  code === 0 ||
+  code > MAX_CODE_POINT ||
+  (code >= SURROGATES.start && code <= SURROGATES.end)
+    ? "�"
+    : String.fromCodePoint(code);
+
+const decodeMarkdown = (href: string): string =>
+  href.replaceAll(
+    MARKDOWN_DECODED,
+    (
+      _match: string,
+      escaped?: string,
+      hex?: string,
+      decimal?: string,
+      named?: string
+    ) => {
+      if (escaped !== undefined) {
+        return escaped;
+      }
+      if (named !== undefined) {
+        return NAMED_REFERENCES.get(named) ?? "";
+      }
+      const code =
+        hex === undefined ? Number(decimal) : Number.parseInt(hex, 16);
+      return fromReference(code);
+    }
+  );
+
 // The URL parser removes ASCII tabs and newlines anywhere, and strips leading
 // C0 controls and spaces, before it reads a scheme — so `java\tscript:` is a
 // `javascript:` URL to a browser, and the check must see it the same way.
@@ -18,7 +70,7 @@ const URL_IGNORED = /[\t\n\r]/gu;
 
 /** Whether a link destination from imported content is safe to keep. */
 export const isSafeHref = (href: string): boolean => {
-  const cleaned = href.replaceAll(URL_IGNORED, "");
+  const cleaned = decodeMarkdown(href).replaceAll(URL_IGNORED, "");
   let start = 0;
   while (start < cleaned.length && (cleaned.codePointAt(start) ?? 0) <= 0x20) {
     start += 1;

package/src/core/safe-links.ts

@@ -1,6 +1,8 @@
 import type { Nodes, Root } from "mdast";
 import { fromMarkdown } from "mdast-util-from-markdown";
+import { gfmFromMarkdown } from "mdast-util-gfm";
 import { toString } from "mdast-util-to-string";
+import { gfm } from "micromark-extension-gfm";
 
 import { isSafeHref } from "./safe-href.ts";
 import { escapeMarkdownText } from "./sources/lower.ts";
@@ -54,10 +56,17 @@ export const unsafeLinkSpans = (tree: Root): UnsafeLinkSpan[] => {
 /**
  * Markdown with every unsafe link reduced to its label text and every unsafe
  * link definition removed. Everything else — safe links, raw HTML, code —
- * passes through as written.
+ * passes through as written. The Markdown is read as GitHub-flavored, the way
+ * the site renders it: a link inside a footnote definition or a table cell is
+ * only a link to a GFM parser.
  */
 export const neutralizeUnsafeLinks = (markdown: string): string => {
-  const spans = unsafeLinkSpans(fromMarkdown(markdown));
+  const spans = unsafeLinkSpans(
+    fromMarkdown(markdown, {
+      extensions: [gfm()],
+      mdastExtensions: [gfmFromMarkdown()],
+    })
+  );
   let out = "";
   let cursor = 0;
   for (const span of spans) {

package/src/core/schema.ts

@@ -397,20 +397,27 @@ const contentConfigSchema = z
      */
     types: z.record(z.string(), contentTypeConfigSchema).default({}),
   })
-  .superRefine((value, ctx) => {
-    if (!value.sources) {
-      return;
-    }
-    for (const key of FILESYSTEM_SHORTHAND_KEYS) {
-      if (value[key] !== undefined) {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: `content.${key} is shorthand for a single filesystem() source and can't be combined with content.sources — move it into a filesystem({ ${key} }) entry in content.sources.`,
-          path: [key],
-        });
+  .superRefine(
+    (value, ctx) => {
+      if (!value.sources) {
+        return;
       }
-    }
-  })
+      for (const key of FILESYSTEM_SHORTHAND_KEYS) {
+        if (value[key] !== undefined) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `content.${key} is shorthand for a single filesystem() source and can't be combined with content.sources — move it into a filesystem({ ${key} }) entry in content.sources.`,
+            path: [key],
+          });
+        }
+      }
+    },
+    // Zod skips a refinement once a field has failed, so without this a
+    // Blume 1 config (`{ type: "filesystem" }` sources beside `content.root`)
+    // would only learn about the shorthand after fixing every source entry.
+    // Any object gets the check; a non-object already failed on its own.
+    { when: (payload) => isObjectLike(payload.value) }
+  )
   .transform(({ exclude, include, root, sources, ...rest }) => ({
     ...rest,
     sources: sources ?? [
@@ -456,7 +463,11 @@ const navTabSchema = z.strictObject({
     )
     .optional(),
   label: localizableLabelSchema,
-  path: z.string(),
+  // Canonical like the routes it's matched against — one leading slash, no
+  // trailing one — so `/guides/` still marks its pages' tab and scopes their
+  // sidebar, and `api` links to `/api` rather than resolving relative to the
+  // current page.
+  path: z.string().transform(normalizeRoute),
 });
 
 const navSelectorItemSchema = z.strictObject({
@@ -1154,9 +1165,30 @@ const versionsConfigSchema = z
 const REDIRECT_PATTERN = /(?:^|\/):[A-Za-z_]|\*/u;
 const URL_ORIGIN = /^[a-z][\d+.a-z-]*:\/\/[^/]*/iu;
 
+/**
+ * The shape each end must start with: `from` is always a path on this site,
+ * `to` may also leave it. A path without its leading slash would never gain
+ * `basePath` or the deployment base, and hosts read it relative to nothing.
+ */
+const REDIRECT_START = {
+  from: {
+    allows: (path: string) => path.startsWith("/"),
+    message:
+      "redirects take root-relative paths: `from` must start with `/` (`/old-page`, not `old-page`).",
+  },
+  to: {
+    allows: (path: string) => path.startsWith("/") || URL_ORIGIN.test(path),
+    message:
+      "redirects take root-relative paths or full URLs: `to` must start with `/` (`/new-page`, not `new-page`) or be an absolute URL (`https://…`).",
+  },
+};
+
 const exactRedirectPath = (end: "from" | "to") =>
   z
     .string()
+    .refine(REDIRECT_START[end].allows, {
+      message: REDIRECT_START[end].message,
+    })
     .refine((path) => !REDIRECT_PATTERN.test(path.replace(URL_ORIGIN, "")), {
       message: `redirects take exact paths: \`${end}\` can't hold a \`:param\` segment or a \`*\` wildcard. Add one redirect per path, or put pattern rules in your host's redirect config (vercel.json, _redirects).`,
     });
@@ -1645,6 +1677,16 @@ const lastModifiedConfigSchema = z.union(
  * build machine's zone. `dateStyle` is a preset that can't be combined with the
  * individual component fields (`year`, `month`, …), matching `Intl`'s own rule.
  */
+/** The `dateFormat` fields that choose the date's shape (length, components). */
+const DATE_FORM_FIELDS = [
+  "dateStyle",
+  "weekday",
+  "era",
+  "year",
+  "month",
+  "day",
+] as const;
+
 const dateFormatConfigSchema = z
   .strictObject({
     /** Calendar system (e.g. `japanese`, `buddhist`). */
@@ -1678,6 +1720,14 @@ const dateFormatConfigSchema = z
       message:
         "dateFormat.dateStyle can't be combined with weekday/era/year/month/day; use one or the other.",
     }
+  )
+  // `timeZone`, `calendar`, and `numberingSystem` don't pick a shape, so a
+  // format that sets only those keeps the long default instead of falling to
+  // Intl's bare numeric date (`7/21/2026`).
+  .transform((value) =>
+    DATE_FORM_FIELDS.some((field) => value[field] !== undefined)
+      ? value
+      : { ...value, dateStyle: "long" as const }
   );
 
 /** Code rendering options (`markdown.code`). */
@@ -1806,6 +1856,12 @@ export const blumeConfigSchema = z
        */
       basePath: z
         .string()
+        // Normalizing would turn a URL into `/https:/docs.example.com/docs`
+        // and keep a query or fragment inside every route.
+        .refine((value) => !URL_ORIGIN.test(value) && !/[#?]/u.test(value), {
+          message:
+            'basePath takes a path like "/docs", not a URL: no scheme, host, query, or fragment. The site\'s origin goes in deployment.site.',
+        })
         .optional()
         .transform((value) => normalizeBasePath(value)),
       content: contentConfigSchema.prefault({}),

package/src/core/sources/assets.ts

@@ -13,7 +13,14 @@ import { extname, join } from "pathe";
 import type { Diagnostic } from "../types.ts";
 import { hashText } from "./cache.ts";
 
-const MD_IMAGE = /!\[(?<alt>[^\]]*)\]\((?<url>[^)\s]+)\)/gu;
+// A Markdown image as the lowerers write it (`image()` in `lower.ts`): the
+// alt text can hold backslash escapes (`\]`), and a destination holding
+// spaces or parentheses sits in angle brackets, both with its own escapes.
+const MD_IMAGE =
+  /!\[(?<alt>(?:\\.|[^\\\]])*)\]\((?:<(?<pointy>(?:\\.|[^\\<>\n])*)>|(?<bare>(?:\\.|[^\\\s)])+))\)/gu;
+// A backslash escape inside a destination, which Markdown reads as the
+// character it escapes.
+const DESTINATION_ESCAPE = /\\(?<char>[!-/:-@[-`{-~])/gu;
 // A `<video>` tag's `src`, split so the rewrite can swap the URL and keep the
 // surrounding attributes untouched. Notion's uploaded videos arrive as signed,
 // expiring URLs exactly like its images, so they rot the same way. `[^>]`
@@ -21,35 +28,47 @@ const MD_IMAGE = /!\[(?<alt>[^\]]*)\]\((?<url>[^)\s]+)\)/gu;
 const HTML_VIDEO_SRC =
   /(?<open><video\b[^>]*?\ssrc=")(?<url>[^"]+)(?<close>")/gu;
 const REMOTE = /^https?:\/\//u;
-const SAFE_EXT = /^\.[a-z0-9]+$/iu;
 const CODE_FENCE_BLOCK =
   /^(?<fence>`{3,}|~{3,})[^\n]*\n[\s\S]*?^\k<fence>[^\n]*(?=\n|$)/gmu;
 // NUL delimiters cannot appear in authored markdown, so tokens never collide.
 // oxlint-disable-next-line no-control-regex -- the NUL is the collision guard.
 const FENCE_TOKEN = /\u0000blume-fence-(?<index>\d+)\u0000/gu;
 
-// The extension for a URL whose path carries none, keyed by the media type the
-// server reports. A static host serves by extension, so a `.png` holding JPEG
-// bytes is mislabeled and a `.png` holding a video is refused by strict
-// players — the response is the source of truth, not the reference kind.
+// The extension an asset is saved under, keyed by the media type the server
+// reports. Only images and videos are ever written: the file is served from
+// the docs origin by its extension, so an HTML page (a Vimeo/Loom watch page,
+// or a hostile "image" URL) saved as `.html` would render as a page on the
+// site. A static host serves by extension, so a `.png` holding JPEG bytes is
+// mislabeled and a `.png` holding a video is refused by strict players — the
+// response is the source of truth, not the reference kind.
 const EXT_BY_MIME = new Map([
+  ["image/apng", ".apng"],
   ["image/avif", ".avif"],
+  ["image/bmp", ".bmp"],
   ["image/gif", ".gif"],
   ["image/jpeg", ".jpg"],
+  ["image/jpg", ".jpg"],
   ["image/png", ".png"],
   ["image/svg+xml", ".svg"],
+  ["image/tiff", ".tiff"],
+  ["image/vnd.microsoft.icon", ".ico"],
   ["image/webp", ".webp"],
+  ["image/x-icon", ".ico"],
   ["video/mp4", ".mp4"],
   ["video/ogg", ".ogv"],
   ["video/quicktime", ".mov"],
   ["video/webm", ".webm"],
 ]);
-const UNKNOWN_EXT = ".bin";
-// Response types that are never a media file. A pasted Vimeo/Loom/Wistia link
-// is a video block in Notion whose URL is a watch page (200 text/html), and an
-// API endpoint answers JSON or XML; `image/svg+xml` is media and stays.
-const NON_MEDIA_TYPE =
-  /^(?:text\/|application\/(?:[\w.-]+\+)?(?:json|xml|javascript))/u;
+// The same images and videos as a URL's path names them, for a response
+// whose type says nothing about the bytes.
+const MEDIA_EXTS = new Set([...EXT_BY_MIME.values(), ".jpeg"]);
+// Response types that don't say what the bytes are; object stores answer
+// uploads this way, so the URL's extension decides.
+const OPAQUE_TYPES = new Set([
+  "",
+  "application/octet-stream",
+  "binary/octet-stream",
+]);
 const PART_SUFFIX = ".part";
 // Generous enough for a multi-hundred-megabyte recording on an ordinary
 // connection; its job is to fail a stalled download rather than hang the build.
@@ -78,13 +97,17 @@ export interface AssetContext {
   timeoutMs?: number;
 }
 
-/** The extension in a URL's path, or null when it carries none we'd trust. */
+/** The image or video extension in a URL's path, or null when it names none. */
 const extFromUrl = (url: string): string | null => {
   const clean = url.split("?")[0] ?? url;
-  const ext = extname(clean);
-  return SAFE_EXT.test(ext) ? ext.toLowerCase() : null;
+  const ext = extname(clean).toLowerCase();
+  return MEDIA_EXTS.has(ext) ? ext : null;
 };
 
+/** An image's destination as the URL it names, its escapes decoded. */
+const imageUrl = (pointy?: string, bare?: string): string =>
+  (pointy ?? bare ?? "").replaceAll(DESTINATION_ESCAPE, "$<char>");
+
 /** The response's media type, lowercased and stripped of parameters. */
 const mediaType = (res: Response): string =>
   res.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase() ?? "";
@@ -100,9 +123,10 @@ const exists = async (path: string): Promise<boolean> => {
 
 /**
  * The completed file for a stem whose extension came from an earlier response
- * rather than the URL, so an extension-less asset is not fetched on every
- * poll. Only a lone candidate counts: query-less URLs can collide, and picking
- * between two files would be a guess.
+ * rather than the URL, so the asset is not fetched on every poll. Only a lone
+ * image or video counts: query-less URLs can collide, picking between two
+ * files would be a guess, and a partial download (or any other file an older
+ * version saved) is never reused.
  */
 const completedFor = async (
   dir: string,
@@ -115,11 +139,28 @@ const completedFor = async (
     return null;
   }
   const candidates = names.filter(
-    (name) => name.startsWith(`${stem}.`) && !name.endsWith(PART_SUFFIX)
+    (name) => name.startsWith(stem) && MEDIA_EXTS.has(name.slice(stem.length))
   );
   return candidates.length === 1 ? (candidates[0] ?? null) : null;
 };
 
+/**
+ * The extension to save a response under: the image or video type it
+ * reports, or the URL's image or video extension when the type says nothing.
+ * Anything else is refused rather than written where the site would serve it.
+ */
+const extFor = (type: string, urlExt: string | null): string => {
+  const ext = EXT_BY_MIME.get(type) ?? (OPAQUE_TYPES.has(type) ? urlExt : null);
+  if (ext) {
+    return ext;
+  }
+  throw new Error(
+    OPAQUE_TYPES.has(type)
+      ? `responded with ${type || "no content type"} and its URL names no image or video file`
+      : `responded with ${type}, not an image or video`
+  );
+};
+
 /**
  * Download remote media referenced in a Markdown body into the asset dir and
  * rewrite the reference to the local public path. Markdown images and the
@@ -148,26 +189,26 @@ export const materializeAssets = async (
     return `\u0000blume-fence-${fences.length - 1}\u0000`;
   });
 
-  const urls = new Set<string>();
-  for (const pattern of [MD_IMAGE, HTML_VIDEO_SRC]) {
-    for (const match of masked.matchAll(pattern)) {
-      const url = match.groups?.url;
-      if (url && REMOTE.test(url)) {
-        urls.add(url);
-      }
-    }
-  }
+  const referenced = [
+    ...[...masked.matchAll(MD_IMAGE)].map((match) =>
+      imageUrl(match.groups?.pointy, match.groups?.bare)
+    ),
+    ...[...masked.matchAll(HTML_VIDEO_SRC)].map(
+      (match) => match.groups?.url ?? ""
+    ),
+  ];
+  const urls = new Set(referenced.filter((url) => REMOTE.test(url)));
 
   /** Fetch one asset into the asset dir and return its file name. */
   const download = async (url: string, stem: string): Promise<string> => {
     const urlExt = extFromUrl(url);
-    // The name is known up front whenever the path has an extension (every
-    // Notion upload does), so a file from an earlier run is reused as is;
+    // The name is usually known up front from the path's extension (every
+    // Notion upload has one), so a file from an earlier run is reused as is;
     // otherwise the extension came from the last response, so look for it.
     if (urlExt && (await exists(join(ctx.assetsDir, `${stem}${urlExt}`)))) {
       return `${stem}${urlExt}`;
     }
-    const completed = urlExt ? null : await completedFor(ctx.assetsDir, stem);
+    const completed = await completedFor(ctx.assetsDir, stem);
     if (completed) {
       return completed;
     }
@@ -176,15 +217,13 @@ export const materializeAssets = async (
       throw new Error(`${res.status}`);
     }
     // Writing a watch page or an API response out as `.mp4` gives a player
-    // that can't play and a green build, so refuse what is never media.
-    const type = mediaType(res);
-    if (NON_MEDIA_TYPE.test(type)) {
-      throw new Error(`responded with ${type}, not a media file`);
-    }
+    // that can't play and a green build, and one saved as `.html` would be
+    // served as a page on the docs origin: only images and videos are kept.
+    const ext = extFor(mediaType(res), urlExt);
     if (!res.body) {
       throw new Error("empty response body");
     }
-    const file = `${stem}${urlExt ?? EXT_BY_MIME.get(type) ?? UNKNOWN_EXT}`;
+    const file = `${stem}${ext}`;
     const target = join(ctx.assetsDir, file);
     await mkdir(ctx.assetsDir, { recursive: true });
     // Stream the body to disk rather than buffering it: a video is hundreds of
@@ -258,10 +297,13 @@ export const materializeAssets = async (
   );
 
   const rewritten = masked
-    .replaceAll(MD_IMAGE, (match, alt, url) => {
-      const local = rewrites.get(url);
-      return local ? `![${alt}](${local})` : match;
-    })
+    .replaceAll(
+      MD_IMAGE,
+      (match: string, alt: string, pointy?: string, bare?: string) => {
+        const local = rewrites.get(imageUrl(pointy, bare));
+        return local ? `![${alt}](${local})` : match;
+      }
+    )
     .replaceAll(HTML_VIDEO_SRC, (match, open, url, close) => {
       const local = rewrites.get(url);
       return local ? `${open}${local}${close}` : match;

package/src/core/sources/contentful-rich-text.ts

@@ -13,6 +13,7 @@ import type { InlineMarks } from "./lower.ts";
 import {
   absoluteUrl,
   blockquote,
+  guardBlockStart,
   headingPrefix,
   image,
   joinBlocks,
@@ -234,11 +235,11 @@ const renderBlock = (
   const type = asString(node.nodeType) ?? "";
   const heading = HEADING.exec(type)?.groups?.level;
   if (heading) {
-    return `${headingPrefix(Number(heading))}${renderInlines(children(node), options)}`;
+    return `${headingPrefix(Number(heading))}${guardBlockStart(renderInlines(children(node), options))}`;
   }
   switch (type) {
     case "paragraph": {
-      return renderInlines(children(node), options);
+      return guardBlockStart(renderInlines(children(node), options));
     }
     case "blockquote": {
       return blockquote(

package/src/core/sources/contentful.ts

@@ -1,3 +1,4 @@
+import { BlumeError } from "../diagnostics.ts";
 import {
   assetFromEntry,
   contentfulRichTextToMarkdown,
@@ -111,19 +112,29 @@ export const contentfulSource = (
     );
   };
 
-  const fetchEntries = async (): Promise<SourceEntry[]> => {
-    const preview = ctx?.preview ?? false;
-    const deliveryToken = options.token ?? process.env.CONTENTFUL_ACCESS_TOKEN;
-    const previewToken =
-      options.previewToken ?? process.env.CONTENTFUL_PREVIEW_TOKEN;
-    // The Preview API rejects delivery tokens, so falling back to one would
-    // only trade a clear config error for a 401.
-    if (preview && !previewToken) {
-      throw new Error(
-        "Contentful --preview needs a Preview API token: set previewToken or CONTENTFUL_PREVIEW_TOKEN."
-      );
+  const preview = ctx?.preview ?? false;
+  const previewToken = (): string | undefined =>
+    options.previewToken ?? process.env.CONTENTFUL_PREVIEW_TOKEN;
+
+  // The Preview API rejects delivery tokens, so falling back to one would
+  // only trade a clear config error for a 401. Checked before the cache, so
+  // a warm snapshot can't stand in for the drafts `--preview` asked for.
+  const assertConfigured = (): void => {
+    if (preview && !previewToken()) {
+      throw new BlumeError({
+        code: "BLUME_SOURCE_MISCONFIGURED",
+        message: `Source "${options.name}": Contentful --preview needs a Preview API token.`,
+        severity: "error",
+        suggestion:
+          "Set previewToken on contentfulSource, or the CONTENTFUL_PREVIEW_TOKEN environment variable.",
+      });
     }
-    const token = preview ? previewToken : deliveryToken;
+  };
+
+  const fetchEntries = async (): Promise<SourceEntry[]> => {
+    const token = preview
+      ? previewToken()
+      : (options.token ?? process.env.CONTENTFUL_ACCESS_TOKEN);
     const client: RestClient = {
       fetchImpl: options.fetchImpl,
       headers: token ? { authorization: `Bearer ${token}` } : {},
@@ -163,10 +174,12 @@ export const contentfulSource = (
 
   return remoteSource(
     {
+      assertConfigured,
       fetchEntries,
       name: options.name,
       pollInterval: options.pollInterval,
       prefix: options.prefix,
+      withContext: (next) => contentfulSource(options, next),
     },
     ctx
   );

package/src/core/sources/filesystem.ts

@@ -83,7 +83,9 @@ export const filesystemSource = (
         file: contentRoot,
         message: `Content root not found: ${options.root}`,
         severity: "error",
-        suggestion: `Create a "${options.root}" folder with at least one .md or .mdx file, or set content.root in blume.config.ts.`,
+        // `content.root` is rejected beside `content.sources`, so the hint
+        // names both places a root is set.
+        suggestion: `Create a "${options.root}" folder with at least one .md or .mdx file, or point Blume at your docs folder: content.root in blume.config.ts, or the filesystem() source's root when you list content.sources.`,
       });
     }
   };
@@ -113,6 +115,8 @@ export const filesystemSource = (
 
   return {
     contentRoot,
+    exclude: options.exclude,
+    include: options.include,
     load,
     name: options.name,
     prefix: options.prefix,