npm - blume - Versions diffs - 0.6.1 → 0.6.2 - Mend

blume 0.6.1 → 0.6.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (51) hide show

package/dist/cli/index.js +5955 -5733
package/dist/cli/index.js.map +37 -37
package/dist/types/core/config-input.d.ts +1 -11
package/dist/types/core/schema.d.ts +4 -4
package/dist/types/core/sources/types.d.ts +6 -0
package/package.json +1 -1
package/src/astro/generate.ts +23 -13
package/src/astro/markdown-negotiation.ts +12 -3
package/src/astro/templates.ts +28 -7
package/src/cli/commands/dev.ts +30 -14
package/src/cli/commands/doctor.ts +35 -7
package/src/cli/commands/sync.ts +14 -2
package/src/cli/dev-lock.ts +40 -10
package/src/cli/env.ts +5 -1
package/src/components/islands/ask-ai.tsx +3 -1
package/src/components/islands/hooks.ts +5 -1
package/src/components/layout/Header.astro +10 -2
package/src/components/layout/NavSelector.astro +5 -3
package/src/components/layout/PageLayout.astro +2 -1
package/src/components/layout/ReferenceLayout.astro +1 -0
package/src/components/layout/RootLayout.astro +16 -2
package/src/components/layout/Search.astro +8 -3
package/src/components/layout/nav-utils.ts +7 -3
package/src/core/config-input.ts +1 -11
package/src/core/i18n.ts +6 -5
package/src/core/links.ts +16 -1
package/src/core/meta.ts +112 -52
package/src/core/navigation.ts +15 -5
package/src/core/project-graph.ts +68 -2
package/src/core/schema.ts +2 -1
package/src/core/sources/assets.ts +21 -5
package/src/core/sources/cache.ts +19 -1
package/src/core/sources/github-releases.ts +9 -3
package/src/core/sources/mdx-remote.ts +14 -4
package/src/core/sources/normalize.ts +13 -1
package/src/core/sources/notion.ts +43 -7
package/src/core/sources/resolve.ts +44 -1
package/src/core/sources/sanity.ts +9 -3
package/src/core/sources/types.ts +6 -0
package/src/deploy/rss.ts +3 -1
package/src/markdown/code-title.ts +11 -4
package/src/markdown/package-commands.ts +13 -0
package/src/og/card.ts +3 -1
package/src/openapi/model.ts +2 -1
package/src/openapi/parse.ts +9 -1
package/src/openapi/references.ts +11 -1
package/src/openapi/render-mdx.ts +30 -3
package/src/openapi/source.ts +3 -1
package/src/search/documents.ts +4 -1
package/src/theme/entry.ts +3 -0
package/src/theme/icons.ts +7 -11

package/src/components/layout/PageLayout.astro CHANGED Viewed

@@ -32,6 +32,7 @@ import Favicon from "./Favicon.astro";
 import Fonts from "./Fonts.astro";
 import { bannerInitScript, themeInitScript } from "./head-scripts.ts";
 import Header from "./Header.astro";
+import { isUnderPath } from "./nav-utils.ts";
 interface Props {
   site: { title: string; description?: string };
@@ -209,7 +210,7 @@ const bannerScript = banner?.dismissible
                     <a
                       aria-current={
                         route === tab.path ||
-                        (tab.path !== "/" && route.startsWith(tab.path))
+                        (tab.path !== "/" && isUnderPath(route, tab.path))
                           ? "page"
                           : undefined
                       }

package/src/components/layout/ReferenceLayout.astro CHANGED Viewed

@@ -92,6 +92,7 @@ const bannerScript = banner?.dismissible
   <body class="bg-background font-sans text-foreground antialiased">
     <Banner banner={banner} />
     <Header
+      hasDrawer={false}
       hasSidebar={false}
       logo={logo}
       navigation={navigation}

package/src/components/layout/RootLayout.astro CHANGED Viewed

@@ -23,6 +23,7 @@ import {
   findBreadcrumbs,
   flattenPages,
   getPagination,
+  isUnderPath,
   sidebarForRoute,
 } from "./nav-utils.ts";
 import NavTree from "./NavTree.astro";
@@ -427,7 +428,7 @@ const bannerScript = banner?.dismissible
                     <a
                       aria-current={
                         page.route === tab.path ||
-                        (tab.path !== "/" && page.route.startsWith(tab.path))
+                        (tab.path !== "/" && isUnderPath(page.route, tab.path))
                           ? "page"
                           : undefined
                       }
@@ -601,7 +602,20 @@ const bannerScript = banner?.dismissible
         button.setAttribute("aria-label", "Copy code");
         button.innerHTML = svg("copy");
         button.addEventListener("click", async () => {
-          const text = pre.querySelector("code")?.textContent ?? "";
+          const code = pre.querySelector("code");
+          let text = code?.textContent ?? "";
+          // Twoslash nests each hover popup's type signature and docs inside
+          // the <code>; copying textContent verbatim would interleave them
+          // with the source. Strip the popups from a clone first.
+          if (code?.querySelector(".twoslash-popup-container")) {
+            const clone = code.cloneNode(true) as HTMLElement;
+            for (const popup of clone.querySelectorAll(
+              ".twoslash-popup-container"
+            )) {
+              popup.remove();
+            }
+            text = clone.textContent ?? "";
+          }
           try {
             await navigator.clipboard.writeText(text);
           } catch {

package/src/components/layout/Search.astro CHANGED Viewed

@@ -133,7 +133,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
   <script
     data-blume-search-popular
     is:inline
-    set:html={JSON.stringify(popular)}
+    set:html={JSON.stringify(popular).replaceAll("<", "\\u003c")}
     type="application/json"
   />
@@ -190,6 +190,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       selectables: Selectable[] = [];
       selectedIndex = -1;
       activeSection: string | null = null;
+      renderGeneration = 0;
       previewOn = true;
       devOnlyMsg = "Search is available in the production build.";
       noResultsMsg = "No results found.";
@@ -339,6 +340,8 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       async render() {
         const query = this.input.value.trim();
+        this.renderGeneration += 1;
+        const generation = this.renderGeneration;
         this.selectables = [];
         this.selectedIndex = -1;
         this.results.replaceChildren();
@@ -364,8 +367,10 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
           locale: localeFilter,
           section: this.activeSection ?? undefined,
         });
-        // A later keystroke may have superseded this query mid-await.
-        if (this.input.value.trim() !== query) {
+        // Any newer render — a keystroke, a section pill, a locale toggle —
+        // supersedes this one mid-await, even for the same query text;
+        // appending the stale hits would duplicate rows and desync selection.
+        if (generation !== this.renderGeneration) {
           return;
         }

package/src/components/layout/nav-utils.ts CHANGED Viewed

@@ -71,9 +71,13 @@ export const findBreadcrumbs = (nodes: NavNode[], route: string): Crumb[] => {
   return search(nodes, []) ?? [];
 };
-/** Whether `route` is the section root `base` or nested beneath it. */
-const isUnderPath = (route: string, base: string): boolean =>
-  route === base || route.startsWith(`${base}/`);
+/**
+ * Whether `route` is the section root `base` or nested beneath it. Requires a
+ * path boundary, so `/api-reference` is not under `/api`. The root `/` spans
+ * every route.
+ */
+export const isUnderPath = (route: string, base: string): boolean =>
+  base === "/" || route === base || route.startsWith(`${base}/`);
 /**
  * The tab whose `path` is the longest prefix of `route`, mirroring the header's

package/src/core/config-input.ts CHANGED Viewed

@@ -714,18 +714,13 @@ export interface GithubConfig {
 export interface CodeConfig {
   /** Show a brand language icon in the code-block header. Defaults to `true`. */
   icons?: boolean;
-  /**
-   * Syntax-highlight inline `` `code{:lang}` `` snippets. Defaults to `false`;
-   * opt a snippet in with a trailing `{:lang}` marker.
-   */
-  inline?: boolean;
   /** Wrap long lines instead of scrolling horizontally. Defaults to `false`. */
   wrap?: boolean;
 }
 /** Markdown / MDX rendering behavior. */
 export interface MarkdownConfig {
-  /** Code-block rendering: language icons, inline highlighting, line wrap. */
+  /** Code-block rendering: language icons, line wrap. */
   code?: CodeConfig;
   /** Syntax-highlighting themes for fenced code blocks. */
   codeBlocks?: {
@@ -744,11 +739,6 @@ export interface MarkdownConfig {
   headingAnchors?: boolean;
   /** Make content images click-to-zoom (lightbox). Defaults to `true`. */
   imageZoom?: boolean;
-  /**
-   * Enable LaTeX math (`$…$` inline, `$$…$$` block) via KaTeX. Defaults to
-   * `false` since `$` is common in prose and shell. MDX only.
-   */
-  math?: boolean;
 }
 // ---------------------------------------------------------------------------

package/src/core/i18n.ts CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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();

package/src/core/sources/assets.ts CHANGED Viewed

@@ -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 };
 };

package/src/core/sources/cache.ts CHANGED Viewed

@@ -27,14 +27,32 @@ export const entriesDigest = (entries: SourceEntry[]): string =>
  * Build an opt-in polling watcher for a remote source: re-`load()` on an
  * interval and fire `onChange` only when the entry digest changes, so a remote
  * source can hot-reload in dev without refetching the world on every keystroke.
+ *
+ * `load` must fetch fresh (bypassing the cache-first dev path) — polling the
+ * cache-first loader would serve the identical snapshot on every tick and
+ * never observe a remote change. `seed` (the source's regular, cache-first
+ * loader) establishes the baseline digest from what dev actually served, so a
+ * remote change landing before the first tick still fires.
  */
 export const pollingWatch =
   (
     load: () => Promise<SourceLoadResult>,
-    intervalSeconds: number
+    intervalSeconds: number,
+    seed?: () => Promise<SourceLoadResult>
   ): ((onChange: () => void) => () => void) =>
   (onChange) => {
     let last = "";
+    if (seed) {
+      const seedBaseline = async (): Promise<void> => {
+        try {
+          const { entries } = await seed();
+          last ||= entriesDigest(entries);
+        } catch {
+          // Fall back to first-tick seeding.
+        }
+      };
+      void seedBaseline();
+    }
     const tick = async (): Promise<void> => {
       try {
         const { entries } = await load();