blume 2.0.1 → 2.0.3

package/src/core/project-graph.ts

@@ -3,6 +3,7 @@ import { isAbsolute, relative } from "pathe";
 import { CHANGELOG_INDEX_ROUTE, hasChangelogIndex } from "./changelog-index.ts";
 import { loadConfig } from "./config.ts";
 import { customStaticRoutes, discoverPages } from "./custom-pages.ts";
+import { unknownDirectiveDiagnostics } from "./directive-diagnostics.ts";
 import { buildContentGraph } from "./graph.ts";
 import { i18nDiagnostics } from "./i18n.ts";
 import { expandIncludes, hasIncludeStatements } from "./includes.ts";
@@ -10,6 +11,7 @@ import {
   gitLastModifiedTimes,
   gitRepositoryRoot,
   lastModifiedShallowWarning,
+  realPath,
   resolveLastModifiedConfig,
 } from "./last-modified.ts";
 import { buildManifest } from "./manifest.ts";
@@ -184,6 +186,7 @@ const normalizeLoadedEntries = (
         source: {
           monolingual: source.monolingual,
           name: source.name,
+          orderedNames: source.orderedNames,
           prefix: source.prefix,
           staged: source.staged,
         },
@@ -195,11 +198,34 @@ const normalizeLoadedEntries = (
       }
       pages.push(...normalized.pages);
       allDiagnostics.push(...normalized.diagnostics);
+      if (normalized.pages.length > 0) {
+        allDiagnostics.push(...unknownDirectiveDiagnostics(entry, source.name));
+      }
     }
   }
   return { diagnostics: allDiagnostics, droppedPages, pages };
 };
 
+/**
+ * The local sources' on-disk roots a `git log` pathspec can cover: those
+ * inside the repository at `gitRoot`. A root outside it would fail the log
+ * outright and can never yield dates. Compared by real path, since git spells
+ * its toplevel with every symlink resolved (`/private/tmp/site` for a project
+ * opened as `/tmp/site`); the roots themselves keep the project's spelling.
+ */
+const gitContentRoots = (
+  sources: readonly ContentSource[],
+  gitRoot: string | null
+): string[] => {
+  if (gitRoot === null) {
+    return [];
+  }
+  const top = realPath(gitRoot);
+  return sources
+    .flatMap((source) => (source.contentRoot ? [source.contentRoot] : []))
+    .filter((dir) => isWithin(top, realPath(dir)));
+};
+
 /**
  * Run the full core pipeline for a project root: load config, resolve paths,
  * discover content and folder meta, build the graph, and assemble the manifest.
@@ -215,6 +241,19 @@ const isLogoShorthand = (
 const logoHref = (logo: ResolvedConfig["logo"]): string =>
   logo === undefined || isLogoShorthand(logo) ? "/" : (logo.href ?? "/");
 
+/** Narrows the banner config's text shorthand from its object form. */
+const isBannerShorthand = (
+  banner: NonNullable<ResolvedConfig["banner"]>
+): banner is string => typeof banner === "string";
+
+/** The configured banner link target, when the banner has a link. */
+const bannerLinkHref = (
+  banner: ResolvedConfig["banner"]
+): string | undefined =>
+  banner === undefined || isBannerShorthand(banner)
+    ? undefined
+    : banner.link?.href;
+
 export const scanProject = async (
   root: string,
   options: {
@@ -255,7 +294,14 @@ export const scanProject = async (
   const metaSources: FolderMetaSource[] = sources.flatMap((source) =>
     source.staged || !source.contentRoot
       ? []
-      : [{ prefix: source.prefix, root: source.contentRoot }]
+      : [
+          {
+            exclude: source.exclude,
+            include: source.include,
+            prefix: source.prefix,
+            root: source.contentRoot,
+          },
+        ]
   );
 
   // Run every source's `load()` in parallel, then funnel each entry through the
@@ -341,12 +387,9 @@ export const scanProject = async (
     // The git pathspecs must cover where the pages actually live: each local
     // source's own on-disk root — a filesystem source's `root`, or a staged
     // local source's tree (an Obsidian vault) — which diverges from the global
-    // `content.root`. A root outside the repository would fail the log outright
-    // and can never yield dates, so those are dropped up front.
+    // `content.root`.
     const gitRoot = gitRepositoryRoot(context.root);
-    const contentRoots = sources
-      .flatMap((source) => (source.contentRoot ? [source.contentRoot] : []))
-      .filter((dir) => gitRoot !== null && isWithin(gitRoot, dir));
+    const contentRoots = gitContentRoots(sources, gitRoot);
     const gitTimes = gitLastModifiedTimes(
       context.root,
       contentRoots,
@@ -382,6 +425,7 @@ export const scanProject = async (
     ? await discoverPages(context.pagesRoot)
     : [];
   const graph = buildContentGraph(pages, {
+    bannerHref: bannerLinkHref(config.banner),
     basePath: config.basePath,
     brandHref: logoHref(config.logo),
     extraRoutes: new Set([

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).`,
     });
@@ -1271,9 +1303,9 @@ const ogConfigSchema = z.strictObject({
    */
   enabled: z.boolean().optional(),
   /**
-   * Google Font families for the generated card, extending Takumi's Latin-only
-   * default so non-Latin titles (CJK, and so on) render instead of tofu.
-   * Fetched from Google Fonts at build.
+   * Fonts for the generated card, replacing the default stack (Takumi's
+   * Latin-only built-in font plus a Noto fallback per script). Google
+   * families are fetched from Google Fonts at build.
    */
   fonts: z.array(ogFontSchema).optional(),
   /**
@@ -1645,6 +1677,30 @@ 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;
+
+/**
+ * Whether `Intl` knows a time zone. An unknown one (`Asia/Tokio`) throws a
+ * RangeError the first time a date is formatted, deep in a page render, so it
+ * is caught here where the error can point at `dateFormat.timeZone`.
+ */
+const isKnownTimeZone = (timeZone: string): boolean => {
+  try {
+    Intl.DateTimeFormat("en", { timeZone });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
 const dateFormatConfigSchema = z
   .strictObject({
     /** Calendar system (e.g. `japanese`, `buddhist`). */
@@ -1660,7 +1716,13 @@ const dateFormatConfigSchema = z
     /** Numbering system (e.g. `latn`, `arab`). */
     numberingSystem: z.string().optional(),
     /** IANA time zone (e.g. `Asia/Tokyo`). Defaults to `UTC`. */
-    timeZone: z.string().optional(),
+    timeZone: z
+      .string()
+      .refine(isKnownTimeZone, {
+        message:
+          'Unknown time zone; use an IANA name like "Asia/Tokyo" or "UTC".',
+      })
+      .optional(),
     /** Weekday representation. */
     weekday: z.enum(["long", "short", "narrow"]).optional(),
     /** Year representation. */
@@ -1678,6 +1740,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 +1876,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;