blume 2.0.0 → 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

@@ -2,9 +2,9 @@ import type { AstroIntegration } from "astro";
 import { z } from "zod";
 
 import {
-  askAdapterSchema,
-  askMovedFieldsHint,
-  DEFAULT_ASK_PROVIDER,
+  assistantAdapterSchema,
+  assistantMovedFieldsHint,
+  DEFAULT_ASSISTANT_PROVIDER,
 } from "../ai/ask.ts";
 import type { ComponentMarkdown } from "../ai/component-markdown.ts";
 import { analyticsConfigSchema } from "../analytics/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({
@@ -744,7 +755,7 @@ const mcpConfigSchema = z.strictObject({
   route: z.string().default("/mcp").transform(normalizeRoute),
 });
 
-const askEndpointSchema = z
+const assistantEndpointSchema = z
   .string()
   .trim()
   .min(1)
@@ -762,7 +773,7 @@ const askEndpointSchema = z
     },
     {
       message:
-        "ai.ask.endpoint must be an HTTP(S) URL or a root-relative path.",
+        "ai.assistant.endpoint must be an HTTP(S) URL or a root-relative path.",
     }
   );
 
@@ -799,7 +810,7 @@ type AiCatalogResolved = z.output<typeof aiCatalogObjectSchema>;
 
 /**
  * The keys that moved from `ai` to `agents`: `ai` now holds only what faces a
- * model at read time (Ask AI, Open in chat), and the machine-readable surface
+ * model at read time (the assistant, Open in chat), and the machine-readable surface
  * agents consume lives under `agents`.
  */
 const MOVED_TO_AGENTS = [
@@ -821,9 +832,9 @@ const movedToAgentsHints = (from: string): Record<string, string> =>
     ])
   );
 
-/** Model-facing config: the Ask AI assistant and the "Open in chat" action. */
+/** Model-facing config: the assistant and the "Open in chat" action. */
 const aiConfigFields = {
-  ask: z
+  assistant: z
     .strictObject(
       {
         // Origins allowed to call the generated `/api/ask` from another site (a
@@ -843,9 +854,9 @@ const aiConfigFields = {
           .optional(),
         enabled: z.boolean().default(false),
         // Optional external endpoint for projects that keep their docs static
-        // and host Ask AI in an existing backend. Absolute URLs and root-relative
+        // and host the assistant in an existing backend. Absolute URLs and root-relative
         // paths are both valid; the built-in request/stream contract is unchanged.
-        endpoint: askEndpointSchema.optional(),
+        endpoint: assistantEndpointSchema.optional(),
         // Extra system-prompt text (identity, language, tone) appended to the
         // built-in instructions, so the grounding contract — answer from the
         // retrieved excerpts, cite pages as Markdown links — stays intact.
@@ -853,9 +864,9 @@ const aiConfigFields = {
         // The adapter descriptor a `gateway()`/`openrouter()`/... factory
         // returns; each adapter validates its own options (model, key env var,
         // reasoning mapping, `providerOptions` passthrough) in `ai/ask.ts`.
-        // Unset means the gateway with its default model, so zero-config Ask AI
+        // Unset means the gateway with its default model, so the zero-config assistant
         // is unchanged.
-        provider: askAdapterSchema.prefault(DEFAULT_ASK_PROVIDER),
+        provider: assistantAdapterSchema.prefault(DEFAULT_ASSISTANT_PROVIDER),
         // How much documentation each question carries. Injected characters are
         // the dominant term in time-to-first-token on a self-hosted backend, so
         // these trade recall for latency. No zod defaults here: only what the
@@ -880,7 +891,7 @@ const aiConfigFields = {
           )
           .default([]),
       },
-      askMovedFieldsHint
+      assistantMovedFieldsHint
     )
     .superRefine((value, ctx) => {
       // `cors` configures the generated route, which an external `endpoint`
@@ -889,7 +900,7 @@ const aiConfigFields = {
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
           message:
-            "ai.ask.cors only applies to the generated route; with ai.ask.endpoint, CORS is that backend's job.",
+            "ai.assistant.cors only applies to the generated route; with ai.assistant.endpoint, CORS is that backend's job.",
           path: ["cors"],
         });
       }
@@ -921,7 +932,10 @@ const aiConfigFields = {
 
 const aiConfigSchema = z.strictObject(
   aiConfigFields,
-  removedKeysHint(movedToAgentsHints("ai"))
+  removedKeysHint({
+    ...movedToAgentsHints("ai"),
+    ask: "ai.ask was renamed to ai.assistant.",
+  })
 );
 
 /**
@@ -988,9 +1002,11 @@ const navigationConfigSchema = z.strictObject({
   tabs: z.array(navTabSchema).default([]),
 });
 
-export { askReasoningLevels } from "../ai/ask.ts";
-export type { AskReasoning } from "../ai/ask.ts";
-export type AskAiConfig = NonNullable<z.infer<typeof aiConfigSchema>["ask"]>;
+export { assistantReasoningLevels } from "../ai/ask.ts";
+export type { AssistantReasoning } from "../ai/ask.ts";
+export type AssistantConfig = NonNullable<
+  z.infer<typeof aiConfigSchema>["assistant"]
+>;
 export { openInChatProviders } from "./open-in-chat.ts";
 export type { OpenInChatProvider } from "./open-in-chat.ts";
 
@@ -1149,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).`,
     });
@@ -1415,7 +1452,7 @@ const seoConfigSchema = z.strictObject(
 /**
  * The machine-readable surface agents consume: the JSON API, `llms.txt`, the
  * MCP server, published skills, discovery manifests, and the robots.txt
- * usage policy. Everything reader-facing that talks to a model (Ask AI, Open
+ * usage policy. Everything reader-facing that talks to a model (the assistant, Open
  * in chat) stays under `ai`.
  */
 const agentsConfigSchema = z.strictObject({
@@ -1640,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`). */
@@ -1673,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`). */
@@ -1731,7 +1786,7 @@ const reactConfigSchema = z.strictObject({
   /**
    * Auto-memoize React components/hooks with the React Compiler
    * (`babel-plugin-react-compiler`). On by default whenever React is enabled
-   * (a project `.tsx`/`.jsx`, a React island/example/override, or Ask AI); set
+   * (a project `.tsx`/`.jsx`, a React island/example/override, or the assistant); set
    * to `false` to skip the compiler's babel pass.
    */
   compiler: z.boolean().default(true),
@@ -1801,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/server-features.ts

@@ -7,8 +7,8 @@ import type { ResolvedConfig } from "./schema.ts";
  */
 export const serverFeatures = (config: ResolvedConfig): string[] => {
   const features: string[] = [];
-  if (config.ai.ask?.enabled && !config.ai.ask.endpoint) {
-    features.push("Ask AI");
+  if (config.ai.assistant?.enabled && !config.ai.assistant.endpoint) {
+    features.push("Assistant");
   }
   // The hosted MCP server is a live JSON-RPC endpoint, so it needs a runtime.
   if (config.agents.mcp.enabled) {

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(