blume 0.6.0 → 0.6.2

package/src/core/config.ts

@@ -1,16 +1,139 @@
 import { existsSync, readFileSync } from "node:fs";
 
+import type { BlumeConfig } from "./config-input.ts";
 import { applyDeploymentEnv } from "./deployment-env.ts";
 import { BlumeError, diagnosticsFromZod } from "./diagnostics.ts";
 import { createModuleLoader } from "./load-module.ts";
 import { findConfigFile } from "./project.ts";
 import { blumeConfigSchema } from "./schema.ts";
-import type { BlumeConfig, ResolvedConfig } from "./schema.ts";
+import type { ResolvedConfig } from "./schema.ts";
 import type { Diagnostic } from "./types.ts";
 
 /**
- * Identity helper for authoring `blume.config.ts`. Exists for type inference
- * and a stable future home for plugin hooks; it does not transform input.
+ * Define a Blume site's configuration with full type-checking and editor
+ * autocomplete. Place the call in `blume.config.ts` at your project root and
+ * `export default` the result:
+ *
+ * ```ts
+ * import { defineConfig } from "blume";
+ *
+ * export default defineConfig({
+ *   title: "Acme Docs",
+ *   description: "Everything you need to build with Acme.",
+ * });
+ * ```
+ *
+ * Every field is optional — an empty `defineConfig({})` produces a working
+ * site from the Markdown/MDX in your `docs/` directory. Configure only what you
+ * want to change; sensible defaults fill in the rest.
+ *
+ * This is an identity helper: it returns its input unchanged and exists purely
+ * for type inference (and as a stable home for future plugin hooks). The object
+ * is validated against the Blume schema when the CLI loads it.
+ *
+ * ## Top-level fields
+ *
+ * **Site identity**
+ * - `title` — site title, shown in the header, `<title>`, and OG images.
+ *   Defaults to `"Documentation"`.
+ * - `description` — default meta description, used where a page sets none.
+ * - `logo` — brand mark. A string is an image path/URL; the object form splits
+ *   an `image` mark from wordmark `text` and can override the brand `href`.
+ * - `banner` — site-wide announcement bar; a string, or `{ content, link,
+ *   dismissible }`.
+ *
+ * **Content & navigation**
+ * - `content` — where content lives (`root`, defaults to `docs`) and pluggable
+ *   `sources` (filesystem, remote MDX, GitHub Releases, Sanity, Notion, or a
+ *   custom `ContentSource`). Omit `sources` and the top-level `root` becomes one
+ *   implicit filesystem source.
+ * - `navigation` — sidebar, header `tabs`, `selectors` (version/language/product
+ *   switchers), pinned `featured` links, and the `repo` link toggle. Omit
+ *   `sidebar` to generate it from the content tree.
+ * - `redirects` — `{ from, to, status }` rules (301 by default).
+ * - `github` — `{ owner, repo, branch, dir }`, powering "Edit this page" links
+ *   and the header repo link.
+ *
+ * **Appearance**
+ * - `theme` — `accent` color, `fonts` (curated Google Font slugs), `radius`,
+ *   `mode` (`system`/`light`/`dark`), `background`, and `strict` token mode.
+ * - `markdown` — `code` (language icons, inline highlighting, line wrap),
+ *   `headingAnchors`, `imageZoom`, and opt-in KaTeX `math`.
+ * - `toc` — on-page table of contents; `true`/`false` or a heading-level range.
+ * - `lastModified` — "Last updated" stamps from `git` history or frontmatter.
+ * - `feedback` — the per-page "Was this helpful?" widget (on by default).
+ * - `export` — reader-facing PDF/EPUB export actions (off by default).
+ *
+ * **Reference docs**
+ * - `openapi` — native OpenAPI reference: one real page per operation, woven
+ *   into the sidebar and search. Point `sources`/`spec` at your spec.
+ * - `asyncapi` — AsyncAPI reference via the embedded Scalar renderer.
+ *
+ * **Search & AI**
+ * - `search` — search backend `provider` (`orama` by default; `pagefind`,
+ *   `algolia`, `typesense`, `orama-cloud`, `mixedbread`, or `none`) plus its
+ *   credential block.
+ * - `ai` — `ask` (the Ask AI chat endpoint and its provider/model) and `llmsTxt`
+ *   (emit `llms.txt`).
+ * - `mcp` — expose the docs as an MCP server for connecting agents.
+ *
+ * **SEO, feeds & analytics**
+ * - `seo` — `og` images, `sitemap`, `robots`, `rss` feeds, `structuredData`
+ *   JSON-LD, `agentReadability`, and robots `contentSignals`.
+ * - `analytics` — PostHog, Vercel, or arbitrary `scripts` (Plausible, Fathom,
+ *   GA, …).
+ *
+ * **Deployment & i18n**
+ * - `deployment` — `site` URL (needed for absolute links, sitemaps, and OG),
+ *   `adapter` (`vercel`/`node`/`netlify`/`cloudflare`), `output`
+ *   (`static`/`server`), and `base` path. Auto-detected on Vercel/Netlify/
+ *   Cloudflare from the platform env.
+ * - `i18n` — opt-in multi-locale: `locales`, `defaultLocale`, `parser`
+ *   (`dir` vs filename `dot` suffix), and per-locale UI overrides.
+ *
+ * - `examples` — where `<Component path>` previews resolve their source from
+ *   (defaults to `examples/`; supports a glob for colocated registries).
+ *
+ * @example Zero-config — just render the Markdown under `docs/`.
+ * ```ts
+ * export default defineConfig({});
+ * ```
+ *
+ * @example A production docs site with theming, search, and deployment.
+ * ```ts
+ * export default defineConfig({
+ *   title: "Acme Docs",
+ *   description: "Build faster with Acme.",
+ *   logo: { image: "/logo.svg", text: "Acme" },
+ *   github: { owner: "acme", repo: "acme" },
+ *   theme: { accent: "violet", fonts: { body: "inter" }, radius: "lg" },
+ *   navigation: {
+ *     tabs: [
+ *       { label: "Guides", path: "/guides" },
+ *       { label: "API", path: "/api" },
+ *     ],
+ *   },
+ *   search: { provider: "orama" },
+ *   deployment: { site: "https://docs.acme.com", adapter: "vercel" },
+ * });
+ * ```
+ *
+ * @example An OpenAPI reference with the Ask AI assistant enabled.
+ * ```ts
+ * export default defineConfig({
+ *   title: "Acme API",
+ *   openapi: {
+ *     enabled: true,
+ *     route: "/reference",
+ *     sources: [{ label: "Core", spec: "./openapi.json" }],
+ *   },
+ *   ai: { ask: { enabled: true }, llmsTxt: true },
+ * });
+ * ```
+ *
+ * @param config - The site configuration. All fields are optional.
+ * @returns The same config object, typed for inference.
+ * @see https://useblume.dev/docs for the full configuration reference.
  */
 export const defineConfig = (config: BlumeConfig): BlumeConfig => config;
 

package/src/core/i18n.ts

@@ -111,13 +111,14 @@ export const localePlacement = (
 
   if (i18n.parser === "dot") {
     const lastDot = base.lastIndexOf(".");
-    // Only a dot inside the filename (not a directory) is a locale suffix.
+    // Only a dot inside the filename (not a directory) is a locale suffix. Any
+    // configured locale counts — including the default, so the symmetric
+    // authoring `intro.en.mdx` + `intro.fr.mdx` shares one translation key
+    // instead of routing the default file to a literal `/intro.en`.
     if (lastDot > base.lastIndexOf("/")) {
       const suffix = base.slice(lastDot + 1);
-      const isNonDefault = i18n.locales.some(
-        (locale) => locale.code !== i18n.defaultLocale && locale.code === suffix
-      );
-      if (isNonDefault) {
+      const matched = i18n.locales.some((locale) => locale.code === suffix);
+      if (matched) {
         return {
           locales: [suffix],
           navPath: `${base.slice(0, lastDot)}${ext}`,

package/src/core/links.ts

@@ -12,6 +12,15 @@ import type {
 const HTTP = /^https?:\/\//iu;
 const PROTOCOL_RELATIVE = /^\/\//u;
 const SCHEME = /^[a-z][a-z0-9+.-]*:/iu;
+
+/** Percent-decode a link piece; malformed sequences stay verbatim. */
+const decodePercent = (value: string): string => {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+};
 const DOC_EXT = /\.(?:md|mdx)$/iu;
 const FILE_EXT = /\.[a-z0-9]+$/iu;
 
@@ -309,12 +318,18 @@ const classifyLink = (
   }
 
   const hashIndex = target.indexOf("#");
-  const fragment = hashIndex === -1 ? "" : target.slice(hashIndex + 1);
+  // Browser-copied links arrive percent-encoded (`/caf%C3%A9`, `#caf%C3%A9`)
+  // while routes and anchor slugs are stored decoded — decode before comparing
+  // so valid links aren't reported broken.
+  const fragment = decodePercent(
+    hashIndex === -1 ? "" : target.slice(hashIndex + 1)
+  );
   let rawPath = hashIndex === -1 ? target : target.slice(0, hashIndex);
   const queryIndex = rawPath.indexOf("?");
   if (queryIndex !== -1) {
     rawPath = rawPath.slice(0, queryIndex);
   }
+  rawPath = decodePercent(rawPath);
 
   if (rawPath === "") {
     return fragment ? checkAnchor(page.route, fragment, site, ctx) : null;

package/src/core/meta.ts

@@ -21,75 +21,135 @@ const META_FILES = [
 const resolveMeta = async (mod: unknown): Promise<unknown> =>
   typeof mod === "function" ? await (mod as () => unknown)() : mod;
 
+/** A filesystem content source to scan for folder meta: its on-disk root and
+ * optional route prefix. The prefix is folded into every key so meta lines up
+ * with the sidebar group path, which carries the same prefix. */
+export interface FolderMetaSource {
+  root: string;
+  prefix?: string;
+}
+
 /**
- * Discover `meta.{ts,js,mjs}` files under the content root. Keys are the
- * directory path relative to the content root (`""` for the root directory).
- * `meta.$.*` files are returned in `shared` — folder meta that applies to that
- * directory in every locale (a locale-specific `meta.*` overrides it). Each file
- * default-exports an object or a (sync/async) function returning one.
+ * The folder-meta key for a directory. Mirrors the sidebar group path: the
+ * source's route prefix (`docs`) followed by the directory relative to the
+ * source root (`provider`) — so `docs/provider/meta.ts` under a `prefix: "docs"`
+ * source keys to `docs/provider`, exactly the group path navigation builds.
+ */
+const metaKeyFor = (prefix: string | undefined, dir: string): string => {
+  const clean = prefix ? prefix.replaceAll(/^\/+|\/+$/gu, "") : "";
+  if (!clean) {
+    return dir;
+  }
+  return dir ? `${clean}/${dir}` : clean;
+};
+
+/**
+ * Discover `meta.{ts,js,mjs}` files across the given filesystem sources. Keys are
+ * the source's route prefix joined with the directory relative to that source's
+ * root (`""`/the prefix itself for a source's root directory), so meta matches
+ * the prefixed sidebar group path. A bare string is shorthand for a single,
+ * unprefixed source (the default project layout). `meta.$.*` files are returned
+ * in `shared` — folder meta that applies to that directory in every locale (a
+ * locale-specific `meta.*` overrides it). Each file default-exports an object or
+ * a (sync/async) function returning one.
+ *
+ * `localeDirs` names the top-level locale directories of a `dir`-parser i18n
+ * project. Navigation looks locale meta up as `locale/<group path>` where the
+ * group path starts with the source prefix, so a locale directory found at a
+ * source root is hoisted in front of the prefix (`docs/fr/guides/meta.ts` keys
+ * to `fr/docs/guides`, not `docs/fr/guides`).
  */
 export const discoverFolderMeta = async (
-  contentRoot: string
+  sources: string | FolderMetaSource[],
+  options: { localeDirs?: readonly string[] } = {}
 ): Promise<{
   meta: Map<string, FolderMeta>;
   shared: Map<string, FolderMeta>;
   diagnostics: Diagnostic[];
 }> => {
-  const files = await glob(META_FILES, {
-    absolute: true,
-    cwd: contentRoot,
-    // Never descend into dependencies or build output — relevant when the
-    // content root is the project root (e.g. a `.`-rooted or all-staged project).
-    ignore: ["**/node_modules/**", "**/.blume/**", "**/dist/**"],
-    onlyFiles: true,
-  });
+  const list: FolderMetaSource[] =
+    typeof sources === "string" ? [{ root: sources }] : sources;
+  const localeDirs = new Set(options.localeDirs);
 
   const load = createModuleLoader();
-  const loaded = await Promise.all(
-    files.map(
-      async (
-        file
-      ): Promise<
-        | { ok: true; file: string; value: unknown }
-        | { ok: false; file: string; error: Error }
-      > => {
-        try {
-          return { file, ok: true, value: await resolveMeta(await load(file)) };
-        } catch (error) {
-          return { error: error as Error, file, ok: false };
-        }
-      }
-    )
-  );
-
   const meta = new Map<string, FolderMeta>();
   const shared = new Map<string, FolderMeta>();
   const diagnostics: Diagnostic[] = [];
 
-  for (const entry of loaded) {
-    const dir = relative(contentRoot, dirname(entry.file));
-
-    if (!entry.ok) {
-      diagnostics.push({
-        code: "BLUME_META_LOAD_FAILED",
-        file: entry.file,
-        message: `Could not load meta file: ${entry.error.message}`,
-        severity: "error",
+  // Scan every source under its own root so a source rooted outside
+  // `content.root` still contributes its folder meta.
+  const perSource = await Promise.all(
+    list.map(async (source) => {
+      const files = await glob(META_FILES, {
+        absolute: true,
+        cwd: source.root,
+        // Never descend into dependencies or build output — relevant when the
+        // root is the project root (e.g. a `.`-rooted or all-staged project).
+        ignore: ["**/node_modules/**", "**/.blume/**", "**/dist/**"],
+        onlyFiles: true,
       });
-      continue;
-    }
+      const loaded = await Promise.all(
+        files.map(
+          async (
+            file
+          ): Promise<
+            | { ok: true; file: string; value: unknown }
+            | { ok: false; file: string; error: Error }
+          > => {
+            try {
+              return {
+                file,
+                ok: true,
+                value: await resolveMeta(await load(file)),
+              };
+            } catch (error) {
+              return { error: error as Error, file, ok: false };
+            }
+          }
+        )
+      );
+      return { loaded, source };
+    })
+  );
+
+  for (const { loaded, source } of perSource) {
+    for (const entry of loaded) {
+      const dir = relative(source.root, dirname(entry.file));
+      const [head, ...tail] = dir.split("/");
+      // A locale directory sits between the source root and the folder, but the
+      // lookup key carries the locale in front of the (prefixed) group path.
+      const key =
+        head && localeDirs.has(head)
+          ? `${head}/${metaKeyFor(source.prefix, tail.join("/"))}`.replace(
+              /\/$/u,
+              ""
+            )
+          : metaKeyFor(source.prefix, dir);
 
-    const result = folderMetaSchema.safeParse(entry.value);
-    if (result.success) {
-      const target = basename(entry.file).startsWith("meta.$.") ? shared : meta;
-      target.set(dir, result.data);
-    } else {
-      diagnostics.push(
-        ...diagnosticsFromZod(result.error, {
-          code: "BLUME_META_INVALID",
+      if (!entry.ok) {
+        diagnostics.push({
+          code: "BLUME_META_LOAD_FAILED",
           file: entry.file,
-        })
-      );
+          message: `Could not load meta file: ${entry.error.message}`,
+          severity: "error",
+        });
+        continue;
+      }
+
+      const result = folderMetaSchema.safeParse(entry.value);
+      if (result.success) {
+        const target = basename(entry.file).startsWith("meta.$.")
+          ? shared
+          : meta;
+        target.set(key, result.data);
+      } else {
+        diagnostics.push(
+          ...diagnosticsFromZod(result.error, {
+            code: "BLUME_META_INVALID",
+            file: entry.file,
+          })
+        );
+      }
     }
   }
 

package/src/core/navigation.ts

@@ -228,6 +228,7 @@ const buildFileSystemSidebar = (
     // Group by the locale-stripped path so the locale dir is not a nav group.
     const parts = page.navPath.split("/");
     const filename = parts.at(-1) ?? page.navPath;
+    const stem = filename.replace(extname(filename), "");
     const dirs = parts.slice(0, -1);
 
     // Each group's URL path is the matching prefix of the page's route. navPath
@@ -235,13 +236,22 @@ const buildFileSystemSidebar = (
     // align the folder segments from the right (the extra leading segments are
     // that prefix). Under such a prefix the path won't match a logical tab path,
     // so tab-scoping simply no-ops — same as the header's active-tab logic.
-    const folderParts = page.route.split("/").filter(Boolean).slice(0, -1);
-    const offset = Math.max(0, folderParts.length - dirs.length);
+    // An index page's route IS its folder's route (no page segment to drop),
+    // and `(group)` folders contribute no route segment at all.
+    const routeSegments = page.route.split("/").filter(Boolean);
+    const folderParts =
+      stem === "index" ? routeSegments : routeSegments.slice(0, -1);
+    const routeDirCount = dirs.filter((dir) => !GROUP_FOLDER.test(dir)).length;
+    const offset = Math.max(0, folderParts.length - routeDirCount);
 
     let parent = root;
-    for (const [index, dir] of dirs.entries()) {
+    let consumed = offset;
+    for (const dir of dirs) {
       parent = ensureGroup(parent, dir);
-      parent.routePath ??= `/${folderParts.slice(0, offset + index + 1).join("/")}`;
+      if (!GROUP_FOLDER.test(dir)) {
+        consumed += 1;
+      }
+      parent.routePath ??= `/${folderParts.slice(0, consumed).join("/")}`;
     }
 
     parent.children.push({
@@ -249,7 +259,7 @@ const buildFileSystemSidebar = (
       deprecated: page.meta.deprecated || undefined,
       description: page.description,
       icon: page.meta.sidebar.icon,
-      key: segmentKey(filename.replace(extname(filename), "")),
+      key: segmentKey(stem),
       kind: "page",
       label: page.meta.sidebar.label ?? page.title,
       order: pageOrder(page, filename),

package/src/core/project-graph.ts

@@ -1,3 +1,5 @@
+import { relative } from "pathe";
+
 import { loadConfig } from "./config.ts";
 import { buildContentGraph } from "./graph.ts";
 import { i18nDiagnostics } from "./i18n.ts";
@@ -7,10 +9,11 @@ import {
 } from "./last-modified.ts";
 import { buildManifest } from "./manifest.ts";
 import { discoverFolderMeta } from "./meta.ts";
+import type { FolderMetaSource } from "./meta.ts";
 import { resolveProjectContext } from "./project.ts";
 import type { ResolvedConfig } from "./schema.ts";
 import { normalizeEntry } from "./sources/normalize.ts";
-import { resolveSources } from "./sources/resolve.ts";
+import { resolveDocsCollection, resolveSources } from "./sources/resolve.ts";
 import type { ContentSource } from "./sources/types.ts";
 import type {
   BlumeManifest,
@@ -70,6 +73,48 @@ export interface BlumeProject {
   sources: ContentSource[];
 }
 
+/**
+ * Guard the invariant that ties a filesystem page to the `docs` collection:
+ * Astro ids each collection entry by its path relative to the collection base,
+ * so `getEntry("docs", entryId)` only resolves when that entry id equals
+ * `relative(base, file)`. A filesystem source ids entries relative to its own
+ * root; when that root can't be the collection base (e.g. a second filesystem
+ * source rooted elsewhere), the ids diverge and every one of that source's pages
+ * would 404 in dev (a static build silently masks it). Emit a hard error naming
+ * the mismatch so it can't ship, instead of a silent runtime failure. One
+ * diagnostic per file (locale duplicates share a source path).
+ */
+const entryIdDiagnostics = (
+  pages: PageRecord[],
+  collectionBase: string
+): Diagnostic[] => {
+  const diagnostics: Diagnostic[] = [];
+  const seen = new Set<string>();
+  for (const page of pages) {
+    // Only filesystem entries render through the base-rooted `docs` collection;
+    // staged sources carry their own id and collection.
+    if (page.collection || !page.sourcePath || seen.has(page.sourcePath)) {
+      continue;
+    }
+    seen.add(page.sourcePath);
+    const expected = relative(collectionBase, page.sourcePath)
+      .split("\\")
+      .join("/");
+    const entryId = page.entryId ?? page.source.ref;
+    if (expected !== entryId) {
+      diagnostics.push({
+        code: "BLUME_ENTRY_ID_MISMATCH",
+        file: page.sourcePath,
+        message: `Content source "${page.source.name}" is rooted outside the docs collection base, so ${page.route} resolves entry id "${entryId}" but the collection would generate "${expected}" — the page would 404 at runtime.`,
+        severity: "error",
+        suggestion:
+          "Give each filesystem source a root under content.root, or use a single filesystem source so the collection can root at it.",
+      });
+    }
+  }
+  return diagnostics;
+};
+
 /**
  * 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.
@@ -110,13 +155,33 @@ export const scanProject = async (
     source.validate?.();
   }
 
+  // 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
+  // `meta.ts` still lines up with its (prefixed) sidebar group path.
+  const metaSources: FolderMetaSource[] = sources
+    .filter((source) => !source.staged && source.contentRoot)
+    .map((source) => ({
+      prefix: source.prefix,
+      root: source.contentRoot ?? "",
+    }));
+
   // Run every source's `load()` in parallel, then funnel each entry through the
   // shared `normalizeEntry` so route mapping is identical regardless of origin.
+  // Under the `dir` parser, non-default locales are top-level directories whose
+  // meta keys must carry the locale in front of the source prefix (see
+  // `discoverFolderMeta`).
+  const localeDirs =
+    config.i18n && config.i18n.parser === "dir"
+      ? config.i18n.locales
+          .map((locale) => locale.code)
+          .filter((code) => code !== config.i18n?.defaultLocale)
+      : undefined;
+
   const [loaded, folderMeta] = await Promise.all([
     Promise.all(
       sources.map(async (source) => ({ source, ...(await source.load()) }))
     ),
-    discoverFolderMeta(context.contentRoot),
+    discoverFolderMeta(metaSources, { localeDirs }),
   ]);
 
   const allPages: PageRecord[] = [];
@@ -180,6 +245,7 @@ export const scanProject = async (
     diagnostics: [
       ...contentDiagnostics,
       ...folderMeta.diagnostics,
+      ...entryIdDiagnostics(pages, resolveDocsCollection(config, context).base),
       ...graph.diagnostics,
       ...i18nWarnings,
     ],

package/src/core/schema.ts

@@ -109,7 +109,8 @@ const pageMetaBaseSchema = z
     sidebar: sidebarMetaSchema.default({}),
     slug: z.string().optional(),
     title: z.string().optional(),
-    type: z.string().default("doc"),
+    // No default: an absent `type` must fall through to `content.defaultType`.
+    type: z.string().optional(),
   })
   .strict();
 
@@ -925,12 +926,6 @@ const codeConfigSchema = z
      * …). On by default; recognized languages only.
      */
     icons: z.boolean().default(true),
-    /**
-     * Syntax-highlight inline `` `code{:lang}` `` snippets. Off by default — most
-     * inline code (flags, file names) reads better plain; opt a snippet in with
-     * a trailing `{:lang}` marker.
-     */
-    inline: z.boolean().default(false),
     /**
      * Wrap long lines instead of scrolling horizontally. Off by default, so
      * code keeps its original line breaks and overflows into a scroll area.
@@ -955,11 +950,6 @@ const markdownConfigSchema = z
      * opt a single image out with `data-no-zoom`.
      */
     imageZoom: z.boolean().default(true),
-    /**
-     * Enable LaTeX math (`$…$` inline, `$$…$$` block) rendered with KaTeX.
-     * Off by default since `$` is common in prose, shell, and code. MDX only.
-     */
-    math: z.boolean().default(false),
   })
   .strict();
 
@@ -1097,8 +1087,12 @@ export type ResolvedConfig = z.infer<typeof blumeConfigSchema>;
 export type ResolvedI18nConfig = z.infer<typeof i18nConfigSchema>;
 /** A configured locale with display metadata. */
 export type LocaleConfig = z.infer<typeof localeSchema>;
-/** User-authored config: the shape accepted by `defineConfig`. */
-export type BlumeConfig = z.input<typeof blumeConfigSchema>;
+/**
+ * User-authored config, straight off the schema. The public, hand-documented
+ * authoring type is `BlumeConfig` in `./config-input.ts`, which a compile-time
+ * guard keeps structurally identical to this.
+ */
+export type BlumeConfigInput = z.input<typeof blumeConfigSchema>;
 /** A configured search backend. */
 export type SearchProvider = (typeof searchProviders)[number];
 /** Resolved robots.txt `Content-Signal` preferences (`null` when disabled). */

package/src/core/sources/assets.ts

@@ -8,6 +8,11 @@ import { hashText } from "./cache.ts";
 const MD_IMAGE = /!\[(?<alt>[^\]]*)\]\((?<url>[^)\s]+)\)/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;
 
 /** Where to write downloaded assets and how to reference them publicly. */
 export interface AssetContext {
@@ -37,8 +42,17 @@ export const materializeAssets = async (
   const doFetch = ctx.fetchImpl ?? globalThis.fetch;
   const diagnostics: Diagnostic[] = [];
 
+  // Mask fenced code blocks so an image URL inside a code sample is neither
+  // downloaded nor rewritten — the sample must keep showing what the author
+  // wrote.
+  const fences: string[] = [];
+  const masked = markdown.replace(CODE_FENCE_BLOCK, (block) => {
+    fences.push(block);
+    return `\u0000blume-fence-${fences.length - 1}\u0000`;
+  });
+
   const urls = new Set<string>();
-  for (const match of markdown.matchAll(MD_IMAGE)) {
+  for (const match of masked.matchAll(MD_IMAGE)) {
     const url = match.groups?.url;
     if (url && REMOTE.test(url)) {
       urls.add(url);
@@ -68,10 +82,12 @@ export const materializeAssets = async (
     })
   );
 
-  const rewritten = markdown.replaceAll(MD_IMAGE, (match, alt, url) => {
-    const local = rewrites.get(url);
-    return local ? `![${alt}](${local})` : match;
-  });
+  const rewritten = masked
+    .replaceAll(MD_IMAGE, (match, alt, url) => {
+      const local = rewrites.get(url);
+      return local ? `![${alt}](${local})` : match;
+    })
+    .replaceAll(FENCE_TOKEN, (token, index) => fences[Number(index)] ?? token);
 
   return { diagnostics, markdown: rewritten };
 };