blume 2.1.0 → 2.1.1

package/src/core/config-input.ts

@@ -155,6 +155,19 @@ export interface FooterConfig {
   socials?: Partial<Record<FooterSocial, string>>;
 }
 
+/**
+ * The generated `/changelog` index's heading and description. Each is a
+ * string, or a map of locale code to text; the index renders in the default
+ * locale. Unset, they're the `changelog` UI strings (`Changelog` in English),
+ * which `i18n.ui` translates.
+ */
+export interface ChangelogConfig {
+  /** The index's description, below its heading and in its meta description. */
+  description?: LocalizableLabel;
+  /** The index's heading, page title, and OG card title. */
+  title?: LocalizableLabel;
+}
+
 /**
  * Where content lives and how it's discovered. `root`/`include`/`exclude` are
  * zero-config shorthand for a single `filesystem()` source; set `sources` to
@@ -506,6 +519,16 @@ export type SearchProviderConfig = AnySearchAdapter | false;
 
 /** The object form of `search`: the adapter plus adapter-independent settings. */
 export interface SearchOptions {
+  /** What search reports to the configured analytics providers. */
+  analytics?: {
+    /**
+     * Send each query's text with the `search` and `search_select` events.
+     * Defaults to `true`. `false` sends the query's length (`queryChars`)
+     * instead, and the text rides only the `blume:track` DOM event, for a
+     * site to forward on its own terms.
+     */
+    queries?: boolean;
+  };
   /** Indexing behavior. */
   indexing?: {
     /**
@@ -529,7 +552,7 @@ export interface SearchOptions {
 /**
  * Search configuration. Pass an adapter directly (`search: algolia({…})`, or
  * `false`) as shorthand for the object form, which also carries `popular`
- * links and `indexing` settings.
+ * links and `indexing` and `analytics` settings.
  */
 export type SearchConfig = SearchProviderConfig | SearchOptions;
 
@@ -1308,8 +1331,8 @@ export interface MarkdownConfig {
 export interface ReactConfig {
   /**
    * Auto-memoize React components/hooks with the React Compiler
-   * (`babel-plugin-react-compiler`). On by default whenever React is enabled;
-   * set to `false` to skip the compiler's babel pass. Defaults to `true`.
+   * (`oxc-transform-react`). On by default whenever React is enabled;
+   * set to `false` to skip the compiler pass. Defaults to `true`.
    */
   compiler?: boolean;
 }
@@ -1495,6 +1518,11 @@ export interface BlumeConfig {
    * compose: with both set, a page lands at `{deployment.base}/{basePath}/page`.
    */
   basePath?: string;
+  /**
+   * The generated `/changelog` index's title and description, each a string
+   * or a per-locale map. Unset, they're the `changelog` UI strings.
+   */
+  changelog?: ChangelogConfig;
   /**
    * Ask readers before analytics runs, with an adapter from `blume/consent`:
    * `native()` for Blume's own banner, or a hosted consent manager

package/src/core/data.ts

@@ -248,6 +248,8 @@ export interface BlumeDataConfig {
   /** Repository URL for header/edit links, or `null`. */
   repoUrl: string | null;
   search: {
+    /** `search.analytics`: whether the dialog's events carry each query's text. */
+    analytics: { queries: boolean };
     enabled: boolean;
     /** Resolved empty-state links; empty when unset (Search falls back to sidebar). */
     popular: { icon?: string; label: string; route: string }[];

package/src/core/diagnostics.ts

@@ -45,6 +45,7 @@ const DOCS_PATHS = new Map(
     BLUME_DEPENDENCY_MISSING: "/docs/cli/doctor",
     BLUME_DUPLICATE_ROUTE: DOCS_CONTENT_NAVIGATION,
     BLUME_DUPLICATE_SIDEBAR_ORDER: DOCS_CONTENT_NAVIGATION,
+    BLUME_EXAMPLE_NOT_FOUND: "/docs/content/components#component",
     BLUME_FRONTMATTER_INVALID: "/docs/content/frontmatter",
     BLUME_INCLUDE_CYCLE: DOCS_CONTENT_INCLUDES,
     BLUME_INCLUDE_MALFORMED: DOCS_CONTENT_INCLUDES,
@@ -60,13 +61,17 @@ const DOCS_PATHS = new Map(
     BLUME_NAV_INDEX_TITLE_MISMATCH: DOCS_CONTENT_NAVIGATION,
     BLUME_NAV_MISSING_PAGE: DOCS_CONTENT_NAVIGATION,
     BLUME_NODE_VERSION: "/docs/quickstart",
+    BLUME_SEARCH_SYNC_FAILED: "/docs/configuration/search",
     BLUME_SERVER_FEATURE_REQUIRED: DOCS_DEPLOYMENT,
     BLUME_SIDEBAR_DISPLAY_IGNORED: DOCS_CONTENT_NAVIGATION,
     BLUME_SOURCE_FETCH_FAILED: DOCS_CONTENT_SOURCES,
     BLUME_SOURCE_MISCONFIGURED: DOCS_CONTENT_SOURCES,
     BLUME_SOURCE_OFFLINE: DOCS_CONTENT_SOURCES,
+    BLUME_SOURCE_PATH_MISSING: "/docs/content/sources/remote-mdx",
     BLUME_SOURCE_SDK_MISSING: DOCS_CONTENT_SOURCES,
     BLUME_SOURCE_UNAVAILABLE: DOCS_CONTENT_SOURCES,
+    BLUME_SOURCE_UNRESOLVED_LINK: "/docs/content/sources/contentful",
+    BLUME_SOURCE_UNSUPPORTED_NODE: "/docs/content/sources/payload",
     BLUME_TRANSLATE_MISSING: "/docs/cli/translate",
     BLUME_TRANSLATE_STALE: "/docs/cli/translate",
     BLUME_UNKNOWN_COMPONENT: "/docs/configuration/customization",

package/src/core/i18n-ui.ts

@@ -90,6 +90,8 @@ const uiStringsObject = z.object({
         .default(
           "Product updates, new features, and fixes from every release."
         ),
+      // What the index says when it has no entries to list.
+      empty: z.string().default("No changelog entries yet."),
       title: z.string().default("Changelog"),
     })
     .prefault({}),

package/src/core/includes.ts

@@ -242,7 +242,7 @@ export const malformedIncludeDiagnostic = (
     "This <include> isn't a statement Blume can read, so the page shows it as written.",
   severity: "warning",
   suggestion:
-    "Write <include>./path.mdx</include> on a line of its own, or wrap it with the path on its own line and no blank lines; only lang and meta attributes are read.",
+    'Write <include>./path.mdx</include> on a line of its own, or wrap it with the path on its own line and no blank lines. Attributes take lowercase names and quoted values (plan="Pro"): lang and meta shape a code include, and any other is a prop the included file reads as {{name}}.',
 });
 
 /**

package/src/core/links.ts

@@ -312,10 +312,13 @@ const checkPathLink = (
 ): LinkResult => {
   // Page routes carry the site-wide base; an absolute author path is written
   // as if mounted at root, so base it for the route lookup (idempotent — a
-  // relative link already resolved against the based `page.route`). A real
-  // route always wins over the asset-extension heuristic, so a dotted route
-  // (e.g. `/releases/v1.0`) isn't misread as a missing asset.
-  const authoredRoute = toRoute(withBasePath(ctx.basePath, resolved));
+  // relative link already resolved against the based `page.route`). A raw
+  // `<a href>` ships unbased, so it's looked up as written. A real route
+  // always wins over the asset-extension heuristic, so a dotted route (e.g.
+  // `/releases/v1.0`) isn't misread as a missing asset.
+  const authoredRoute = toRoute(
+    link.raw ? resolved : withBasePath(ctx.basePath, resolved)
+  );
   const route = servedRoute(authoredRoute, page, ctx);
   if (ctx.routes.has(route)) {
     return fragment ? checkAnchor(route, fragment, site, ctx, via) : null;
@@ -436,6 +439,12 @@ export interface FileRouteIndex {
    * into the reader's locale onto the fallback copy.
    */
   byDefaultNavPath: Map<string, string>;
+  /**
+   * A staged page's entry id (`<source>/<ref>`) → its route. A remote
+   * source's files have no path on disk, so a file link between two of them
+   * (`./02-errors.mdx`) resolves by entry id, as the rendered link does.
+   */
+  byEntryId: Map<string, string>;
 }
 
 /** The linking side of a file link: where the page's source lives. */
@@ -450,12 +459,19 @@ export const buildFileRouteIndex = (
 ): FileRouteIndex => {
   const bySource = new Map<string, string>();
   const byDefaultNavPath = new Map<string, string>();
+  const byEntryId = new Map<string, string>();
   for (const page of pages) {
-    const { sourcePath } = page;
-    if (!sourcePath || page.fallback) {
+    const { entryId, sourcePath } = page;
+    if (page.fallback) {
       continue;
     }
     const isDefault = page.locale === i18n?.defaultLocale;
+    if (entryId && (!byEntryId.has(entryId) || isDefault)) {
+      byEntryId.set(entryId, page.route);
+    }
+    if (!sourcePath) {
+      continue;
+    }
     if (!bySource.has(sourcePath) || isDefault) {
       bySource.set(sourcePath, page.route);
     }
@@ -463,7 +479,7 @@ export const buildFileRouteIndex = (
       byDefaultNavPath.set(normalize(page.navPath), page.route);
     }
   }
-  return { byDefaultNavPath, bySource };
+  return { byDefaultNavPath, byEntryId, bySource };
 };
 
 /**
@@ -492,11 +508,15 @@ const relativeTarget = (
   ctx: LinkContext
 ): string => {
   const base = { isIndex: isIndexPage(page), route: page.route };
-  const { navPath, sourcePath } = page;
-  const resolveFile = sourcePath
-    ? (path: string) =>
-        routeOfLinkedFile(ctx.fileRoutes, { navPath, sourcePath }, path)
-    : undefined;
+  const { entryId, navPath, sourcePath } = page;
+  let resolveFile: ((path: string) => string | undefined) | undefined;
+  if (sourcePath) {
+    resolveFile = (path) =>
+      routeOfLinkedFile(ctx.fileRoutes, { navPath, sourcePath }, path);
+  } else if (entryId) {
+    resolveFile = (path) =>
+      ctx.fileRoutes.byEntryId.get(normalize(join(dirname(entryId), path)));
+  }
   return (
     resolveRelativeHref(rawPath, base, resolveFile, (route) =>
       ctx.routes.has(route)
@@ -555,9 +575,14 @@ const classifyLink = (
     return fragment ? checkAnchor(page.route, fragment, site, ctx, via) : null;
   }
 
-  const resolved = rawPath.startsWith("/")
-    ? rawPath
-    : relativeTarget(page, rawPath, ctx);
+  let resolved = rawPath;
+  if (!rawPath.startsWith("/")) {
+    // A raw `<a href>` isn't rewritten, so the browser resolves it against
+    // the page's slashless URL: its parent directory, even on an index page.
+    resolved = link.raw
+      ? resolveRelative(page.route, rawPath, false)
+      : relativeTarget(page, rawPath, ctx);
+  }
   return checkPathLink(resolved, fragment, page, link, site, ctx, via);
 };
 
@@ -582,6 +607,8 @@ export const validateLinks = async (
     i18n?: LocaleRouting | null;
     publicDir: string | null;
     checkExternal?: boolean;
+    /** External URLs not to request (`--ignore`). Internal links are always checked. */
+    ignore?: (url: string) => boolean;
     /** Configured redirects; their `from` paths count as valid link targets. */
     redirects?: { from: string }[];
   }
@@ -629,8 +656,11 @@ export const validateLinks = async (
     });
   }
 
-  if (options.checkExternal && external.length > 0) {
-    diagnostics.push(...(await checkExternalLinks(external)));
+  // `--ignore` names URLs that can't be checked from where this runs: a
+  // placeholder host, a local server, a site that turns bots away.
+  const probed = external.filter((ref) => !options.ignore?.(ref.url));
+  if (options.checkExternal && probed.length > 0) {
+    diagnostics.push(...(await checkExternalLinks(probed)));
   }
 
   // A partial spliced into several pages (or every locale of one) yields the

package/src/core/probe.ts

@@ -16,6 +16,8 @@ export interface ProbeResult {
   status?: number;
   timedOut?: boolean;
   error?: string;
+  /** The system error code behind a request that got no response (`ENOTFOUND`). */
+  code?: string;
   /** Whether the request was redirected before landing on `status`. */
   redirected?: boolean;
   /** The URL finally landed on, after following redirects. */
@@ -28,6 +30,18 @@ export interface ProbeResult {
   robotsTag?: string | null;
 }
 
+/**
+ * The reason a request got no response. Node's fetch rejects with a bare
+ * "fetch failed" and puts the system error (`getaddrinfo ENOTFOUND …`, with
+ * its `code`) on `cause`; Bun's rejects with the system error itself.
+ */
+const failure = (error: Error): Pick<ProbeResult, "code" | "error"> => {
+  const reason = error.cause instanceof Error ? error.cause : error;
+  return "code" in reason
+    ? { code: String(reason.code), error: reason.message }
+    : { error: reason.message };
+};
+
 /** Probe a URL with the given method, normalizing failures to a result. */
 const request = async (
   url: string,
@@ -56,10 +70,9 @@ const request = async (
     if (error instanceof Error && error.name === "AbortError") {
       return { ok: false, timedOut: true };
     }
-    return {
-      error: error instanceof Error ? error.message : String(error),
-      ok: false,
-    };
+    const reason =
+      error instanceof Error ? failure(error) : { error: String(error) };
+    return { ...reason, ok: false };
   } finally {
     clearTimeout(timer);
   }
@@ -95,10 +108,17 @@ export const gradeExternal = (
   if (result.timedOut) {
     return { detail: "request timed out", severity: "warning" };
   }
+  // No response at all. A host name that doesn't resolve is as dead as a 404;
+  // a refused, reset, or failed connection is more often someone else's outage
+  // or the runner's own network, so it's graded like a timeout.
   if (result.status === undefined) {
-    return { detail: result.error ?? "unreachable", severity: "error" };
+    return {
+      detail: result.error ?? "unreachable",
+      severity: result.code === "ENOTFOUND" ? "error" : "warning",
+    };
   }
-  // A 404/410 is definitively dead. A 403/429/5xx may well be rate limiting or a
+  // A 404/410 is definitively dead. Any other status — a 401/403 from a site
+  // that turns bots away, a 429, a 5xx — may well be rate limiting or a
   // transient blip, which is not the author's bug to fix.
   if (result.status === STATUS_NOT_FOUND || result.status === STATUS_GONE) {
     return { detail: `HTTP ${result.status}`, severity: "error" };

package/src/core/project-graph.ts

@@ -1,6 +1,6 @@
 import { isAbsolute, relative } from "pathe";
 
-import { withBasePath } from "./base-path.ts";
+import { normalizePath, withBasePath } from "./base-path.ts";
 import { CHANGELOG_INDEX_ROUTE, hasChangelogIndex } from "./changelog-index.ts";
 import { loadConfig } from "./config.ts";
 import { customStaticRoutes, discoverPages } from "./custom-pages.ts";
@@ -19,10 +19,11 @@ import { buildManifest } from "./manifest.ts";
 import { discoverFolderMeta } from "./meta.ts";
 import type { FolderMetaSource } from "./meta.ts";
 import { resolveProjectContext } from "./project.ts";
-import { pathsUnderPattern } from "./redirect-patterns.ts";
+import { isPatternPath, pathsUnderPattern } from "./redirect-patterns.ts";
 import type { ResolvedConfig } from "./schema.ts";
 import { normalizeEntry, strippedLineOffset } from "./sources/normalize.ts";
 import { resolveDocsCollection, resolveSources } from "./sources/resolve.ts";
+import type { SourceRuntime } from "./sources/resolve.ts";
 import type {
   ContentSource,
   SourceEntry,
@@ -309,17 +310,36 @@ const substituteLoadedVariables = (
  * and the Node server serve the page), so the pattern is rejected rather than
  * let the answer depend on the host. `pages` are the served page paths, which
  * carry `basePath`, as the based `from` does.
+ *
+ * An exact redirect from a page's own URL answers the same way everywhere:
+ * Astro ranks its route above the page's catch-all, in dev and build alike,
+ * and writes the redirect page where the page would go, so the page never
+ * publishes. That's a warning rather than an error, since the outcome doesn't
+ * depend on the host.
  */
 const redirectPageDiagnostics = (
   config: ResolvedConfig,
   pages: readonly string[],
   configFile: string | null
 ): Diagnostic[] =>
-  config.redirects.flatMap((redirect) => {
-    const matched = pathsUnderPattern(
-      withBasePath(config.basePath, redirect.from),
-      pages
-    );
+  config.redirects.flatMap((redirect): Diagnostic[] => {
+    const from = withBasePath(config.basePath, redirect.from);
+    if (!isPatternPath(redirect.from)) {
+      const page = normalizePath(from);
+      return pages.includes(page)
+        ? [
+            {
+              code: "BLUME_REDIRECT_MATCHES_PAGE",
+              file: configFile ?? undefined,
+              message: `The redirect from ${redirect.from} is also the page ${page}, which never publishes: its URL redirects to ${redirect.to} instead.`,
+              severity: "warning",
+              suggestion:
+                "If the page moved, delete it or give it a new slug; otherwise remove the redirect.",
+            } satisfies Diagnostic,
+          ]
+        : [];
+    }
+    const matched = pathsUnderPattern(from, pages);
     const [first] = matched;
     if (first === undefined) {
       return [];
@@ -345,6 +365,26 @@ const bannerLinkHref = (
     ? undefined
     : banner.link?.href;
 
+/**
+ * The project's sources, before any of them loads: `beforeSources` sees the
+ * config first, then each source validates itself (e.g. the filesystem
+ * source checks its root exists), replacing the single hard `contentRoot`
+ * check.
+ */
+const validatedSources = (
+  config: ResolvedConfig,
+  context: ProjectContext,
+  runtime: SourceRuntime,
+  beforeSources?: (config: ResolvedConfig) => void
+): ContentSource[] => {
+  beforeSources?.(config);
+  const sources = resolveSources(config, context, runtime);
+  for (const source of sources) {
+    source.validate?.();
+  }
+  return sources;
+};
+
 export const scanProject = async (
   root: string,
   options: {
@@ -356,6 +396,12 @@ export const scanProject = async (
     overrides?: ConfigOverrides;
     /** Relocate the generated runtime (e.g. `.blume-verify` for isolation). */
     runtimeDir?: string;
+    /**
+     * Called with the resolved config before any source loads, so a command
+     * can report an unset secret ahead of a fetch that fails without it: a
+     * source that can't load fails the scan, and nothing after it runs.
+     */
+    beforeSources?: (config: ResolvedConfig) => void;
   } = {}
 ): Promise<BlumeProject> => {
   const mode = options.mode ?? "dev";
@@ -367,17 +413,12 @@ export const scanProject = async (
   const context = resolveProjectContext(root, config, {
     runtimeDir: options.runtimeDir,
   });
-
-  // Each source validates itself (e.g. the filesystem source checks its root
-  // exists), replacing the single hard `contentRoot` check.
-  const sources = resolveSources(config, context, {
-    mode,
-    preview,
-    refresh: options.refresh,
-  });
-  for (const source of sources) {
-    source.validate?.();
-  }
+  const sources = validatedSources(
+    config,
+    context,
+    { mode, preview, refresh: options.refresh },
+    options.beforeSources
+  );
 
   // Folder meta is discovered per filesystem source, under each source's own
   // root and keyed by its route prefix, so a prefixed/root-differing source's

package/src/core/redirect-patterns.ts

@@ -20,6 +20,8 @@
  * `/v2` rather than `/v2/` on every host.
  */
 
+import { normalizePath } from "./base-path.ts";
+
 /** The name `*` captures under, which `_redirects` reads as `:splat`. */
 export const SPLAT = "splat";
 
@@ -401,19 +403,46 @@ export type CompiledRedirect = [
   status: number,
 ];
 
+/** One rule, compiled (see {@link compileRedirects}). */
+const compileRule = (rule: RedirectRule): CompiledRedirect => {
+  const { location, source } = regexRedirect(rule);
+  return [source, encodeURI(location), rule.status];
+};
+
 /**
  * The pattern redirects among `redirects`, compiled for the server wrappers
- * and the dev server, in the order to try them. The `Location` template is
- * percent-encoded as the header needs; a capture is encoded when it's filled
- * (see {@link fillLocation}).
+ * and Vercel's routing config, in the order to try them. The `Location`
+ * template is percent-encoded as the header needs; a capture is encoded when
+ * it's filled (see {@link fillLocation}).
  */
 export const compileRedirects = (
   redirects: readonly RedirectEnds[]
+): CompiledRedirect[] => redirects.flatMap(expandRedirect).map(compileRule);
+
+/**
+ * Every redirect among `redirects` compiled, exact paths first: a pattern as
+ * {@link compileRedirects} compiles it, an exact path as a rule matching
+ * just that path, a trailing slash optional. What the dev server answers
+ * with, where Astro's own handler would send an exact redirect to a page
+ * served by `[...slug]` as a `301` whatever its status.
+ */
+export const compileEveryRedirect = (
+  redirects: readonly RedirectEnds[]
 ): CompiledRedirect[] =>
-  redirects.flatMap(expandRedirect).map((rule) => {
-    const { location, source } = regexRedirect(rule);
-    return [source, encodeURI(location), rule.status];
-  });
+  exactFirst(redirects)
+    .flatMap((redirect) => {
+      const rules = expandRedirect(redirect);
+      return rules.length > 0
+        ? rules
+        : [
+            {
+              parts: [{ kind: "text", text: normalizePath(redirect.from) }],
+              status: redirect.status,
+              to: redirect.to,
+            } satisfies RedirectRule,
+          ];
+    })
+    .map(compileRule);
 
 /** A captured value, encoded for a `Location` header that must not grow a query or fragment. */
 export const encodeCapture = (value: string): string =>

package/src/core/schema.ts

@@ -485,6 +485,16 @@ const footerConfigSchema = z.strictObject({
   socials: z.partialRecord(z.enum(FOOTER_SOCIALS), z.string()).default({}),
 });
 
+/**
+ * The generated `/changelog` index. Its title and description may be
+ * per-locale maps; unset, they're the `changelog` UI strings `i18n.ui`
+ * translates.
+ */
+const changelogConfigSchema = z.strictObject({
+  description: localizableLabelSchema.optional(),
+  title: localizableLabelSchema.optional(),
+});
+
 /** A validated `content.sources` entry: an adapter descriptor from `blume/sources`. */
 export type { ContentSourceAdapter } from "../sources/registry.ts";
 
@@ -778,9 +788,17 @@ const searchIndexingSchema = z
   })
   .prefault({});
 
+/** What the search dialog's analytics events carry. */
+const searchAnalyticsSchema = z
+  .strictObject({
+    queries: z.boolean().default(true),
+  })
+  .prefault({});
+
 /** The object form of `search`: the adapter plus its adapter-independent settings. */
 const searchOptionsSchema = z.strictObject(
   {
+    analytics: searchAnalyticsSchema,
     indexing: searchIndexingSchema,
     /** Curated links for the Cmd+K empty state; defaults to the first sidebar pages. */
     popular: z.array(searchPopularLinkSchema).default([]),
@@ -2022,9 +2040,9 @@ const markdownConfigSchema = z.strictObject(
 const reactConfigSchema = z.strictObject({
   /**
    * Auto-memoize React components/hooks with the React Compiler
-   * (`babel-plugin-react-compiler`). On by default whenever React is enabled
+   * (`oxc-transform-react`). On by default whenever React is enabled
    * (a project `.tsx`/`.jsx`, a React island/example/override, or the assistant); set
-   * to `false` to skip the compiler's babel pass.
+   * to `false` to skip the compiler pass.
    */
   compiler: z.boolean().default(true),
 });
@@ -2102,6 +2120,7 @@ export const blumeConfigSchema = z
         })
         .optional()
         .transform((value) => normalizeBasePath(value)),
+      changelog: changelogConfigSchema.optional(),
       // An adapter from `blume/consent`; analytics waits for the reader.
       consent: consentConfigSchema,
       content: contentConfigSchema.prefault({}),

package/src/core/sources/cache.ts

@@ -109,6 +109,9 @@ export const snapshotCache = (cacheDir: string): SnapshotCache => {
  * snapshot exists, serve it without fetching (cache-first dev). On fetch failure,
  * serve the last-known-good snapshot with a warning so a CMS/network outage
  * doesn't fail the build; if there is no snapshot either, surface a hard error.
+ * A `BlumeError` from the source (a missing SDK or token, checked before any
+ * request, or a misconfiguration) already names its cause, so without a
+ * snapshot it surfaces as itself rather than as a fetch failure.
  */
 export const loadWithCache = async (
   name: string,
@@ -138,6 +141,9 @@ export const loadWithCache = async (
       };
       return { diagnostics: [diagnostic], entries: fallback };
     }
+    if (error instanceof BlumeError) {
+      throw error;
+    }
     // SAFETY: same invariant as above — `fetchEntries` failures are Errors.
     throw new BlumeError({
       code: "BLUME_SOURCE_FETCH_FAILED",

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

@@ -1,7 +1,8 @@
 /**
  * Contentful rich text → Markdown. Covers the block, inline, and mark types
  * the Rich Text editor emits; embedded entries fall through to a serializer
- * keyed by content type or are noted in a comment. Links to assets and
+ * keyed by content type or are noted in a comment, and a link to an entry
+ * points at its page when the source says it has one. Links to assets and
  * entries arrive unresolved from the Delivery API (`data.target` is a
  * `sys` link), so the source hands in resolvers over the response's
  * `includes`; a document the SDK already resolved (with `fields` inline)
@@ -25,14 +26,22 @@ import {
   writesMdx,
 } from "./lower.ts";
 
-/** An asset's file as a Markdown image needs it. */
+/** An asset's file as a Markdown image or link needs it. */
 export interface ContentfulAsset {
+  /** The file's MIME type; an asset that isn't an image renders as a link. */
+  contentType?: string;
   description?: string;
+  fileName?: string;
   title?: string;
   url: string;
 }
 
 export interface ContentfulRichTextOptions {
+  /**
+   * The route of a linked entry's page; an entry hyperlink to an entry with
+   * none keeps only its text.
+   */
+  entryHref?: (entry: JsonObject) => string | undefined;
   /** Resolve an asset link (`data.target.sys.id`) to its file. */
   resolveAsset?: (id: string) => ContentfulAsset | null;
   /** Resolve an entry link to the entry (`sys` plus `fields`). */
@@ -55,7 +64,9 @@ export const assetFromEntry = (asset: JsonObject): ContentfulAsset | null => {
     return null;
   }
   return {
+    contentType: asString(getPath(asset, "fields.file.contentType")),
     description: asString(getPath(asset, "fields.description")),
+    fileName: asString(getPath(asset, "fields.file.fileName")),
     title: asString(getPath(asset, "fields.title")),
     url: absoluteUrl(url),
   };
@@ -166,11 +177,16 @@ const inlineNodeParts = (
         linkedAsset(node, options)?.url
       );
     }
+    case "entry-hyperlink": {
+      const entry = linkedTarget(node, options.resolveEntry);
+      const href = entry ? options.entryHref?.(entry) : undefined;
+      return linkParts(inlineParts(children(node), options), href);
+    }
     case "embedded-entry-inline": {
       return [{ markdown: embeddedEntry(node, options) }];
     }
     default: {
-      // entry-hyperlink (no route to point at) and anything unknown: the label.
+      // Anything unknown: the label.
       return inlineParts(children(node), options);
     }
   }
@@ -264,11 +280,18 @@ const renderBlock = (
     }
     case "embedded-asset-block": {
       const asset = linkedAsset(node, options);
+      if (!asset) {
+        return "";
+      }
+      // Any file can be embedded: one that isn't an image (a PDF, a video)
+      // would render as a broken image, so it's a link to the file.
+      if (asset.contentType && !asset.contentType.startsWith("image/")) {
+        const label = asset.title ?? asset.fileName ?? asset.url;
+        return renderInline(linkParts([{ marks: {}, text: label }], asset.url));
+      }
       // Contentful's own rich-text renderer uses the description as alt text
       // and the title only as a fallback.
-      return asset
-        ? image(asset.description ?? asset.title ?? "", asset.url)
-        : "";
+      return image(asset.description ?? asset.title ?? "", asset.url);
     }
     case "embedded-entry-block": {
       return embeddedEntry(node, options);