blume 2.1.0 → 2.1.2

package/dist/cli/{chunk-43zcf4gz.js → chunk-0pmb4tr4.js}

@@ -6,6 +6,7 @@ import {
   i18nDiagnostics,
   blumeReferences,
   frontmatter_default,
+  resolveLocalizable,
   resolveDocsCollection,
   CHANGELOG_INDEX_ROUTE,
   hasChangelogIndex,
@@ -22,6 +23,7 @@ import {
   pagesByRef,
   buildNavigation,
   PUBLIC_API_URL,
+  isPatternPath,
   pathsUnderPattern,
   hasVariables,
   substituteVariables,
@@ -33,6 +35,7 @@ import {
   slugify,
   slugifyPath,
   unloadablePathDiagnostic,
+  frontmatterYamlDiagnostic,
   extractHeadings,
   strippedLineOffset,
   isStringValue,
@@ -47,6 +50,7 @@ import {
   escapeMarkdownText,
   guardBlockStart,
   renderInline,
+  renderInlineMdx,
   destination,
   linkParts,
   headingPrefix,
@@ -73,7 +77,7 @@ import {
   createModuleLoader,
   resolveProjectContext,
   loadConfig
-} from "./chunk-xkz5xbtv.js";
+} from "./chunk-124fvmzq.js";
 import {
   getBlumeVersion,
   BlumeError,
@@ -81,6 +85,7 @@ import {
 } from "./index.js";
 import {
   trimChar,
+  normalizePath,
   isInternalPath,
   withBasePath,
   mountBasePath
@@ -93,6 +98,232 @@ import {
   ignoringWatchListener
 } from "./chunk-kwrg63tm.js";
 
+// src/theme/icon-kind.ts
+var IMAGE_ICON = /^(?:https?:\/\/|data:image\/|\/|\.{1,2}\/)|\.(?:avif|gif|jpe?g|png|svg|webp)$/iu;
+var INLINE_SVG = /^\s*<svg[\s\S]*<\/svg>\s*$/u;
+var isImageIcon = (value) => IMAGE_ICON.test(value);
+var isInlineSvg = (value) => INLINE_SVG.test(value);
+var isAssetIcon = (value) => isInlineSvg(value) || isImageIcon(value);
+
+// src/theme/icons.ts
+import { createRequire } from "node:module";
+import { getIconData, iconToSVG } from "@iconify/utils";
+var requireJson = createRequire(import.meta.url);
+var loadSet = (pkg) => requireJson(pkg);
+var SETS = {
+  lucide: loadSet("@iconify-json/lucide/icons.json")
+};
+var DEFAULT_SET = "lucide";
+var PREFIX_SETS = {
+  lucide: "lucide"
+};
+var ownEntry = (map, key) => Object.hasOwn(map, key) ? map[key] : undefined;
+var normalize = (name) => name.trim().toLowerCase().replaceAll(/[\s_]+/gu, "-");
+var fromSet = (setName, iconName) => {
+  const set = ownEntry(SETS, setName);
+  const data = set && getIconData(set, iconName);
+  if (!data) {
+    return null;
+  }
+  const { attributes, body } = iconToSVG(data, { height: "auto" });
+  return { body, name: iconName, viewBox: attributes.viewBox };
+};
+var resolveIcon = (name) => {
+  const normalized = normalize(name);
+  const colon = normalized.indexOf(":");
+  if (colon > 0) {
+    const setName = ownEntry(PREFIX_SETS, normalized.slice(0, colon));
+    return setName ? fromSet(setName, normalized.slice(colon + 1)) : null;
+  }
+  return fromSet(DEFAULT_SET, normalized);
+};
+var hasIcon = (name) => resolveIcon(name) !== null;
+
+// src/core/nav-diagnostics.ts
+var ICON_FORMAT_HINT = "Use a built-in icon name, an image path/URL, or inline SVG markup.";
+var flattenNodes = (nodes) => nodes.flatMap((node) => node.kind === "group" ? [node, ...flattenNodes(node.children)] : [node]);
+var collectIcons = (navigation) => {
+  const icons = [];
+  const push = (icon, where) => {
+    if (icon) {
+      icons.push({ icon, where });
+    }
+  };
+  for (const tab of navigation.tabs) {
+    push(tab.icon, `tab "${tab.label}"`);
+    for (const item of tab.items ?? []) {
+      push(item.icon, `tab item "${item.label}"`);
+    }
+  }
+  for (const selector of navigation.selectors) {
+    for (const item of selector.items) {
+      push(item.icon, `selector "${item.label}"`);
+    }
+  }
+  for (const link of navigation.featured) {
+    push(link.icon, `featured link "${link.label}"`);
+  }
+  const sidebars = [navigation.sidebar];
+  for (const sidebar of sidebars) {
+    for (const node of flattenNodes(sidebar)) {
+      push(node.icon, `"${node.label}"`);
+    }
+  }
+  return icons;
+};
+var unknownIconDiagnostics = (icons, suggestion) => {
+  const seen = new Set;
+  const diagnostics = [];
+  for (const { icon, where } of icons) {
+    if (isAssetIcon(icon) || hasIcon(icon) || seen.has(icon)) {
+      continue;
+    }
+    seen.add(icon);
+    const message = icon.trimStart().startsWith("<") ? `Icon markup "${icon}" (${where}) isn't a complete inline <svg> element, so it won't render.` : `Unknown icon "${icon}" (${where}) — it isn't in Blume's icon set.`;
+    diagnostics.push({
+      code: "BLUME_UNKNOWN_ICON",
+      message,
+      severity: "warning",
+      suggestion
+    });
+  }
+  return diagnostics;
+};
+var validateNavIcons = (navigation) => unknownIconDiagnostics(collectIcons(navigation), ICON_FORMAT_HINT);
+var validateSearchPopularIcons = (popular) => {
+  const icons = popular.flatMap((link) => link.icon ? [{ icon: link.icon, where: `popular link "${link.label}"` }] : []);
+  return unknownIconDiagnostics(icons, ICON_FORMAT_HINT);
+};
+var resolvesToPages = (routes, path) => routes.has(path) || [...routes].some((route) => route.startsWith(`${path}/`));
+var validateNavTargets = (navigation, routes) => {
+  const targets = [
+    ...navigation.tabs.map((tab) => ({ label: tab.label, path: tab.path })),
+    ...navigation.selectors.flatMap((selector) => selector.items.map((item) => ({ label: item.label, path: item.path }))),
+    ...navigation.featured.map((link) => ({
+      label: link.label,
+      path: link.href
+    })),
+    ...(navigation.actions ?? []).map((action) => ({
+      label: action.label,
+      path: action.href
+    })),
+    ...navigation.cta ? [{ label: navigation.cta.label, path: navigation.cta.href }] : []
+  ];
+  const diagnostics = [];
+  const seen = new Set;
+  for (const { label, path } of targets) {
+    if (!isInternalPath(path) || path.startsWith("/#") || seen.has(path)) {
+      continue;
+    }
+    if (!resolvesToPages(routes, path.split(/[?#]/u)[0] ?? path)) {
+      seen.add(path);
+      diagnostics.push({
+        code: "BLUME_NAV_MISSING_PAGE",
+        message: `Navigation entry "${label}" points to ${path}, but no page matches it.`,
+        severity: "warning",
+        suggestion: "Fix the path, or add a page at that route."
+      });
+    }
+  }
+  return diagnostics;
+};
+var validateSidebarItems = (items, resolves) => {
+  const diagnostics = [];
+  const walk = (list) => {
+    for (const item of list) {
+      if (isPageRef(item)) {
+        if (!resolves(normalizeRef(item))) {
+          diagnostics.push({
+            code: "BLUME_NAV_MISSING_PAGE",
+            message: `Sidebar entry "${item}" matches no page, so it's left out of the sidebar.`,
+            severity: "warning",
+            suggestion: "Fix the route, or add a page at it."
+          });
+        }
+        continue;
+      }
+      if (item.root && !resolves(normalizeRef(item.root))) {
+        diagnostics.push({
+          code: "BLUME_NAV_MISSING_PAGE",
+          message: `Sidebar entry "${item.label}" has root "${item.root}", but no page matches it, so its link leads nowhere.`,
+          severity: "warning",
+          suggestion: "Fix the root, or add a page at that route."
+        });
+      }
+      if (item.items) {
+        walk(item.items);
+      } else if (!(item.root || item.href)) {
+        diagnostics.push({
+          code: "BLUME_NAV_EMPTY_ITEM",
+          message: `Sidebar entry "${item.label}" has no page, href, root, or items, so it's left out of the sidebar.`,
+          severity: "warning",
+          suggestion: "Give it an href or a root to link somewhere, or items to make it a group."
+        });
+      }
+    }
+  };
+  walk(items);
+  return diagnostics;
+};
+var duplicateLabelDiagnostics = (navigation) => {
+  const diagnostics = [];
+  const checkLevel = (nodes, where) => {
+    const counts = new Map;
+    for (const node of nodes) {
+      counts.set(node.label, (counts.get(node.label) ?? 0) + 1);
+    }
+    for (const [label, count] of counts) {
+      if (count > 1) {
+        diagnostics.push({
+          code: "BLUME_NAV_DUPLICATE_LABEL",
+          message: `Duplicate sidebar label "${label}" appears ${count} times ${where}.`,
+          severity: "warning",
+          suggestion: "Give the entries distinct titles."
+        });
+      }
+    }
+    for (const node of nodes) {
+      if (node.kind === "group") {
+        checkLevel(node.children, `under "${node.label}"`);
+      }
+    }
+  };
+  const sidebars = [
+    { nodes: navigation.sidebar, where: "at the top level" }
+  ];
+  for (const { nodes, where } of sidebars) {
+    checkLevel(nodes, where);
+  }
+  return diagnostics;
+};
+var hiddenInSidebarDiagnostics = (navigation, pages) => {
+  const hidden = new Set(pages.flatMap((page) => page.meta.sidebar.hidden ? [page.id] : []));
+  if (hidden.size === 0) {
+    return [];
+  }
+  const sidebars = [navigation.sidebar];
+  const diagnostics = [];
+  const seen = new Set;
+  for (const sidebar of sidebars) {
+    for (const node of flattenNodes(sidebar)) {
+      if (node.kind === "page" && hidden.has(node.pageId) && !seen.has(node.pageId)) {
+        seen.add(node.pageId);
+        diagnostics.push({
+          code: "BLUME_NAV_HIDDEN_IN_SIDEBAR",
+          message: `Page "${node.label}" is marked hidden but appears in the sidebar (and its pagination).`,
+          severity: "warning",
+          suggestion: "Remove it from the navigation config, or unset sidebar.hidden."
+        });
+      }
+    }
+  }
+  return diagnostics;
+};
+var validateNavStructure = (navigation, pages) => [
+  ...duplicateLabelDiagnostics(navigation),
+  ...hiddenInSidebarDiagnostics(navigation, pages)
+];
+
 // src/core/manifest.ts
 var versionAlternateKey = (versionKey, locale) => `${versionKey}\x00${locale}`;
 var versionAlternatesFor = (byKey, versionKey, locale) => {
@@ -251,304 +482,69 @@ var LITERAL_MARKERS = new Map([
 var labelSource = (label) => label.length > 0 ? `[${mdastToString(label, { includeImageAlt: false })}]` : "";
 var attributeSource = (node) => {
   const attributes = Object.entries(node.attributes ?? {}).map(([key, value]) => value ? `${key}="${value}"` : key);
-  return attributes.length > 0 ? `{${attributes.join(" ")}}` : "";
-};
-var spannedSource = (node, source) => {
-  const start = node.position?.start?.offset;
-  const end = node.position?.end?.offset;
-  return start !== undefined && end !== undefined ? source.slice(start, end) : null;
-};
-var directiveSource = (node, marker, source) => {
-  const opening = `${marker}${node.name}`;
-  const slice = spannedSource(node, source);
-  if (slice?.startsWith(opening)) {
-    return slice;
-  }
-  return `${opening}${labelSource(node.children ?? [])}${attributeSource(node)}`;
-};
-
-// src/core/directive-diagnostics.ts
-var CONTAINER_OPENING = /^[\t >]*:{3,}(?<name>[a-z][\w-]*)/gimu;
-var codeList = (names) => [...names].map((name) => `\`${name}\``).join(", ");
-var CALLOUT_NAMES = `${codeList(CALLOUT_TYPES)} (or the aliases ${codeList(Object.keys(CALLOUT_ALIASES))})`;
-var unknownContainers = (text) => {
-  const named = [...text.matchAll(CONTAINER_OPENING)].some((match) => calloutTypeFor(match.groups?.name ?? "") === null);
-  if (!named) {
-    return [];
-  }
-  let tree;
-  try {
-    tree = mdxToMdast(text, { features: MDX_BODY_FEATURES });
-  } catch {
-    return [];
-  }
-  const found = [];
-  const walk = (node) => {
-    if (node.type === "containerDirective" && calloutTypeFor(node.name) === null) {
-      found.push({ line: node.position?.start.line ?? 1, name: node.name });
-    }
-    if ("children" in node) {
-      for (const child of node.children) {
-        walk(child);
-      }
-    }
-  };
-  walk(tree);
-  return found;
-};
-var unknownDirectiveDiagnostics = (entry, sourceName) => {
-  if (entry.body.format !== "mdx") {
-    return [];
-  }
-  const page = entry.sourcePath ?? `${sourceName}:${entry.ref}`;
-  const offset = entry.bodyLineOffset ?? strippedLineOffset(entry.raw, entry.body.text);
-  return unknownContainers(entry.expanded?.text ?? entry.body.text).map(({ line, name }) => {
-    const origin = entry.expanded?.origins[line - 1];
-    return {
-      code: "BLUME_UNKNOWN_DIRECTIVE",
-      file: origin?.file ?? page,
-      line: origin?.line ?? line + offset,
-      message: `\`:::${name}\` isn't a callout type, so the page shows its \`:::\` lines as written around its content.`,
-      severity: "warning",
-      suggestion: `Use a callout type — ${CALLOUT_NAMES} — or remove the \`:::\` lines to keep the content as plain prose.`
-    };
-  });
-};
-
-// src/core/localizable.ts
-var isSingleLabel = (label) => typeof label === "string";
-var resolveLocalizable = (label, locale, defaultLocale) => {
-  if (isSingleLabel(label)) {
-    return label;
-  }
-  return (locale === undefined ? undefined : label[locale]) ?? (defaultLocale === undefined ? undefined : label[defaultLocale]) ?? Object.values(label)[0] ?? "";
-};
-
-// src/theme/icon-kind.ts
-var IMAGE_ICON = /^(?:https?:\/\/|data:image\/|\/|\.{1,2}\/)|\.(?:avif|gif|jpe?g|png|svg|webp)$/iu;
-var INLINE_SVG = /^\s*<svg[\s\S]*<\/svg>\s*$/u;
-var isImageIcon = (value) => IMAGE_ICON.test(value);
-var isInlineSvg = (value) => INLINE_SVG.test(value);
-var isAssetIcon = (value) => isInlineSvg(value) || isImageIcon(value);
-
-// src/theme/icons.ts
-import { createRequire } from "node:module";
-import { getIconData, iconToSVG } from "@iconify/utils";
-var requireJson = createRequire(import.meta.url);
-var loadSet = (pkg) => requireJson(pkg);
-var SETS = {
-  lucide: loadSet("@iconify-json/lucide/icons.json")
-};
-var DEFAULT_SET = "lucide";
-var PREFIX_SETS = {
-  lucide: "lucide"
-};
-var ownEntry = (map, key) => Object.hasOwn(map, key) ? map[key] : undefined;
-var normalize = (name) => name.trim().toLowerCase().replaceAll(/[\s_]+/gu, "-");
-var fromSet = (setName, iconName) => {
-  const set = ownEntry(SETS, setName);
-  const data = set && getIconData(set, iconName);
-  if (!data) {
-    return null;
-  }
-  const { attributes, body } = iconToSVG(data, { height: "auto" });
-  return { body, name: iconName, viewBox: attributes.viewBox };
-};
-var resolveIcon = (name) => {
-  const normalized = normalize(name);
-  const colon = normalized.indexOf(":");
-  if (colon > 0) {
-    const setName = ownEntry(PREFIX_SETS, normalized.slice(0, colon));
-    return setName ? fromSet(setName, normalized.slice(colon + 1)) : null;
-  }
-  return fromSet(DEFAULT_SET, normalized);
-};
-var hasIcon = (name) => resolveIcon(name) !== null;
-
-// src/core/nav-diagnostics.ts
-var ICON_FORMAT_HINT = "Use a built-in icon name, an image path/URL, or inline SVG markup.";
-var flattenNodes = (nodes) => nodes.flatMap((node) => node.kind === "group" ? [node, ...flattenNodes(node.children)] : [node]);
-var collectIcons = (navigation) => {
-  const icons = [];
-  const push = (icon, where) => {
-    if (icon) {
-      icons.push({ icon, where });
-    }
-  };
-  for (const tab of navigation.tabs) {
-    push(tab.icon, `tab "${tab.label}"`);
-    for (const item of tab.items ?? []) {
-      push(item.icon, `tab item "${item.label}"`);
-    }
-  }
-  for (const selector of navigation.selectors) {
-    for (const item of selector.items) {
-      push(item.icon, `selector "${item.label}"`);
-    }
-  }
-  for (const link of navigation.featured) {
-    push(link.icon, `featured link "${link.label}"`);
-  }
-  const sidebars = [navigation.sidebar];
-  for (const sidebar of sidebars) {
-    for (const node of flattenNodes(sidebar)) {
-      push(node.icon, `"${node.label}"`);
-    }
-  }
-  return icons;
-};
-var unknownIconDiagnostics = (icons, suggestion) => {
-  const seen = new Set;
-  const diagnostics = [];
-  for (const { icon, where } of icons) {
-    if (isAssetIcon(icon) || hasIcon(icon) || seen.has(icon)) {
-      continue;
-    }
-    seen.add(icon);
-    const message = icon.trimStart().startsWith("<") ? `Icon markup "${icon}" (${where}) isn't a complete inline <svg> element, so it won't render.` : `Unknown icon "${icon}" (${where}) — it isn't in Blume's icon set.`;
-    diagnostics.push({
-      code: "BLUME_UNKNOWN_ICON",
-      message,
-      severity: "warning",
-      suggestion
-    });
-  }
-  return diagnostics;
+  return attributes.length > 0 ? `{${attributes.join(" ")}}` : "";
 };
-var validateNavIcons = (navigation) => unknownIconDiagnostics(collectIcons(navigation), ICON_FORMAT_HINT);
-var validateSearchPopularIcons = (popular) => {
-  const icons = popular.flatMap((link) => link.icon ? [{ icon: link.icon, where: `popular link "${link.label}"` }] : []);
-  return unknownIconDiagnostics(icons, ICON_FORMAT_HINT);
+var spannedSource = (node, source) => {
+  const start = node.position?.start?.offset;
+  const end = node.position?.end?.offset;
+  return start !== undefined && end !== undefined ? source.slice(start, end) : null;
 };
-var resolvesToPages = (routes, path) => routes.has(path) || [...routes].some((route) => route.startsWith(`${path}/`));
-var validateNavTargets = (navigation, routes) => {
-  const targets = [
-    ...navigation.tabs.map((tab) => ({ label: tab.label, path: tab.path })),
-    ...navigation.selectors.flatMap((selector) => selector.items.map((item) => ({ label: item.label, path: item.path }))),
-    ...navigation.featured.map((link) => ({
-      label: link.label,
-      path: link.href
-    })),
-    ...(navigation.actions ?? []).map((action) => ({
-      label: action.label,
-      path: action.href
-    })),
-    ...navigation.cta ? [{ label: navigation.cta.label, path: navigation.cta.href }] : []
-  ];
-  const diagnostics = [];
-  const seen = new Set;
-  for (const { label, path } of targets) {
-    if (!isInternalPath(path) || path.startsWith("/#") || seen.has(path)) {
-      continue;
-    }
-    if (!resolvesToPages(routes, path.split(/[?#]/u)[0] ?? path)) {
-      seen.add(path);
-      diagnostics.push({
-        code: "BLUME_NAV_MISSING_PAGE",
-        message: `Navigation entry "${label}" points to ${path}, but no page matches it.`,
-        severity: "warning",
-        suggestion: "Fix the path, or add a page at that route."
-      });
-    }
+var directiveSource = (node, marker, source) => {
+  const opening = `${marker}${node.name}`;
+  const slice = spannedSource(node, source);
+  if (slice?.startsWith(opening)) {
+    return slice;
   }
-  return diagnostics;
-};
-var validateSidebarItems = (items, resolves) => {
-  const diagnostics = [];
-  const walk = (list) => {
-    for (const item of list) {
-      if (isPageRef(item)) {
-        if (!resolves(normalizeRef(item))) {
-          diagnostics.push({
-            code: "BLUME_NAV_MISSING_PAGE",
-            message: `Sidebar entry "${item}" matches no page, so it's left out of the sidebar.`,
-            severity: "warning",
-            suggestion: "Fix the route, or add a page at it."
-          });
-        }
-        continue;
-      }
-      if (item.root && !resolves(normalizeRef(item.root))) {
-        diagnostics.push({
-          code: "BLUME_NAV_MISSING_PAGE",
-          message: `Sidebar entry "${item.label}" has root "${item.root}", but no page matches it, so its link leads nowhere.`,
-          severity: "warning",
-          suggestion: "Fix the root, or add a page at that route."
-        });
-      }
-      if (item.items) {
-        walk(item.items);
-      } else if (!(item.root || item.href)) {
-        diagnostics.push({
-          code: "BLUME_NAV_EMPTY_ITEM",
-          message: `Sidebar entry "${item.label}" has no page, href, root, or items, so it's left out of the sidebar.`,
-          severity: "warning",
-          suggestion: "Give it an href or a root to link somewhere, or items to make it a group."
-        });
-      }
-    }
-  };
-  walk(items);
-  return diagnostics;
+  return `${opening}${labelSource(node.children ?? [])}${attributeSource(node)}`;
 };
-var duplicateLabelDiagnostics = (navigation) => {
-  const diagnostics = [];
-  const checkLevel = (nodes, where) => {
-    const counts = new Map;
-    for (const node of nodes) {
-      counts.set(node.label, (counts.get(node.label) ?? 0) + 1);
-    }
-    for (const [label, count] of counts) {
-      if (count > 1) {
-        diagnostics.push({
-          code: "BLUME_NAV_DUPLICATE_LABEL",
-          message: `Duplicate sidebar label "${label}" appears ${count} times ${where}.`,
-          severity: "warning",
-          suggestion: "Give the entries distinct titles."
-        });
-      }
+
+// src/core/directive-diagnostics.ts
+var CONTAINER_OPENING = /^[\t >]*:{3,}(?<name>[a-z][\w-]*)/gimu;
+var codeList = (names) => [...names].map((name) => `\`${name}\``).join(", ");
+var CALLOUT_NAMES = `${codeList(CALLOUT_TYPES)} (or the aliases ${codeList(Object.keys(CALLOUT_ALIASES))})`;
+var unknownContainers = (text) => {
+  const named = [...text.matchAll(CONTAINER_OPENING)].some((match) => calloutTypeFor(match.groups?.name ?? "") === null);
+  if (!named) {
+    return [];
+  }
+  let tree;
+  try {
+    tree = mdxToMdast(text, { features: MDX_BODY_FEATURES });
+  } catch {
+    return [];
+  }
+  const found = [];
+  const walk = (node) => {
+    if (node.type === "containerDirective" && calloutTypeFor(node.name) === null) {
+      found.push({ line: node.position?.start.line ?? 1, name: node.name });
     }
-    for (const node of nodes) {
-      if (node.kind === "group") {
-        checkLevel(node.children, `under "${node.label}"`);
+    if ("children" in node) {
+      for (const child of node.children) {
+        walk(child);
       }
     }
   };
-  const sidebars = [
-    { nodes: navigation.sidebar, where: "at the top level" }
-  ];
-  for (const { nodes, where } of sidebars) {
-    checkLevel(nodes, where);
-  }
-  return diagnostics;
+  walk(tree);
+  return found;
 };
-var hiddenInSidebarDiagnostics = (navigation, pages) => {
-  const hidden = new Set(pages.flatMap((page) => page.meta.sidebar.hidden ? [page.id] : []));
-  if (hidden.size === 0) {
+var unknownDirectiveDiagnostics = (entry, sourceName) => {
+  if (entry.body.format !== "mdx") {
     return [];
   }
-  const sidebars = [navigation.sidebar];
-  const diagnostics = [];
-  const seen = new Set;
-  for (const sidebar of sidebars) {
-    for (const node of flattenNodes(sidebar)) {
-      if (node.kind === "page" && hidden.has(node.pageId) && !seen.has(node.pageId)) {
-        seen.add(node.pageId);
-        diagnostics.push({
-          code: "BLUME_NAV_HIDDEN_IN_SIDEBAR",
-          message: `Page "${node.label}" is marked hidden but appears in the sidebar (and its pagination).`,
-          severity: "warning",
-          suggestion: "Remove it from the navigation config, or unset sidebar.hidden."
-        });
-      }
-    }
-  }
-  return diagnostics;
+  const page = entry.sourcePath ?? `${sourceName}:${entry.ref}`;
+  const offset = entry.bodyLineOffset ?? strippedLineOffset(entry.raw, entry.body.text);
+  return unknownContainers(entry.expanded?.text ?? entry.body.text).map(({ line, name }) => {
+    const origin = entry.expanded?.origins[line - 1];
+    return {
+      code: "BLUME_UNKNOWN_DIRECTIVE",
+      file: origin?.file ?? page,
+      line: origin?.line ?? line + offset,
+      message: `\`:::${name}\` isn't a callout type, so the page shows its \`:::\` lines as written around its content.`,
+      severity: "warning",
+      suggestion: `Use a callout type — ${CALLOUT_NAMES} — or remove the \`:::\` lines to keep the content as plain prose.`
+    };
+  });
 };
-var validateNavStructure = (navigation, pages) => [
-  ...duplicateLabelDiagnostics(navigation),
-  ...hiddenInSidebarDiagnostics(navigation, pages)
-];
 
 // src/core/graph.ts
 var collectRoutes = (pages) => {
@@ -1016,7 +1012,9 @@ var assetFromEntry = (asset) => {
     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)
   };
@@ -1084,6 +1082,11 @@ var inlineNodeParts = (node, options) => {
     case "asset-hyperlink": {
       return linkParts(inlineParts(children(node), options), 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) }];
     }
@@ -1135,7 +1138,14 @@ var renderBlock = (node, options) => {
     }
     case "embedded-asset-block": {
       const asset = linkedAsset(node, options);
-      return asset ? image(asset.description ?? asset.title ?? "", asset.url) : "";
+      if (!asset) {
+        return "";
+      }
+      if (asset.contentType && !asset.contentType.startsWith("image/")) {
+        const label = asset.title ?? asset.fileName ?? asset.url;
+        return renderInline(linkParts([{ marks: {}, text: label }], asset.url));
+      }
+      return image(asset.description ?? asset.title ?? "", asset.url);
     }
     case "embedded-entry-block": {
       return embeddedEntry(node, options);
@@ -1157,9 +1167,17 @@ var remoteSource = (options, ctx) => {
   let snapshot = new Map;
   const load = async (refresh = ctx?.refresh ?? true) => {
     options.assertConfigured?.();
-    const result = await loadWithCache(options.name, cache, options.fetchEntries, refresh);
+    let warnings = [];
+    const result = await loadWithCache(options.name, cache, async () => {
+      const found = [];
+      const entries = await options.fetchEntries((diagnostic) => {
+        found.push(diagnostic);
+      });
+      warnings = found;
+      return entries;
+    }, refresh);
     snapshot = new Map(result.entries.map((entry) => [entry.ref, entry]));
-    return result;
+    return { ...result, diagnostics: [...result.diagnostics, ...warnings] };
   };
   const read = async (ref) => {
     const cached = snapshot.get(ref);
@@ -1190,6 +1208,12 @@ var stagedEntry = (slug, data, markdown, lastModified, format = "md") => {
     ref: `${slug}.${format}`
   };
 };
+var missingSecretError = (name, env) => new BlumeError({
+  code: "BLUME_MISSING_SECRET",
+  message: `Source "${name}" needs ${env}, which is not set.`,
+  severity: "error",
+  suggestion: `Set ${env} in .env.local for local dev, or in your host's environment for production.`
+});
 var REMOTE_TIMEOUT_MS = 30000;
 var fetchJson = async (url, client) => {
   const doFetch = client.fetchImpl ?? globalThis.fetch;
@@ -1211,9 +1235,9 @@ var queryString = (params) => {
   }
   return search.toString();
 };
+var documentSlug = (doc, slugField, id) => slugifyPath(asString(getPath(doc, slugField)) ?? id) || slugify(id) || "untitled";
 var documentEntry = (doc, fields, id, lower, draft = false, lowersToMdx = false) => {
-  const slugValue = asString(getPath(doc, fields.slug)) ?? id;
-  const slug = slugifyPath(slugValue) || slugify(id) || "untitled";
+  const slug = documentSlug(doc, fields.slug, id);
   const data = {};
   const title = asString(getPath(doc, fields.title));
   const description = asString(getPath(doc, fields.description));
@@ -1226,6 +1250,10 @@ var documentEntry = (doc, fields, id, lower, draft = false, lowersToMdx = false)
   if (draft) {
     data.draft = true;
   }
+  const order = fields.order ? asNumber(getPath(doc, fields.order)) : undefined;
+  if (order !== undefined) {
+    data.sidebar = { order };
+  }
   const body = getPath(doc, fields.body);
   let markdown = "";
   let format = "md";
@@ -1240,8 +1268,8 @@ var documentEntry = (doc, fields, id, lower, draft = false, lowersToMdx = false)
 };
 
 // src/core/sources/contentful.ts
-var DELIVERY_HOST = "https://cdn.contentful.com";
-var PREVIEW_HOST = "https://preview.contentful.com";
+var DELIVERY_HOST = "cdn.contentful.com";
+var PREVIEW_HOST = "preview.contentful.com";
 var PAGE_SIZE = 100;
 var DEFAULT_FIELDS = {
   body: "body",
@@ -1251,20 +1279,50 @@ var DEFAULT_FIELDS = {
   title: "title"
 };
 var byId = (objects) => new Map(objects.map((object) => [asString(getPath(object, "sys.id")) ?? "", object]));
+var entryView = (item) => {
+  const sys = asObject(item.sys) ?? {};
+  return {
+    id: asString(sys.id) ?? "",
+    view: { ...asObject(item.fields), sys }
+  };
+};
 var contentfulSource = (options, ctx) => {
   const fields = { ...DEFAULT_FIELDS, ...options.fields };
-  const toEntry = (item, assets, linked) => {
-    const sys = asObject(item.sys) ?? {};
-    const id = asString(sys.id) ?? "";
-    const view = { ...asObject(item.fields), sys };
-    return documentEntry(view, fields, id, (body) => isJsonObject(body) ? contentfulRichTextToMarkdown(body, {
+  const routeOf = (view, id) => {
+    const route = resolveEntryRoute({ ref: `${documentSlug(view, fields.slug, id)}.md` }, ".md", undefined, { i18n: options.i18n, prefix: options.prefix, versions: options.versions });
+    return localizedRoute(route.logicalRoute, route.locales[0] ?? "", options.i18n);
+  };
+  const toEntry = (item, { assets, linked }, routes, warn) => {
+    const { id, view } = entryView(item);
+    const missing = new Set;
+    const entry = documentEntry(view, fields, id, (body) => isJsonObject(body) ? contentfulRichTextToMarkdown(body, {
+      entryHref: (target) => routes.get(asString(getPath(target, "sys.id")) ?? ""),
       resolveAsset: (assetId) => {
         const asset = assets.get(assetId);
-        return asset ? assetFromEntry(asset) : null;
+        if (!asset) {
+          missing.add(`asset "${assetId}"`);
+          return null;
+        }
+        return assetFromEntry(asset);
+      },
+      resolveEntry: (entryId) => {
+        const target = linked.get(entryId);
+        if (!target) {
+          missing.add(`entry "${entryId}"`);
+        }
+        return target ?? null;
       },
-      resolveEntry: (entryId) => linked.get(entryId) ?? null,
       serializers: options.serializers
     }) : "", false, writesMdx(options.serializers));
+    for (const link of missing) {
+      warn({
+        code: "BLUME_SOURCE_UNRESOLVED_LINK",
+        message: `Source "${options.name}": "${entry.ref}" links to Contentful ${link}, which the response didn't include, so the page renders without it.`,
+        severity: "warning",
+        suggestion: "Publish the linked asset or entry, or remove the link: the Delivery API returns only published content."
+      });
+    }
+    return entry;
   };
   const preview = ctx?.preview ?? false;
   const previewToken = () => options.previewToken ?? process.env.CONTENTFUL_PREVIEW_TOKEN;
@@ -1278,15 +1336,18 @@ var contentfulSource = (options, ctx) => {
       });
     }
   };
-  const fetchEntries = async () => {
+  const fetchEntries = async (warn) => {
     const token = preview ? previewToken() : options.token ?? process.env.CONTENTFUL_ACCESS_TOKEN;
+    if (!token) {
+      throw missingSecretError(options.name, "CONTENTFUL_ACCESS_TOKEN");
+    }
     const client = {
       fetchImpl: options.fetchImpl,
-      headers: token ? { authorization: `Bearer ${token}` } : {}
+      headers: { authorization: `Bearer ${token}` }
     };
-    const host = preview ? PREVIEW_HOST : DELIVERY_HOST;
-    const base = `${host}/spaces/${options.space}/environments/${options.environment ?? "master"}/entries`;
-    const entries = [];
+    const host = preview ? options.previewHost ?? PREVIEW_HOST : options.host ?? DELIVERY_HOST;
+    const base = `https://${host}/spaces/${options.space}/environments/${options.environment ?? "master"}/entries`;
+    const pages = [];
     let skip = 0;
     let more = true;
     while (more) {
@@ -1302,16 +1363,20 @@ var contentfulSource = (options, ctx) => {
       if (!page) {
         throw new Error("Contentful returned a non-object response");
       }
-      const assets = byId(objectsIn(getPath(page, "includes.Asset")));
-      const linked = byId(objectsIn(getPath(page, "includes.Entry")));
       const items = objectsIn(page.items);
-      for (const item of items) {
-        entries.push(toEntry(item, assets, linked));
-      }
+      pages.push({
+        assets: byId(objectsIn(getPath(page, "includes.Asset"))),
+        items,
+        linked: byId([...objectsIn(getPath(page, "includes.Entry")), ...items])
+      });
       skip += items.length;
       more = items.length > 0 && skip < (asNumber(page.total) ?? 0);
     }
-    return entries;
+    const routes = new Map(pages.flatMap(({ items }) => items.map((item) => {
+      const { id, view } = entryView(item);
+      return [id, routeOf(view, id)];
+    })));
+    return pages.flatMap((page) => page.items.map((item) => toEntry(item, page, routes, warn)));
   };
   return remoteSource({
     assertConfigured,
@@ -1326,6 +1391,7 @@ var contentfulSource = (options, ctx) => {
 // src/core/sources/filesystem.ts
 import { existsSync, watch as fsWatch } from "node:fs";
 import { readFile } from "node:fs/promises";
+import { YAMLException } from "js-yaml";
 import { extname, isAbsolute, join as join2, relative as relative3, resolve } from "pathe";
 import { glob as glob2 } from "tinyglobby";
 var filesystemSource = (options) => {
@@ -1348,11 +1414,19 @@ var filesystemSource = (options) => {
         loadable.push(file);
       }
     }
-    const entries = await Promise.all(loadable.map(async (file) => {
+    const read = await Promise.all(loadable.map(async (file) => {
       const source = await readFile(file, "utf-8");
       const ext = extname(file).toLowerCase();
       const format = ext === ".mdx" ? "mdx" : "md";
-      const parsed = frontmatter_default(source);
+      let parsed;
+      try {
+        parsed = frontmatter_default(source);
+      } catch (error) {
+        if (error instanceof YAMLException) {
+          return frontmatterYamlDiagnostic(error, file);
+        }
+        throw error;
+      }
       return {
         body: { format, text: parsed.content },
         data: parsed.data,
@@ -1361,6 +1435,14 @@ var filesystemSource = (options) => {
         sourcePath: file
       };
     }));
+    const entries = [];
+    for (const item of read) {
+      if ("body" in item) {
+        entries.push(item);
+      } else {
+        diagnostics.push(item);
+      }
+    }
     return { diagnostics, entries };
   };
   const validate = () => {
@@ -1526,11 +1608,17 @@ var githubHeaders = () => {
   }
   return headers;
 };
+var releaseCategory = (release) => {
+  if (release.draft) {
+    return "Draft";
+  }
+  return release.prerelease ? "Prerelease" : "Release";
+};
 var releaseToEntry = (release, site) => {
   const version = release.tag_name.replace(LEADING_V, "");
   const title = release.name?.trim() || release.tag_name;
   const date = release.published_at ?? release.created_at;
-  const category = release.prerelease ? "Prerelease" : "Release";
+  const category = releaseCategory(release);
   const body = liftHeadings(relativizeOwnLinks(neutralizeUnsafeLinks((release.body ?? "").replaceAll(`\r
 `, `
 `)).trim(), site));
@@ -1641,6 +1729,11 @@ var githubReleasesSource = (options, ctx) => {
 
 // src/core/sources/mdx-remote.ts
 import picomatch from "picomatch";
+var includeMatcher = (include) => {
+  const included = picomatch(include.filter((pattern) => !pattern.startsWith("!")));
+  const excluded = picomatch(include.filter((pattern) => pattern.startsWith("!")).map((pattern) => pattern.slice(1)));
+  return (ref) => included(ref) && !excluded(ref);
+};
 var GITHUB_HOSTS = new Set(["api.github.com", "raw.githubusercontent.com"]);
 var githubHeaders2 = (url) => {
   const token = process.env.GITHUB_TOKEN;
@@ -1679,7 +1772,7 @@ var enumerateGithub = async (github, include, doFetch) => {
   const text = await fetchText(treeUrl, doFetch);
   const body = JSON.parse(text);
   const prefix = base ? `${base}/` : "";
-  const included = picomatch(include);
+  const included = includeMatcher(include);
   const refs = (body.tree ?? []).flatMap((node) => {
     if (!(node.type === "blob" && node.path.startsWith(prefix))) {
       return [];
@@ -1696,7 +1789,13 @@ var enumerateGithub = async (github, include, doFetch) => {
       }
     ];
   });
-  return { refs, truncated: body.truncated === true };
+  const truncated = body.truncated === true;
+  const found = prefix === "" || truncated || (body.tree ?? []).some((node) => node.path.startsWith(prefix));
+  return {
+    missing: found ? undefined : `"${base}" in ${owner}/${repo} at ${ref}`,
+    refs,
+    truncated
+  };
 };
 var mdxRemoteSource = (options, ctx) => {
   const doFetch = options.fetchImpl ?? globalThis.fetch;
@@ -1717,7 +1816,7 @@ var mdxRemoteSource = (options, ctx) => {
       return await enumerateGithub(options.github, options.include, doFetch);
     }
     const base = (options.url ?? "").replace(/\/$/u, "");
-    const included = picomatch(options.include);
+    const included = includeMatcher(options.include);
     const refs = (options.files ?? []).flatMap((ref) => included(ref) ? [{ editUrl: `${base}/${ref}`, fetchUrl: `${base}/${ref}`, ref }] : []);
     return { refs, truncated: false };
   };
@@ -1738,12 +1837,21 @@ var mdxRemoteSource = (options, ctx) => {
     assertConfigured();
     const skipped = [];
     const result = await loadWithCache(options.name, cache, async () => {
-      const { refs, truncated } = await enumerate();
+      const { missing, refs, truncated } = await enumerate();
+      if (missing) {
+        skipped.push({
+          code: "BLUME_SOURCE_PATH_MISSING",
+          message: `Source "${options.name}" read no files: there is no folder ${missing}.`,
+          severity: "warning",
+          suggestion: "Check github.path and github.ref against the repository."
+        });
+      }
       if (truncated) {
         skipped.push({
           code: "BLUME_SOURCE_TRUNCATED",
-          message: `Source "${options.name}" hit GitHub's tree listing limit; some files were not enumerated. Narrow the source path or split the repo.`,
-          severity: "warning"
+          message: `Source "${options.name}" hit GitHub's tree listing limit for the whole repository; some files were not enumerated.`,
+          severity: "warning",
+          suggestion: "List the files to read with { url, files } instead, or split the repository."
         });
       }
       const reasons = [];
@@ -1965,7 +2073,7 @@ var materializeAssets = async (markdown, ctx) => {
 };
 
 // src/core/sources/notion.ts
-var richToMarkdown = (rich = []) => {
+var richToMarkdown = (rich = [], mdx = false) => {
   const linked = [];
   for (const { annotations = {}, href, plain_text: text } of rich) {
     const run = {
@@ -1984,8 +2092,10 @@ var richToMarkdown = (rich = []) => {
       linked.push({ href: href ?? undefined, runs: [run] });
     }
   }
-  return renderInline(linked.flatMap(({ href, runs }) => linkParts(runs, href)));
+  const parts = linked.flatMap(({ href, runs }) => linkParts(runs, href, mdx));
+  return mdx ? renderInlineMdx(parts) : renderInline(parts);
 };
+var blockText2 = (rich, mdx) => mdx ? richToMarkdown(rich, true) : guardBlockStart(richToMarkdown(rich));
 var isBlockPayload = (value) => typeof value === "object";
 var payloadOf = (block) => {
   const value = block[block.type];
@@ -2044,9 +2154,9 @@ var renderVideo = (data) => {
 ${media}
 </Frame>` : media;
 };
-var renderLeaf = (block) => {
+var renderLeaf = (block, mdx) => {
   const data = payloadOf(block) ?? {};
-  const text = guardBlockStart(richToMarkdown(blockField(block)));
+  const text = blockText2(blockField(block), mdx);
   switch (block.type) {
     case "paragraph": {
       return text;
@@ -2092,6 +2202,7 @@ var renderLeaf = (block) => {
 };
 var notionSource = (options, ctx) => {
   const props = options.properties ?? {};
+  const textAsMdx = options.mdx ?? false;
   const limit = pLimit(Math.max(1, options.concurrency ?? DEFAULT_CONCURRENCY));
   const downloads = pLimit(ASSET_DOWNLOAD_CONCURRENCY);
   const inFlight = new Map;
@@ -2115,7 +2226,11 @@ var notionSource = (options, ctx) => {
         severity: "error"
       });
     }
-    return new Client({ auth: options.token ?? process.env.NOTION_TOKEN });
+    const auth = options.token ?? process.env.NOTION_TOKEN;
+    if (!auth) {
+      throw missingSecretError(options.name, "NOTION_TOKEN");
+    }
+    return new Client({ auth });
   };
   const childrenOf = (client, blockId) => collectAll((cursor) => notionCall(() => client.blocks.children.list({ block_id: blockId, start_cursor: cursor })));
   const renderContainer = async (client, block, render) => {
@@ -2127,7 +2242,7 @@ var notionSource = (options, ctx) => {
     };
     if (block.type === "callout") {
       const body = [
-        guardBlockStart(richToMarkdown(blockField(block))),
+        blockText2(blockField(block), textAsMdx),
         await children(block)
       ].filter(Boolean).join(`
 
@@ -2158,7 +2273,7 @@ ${rendered.join(`
   };
   const renderBlocks = async (client, blocks) => {
     const parts = await Promise.all(blocks.map(async (block) => {
-      const leaf = renderLeaf(block);
+      const leaf = renderLeaf(block, textAsMdx);
       if (leaf === null) {
         return renderContainer(client, block, renderBlocks);
       }
@@ -2311,6 +2426,7 @@ ${nested}`;
 // src/core/sources/obsidian.ts
 import { existsSync as existsSync2, watch as fsWatch2, statSync } from "node:fs";
 import { readdir as readdir2, readFile as readFile2, stat } from "node:fs/promises";
+import { YAMLException as YAMLException2 } from "js-yaml";
 import { basename as basename2, isAbsolute as isAbsolute2, join as join5, relative as relative4, resolve as resolve2 } from "pathe";
 var MARKDOWN_FILE = /\.md$/iu;
 var OBSIDIAN_COMMENT = /%%.*?%%/gu;
@@ -2643,6 +2759,9 @@ var readNote = async (vaultDir, rel, options) => {
       rel
     };
   } catch (error) {
+    if (error instanceof YAMLException2) {
+      return frontmatterYamlDiagnostic(error, absPath);
+    }
     if (error.code === "ENOENT") {
       return null;
     }
@@ -2733,7 +2852,8 @@ var obsidianSource = (options, ctx) => {
       }
     }
     const read = await Promise.all(files.map((rel) => readNote(vaultDir, rel, options)));
-    const notes = read.filter((note) => note !== null);
+    const notes = read.filter((note) => note !== null && ("rel" in note));
+    skipped.push(...read.filter((note) => note !== null && ("code" in note)));
     const { index, pairs } = buildLinkIndex(notes, options);
     const unresolved = noTargets();
     const entries = pairs.map((pair) => noteToEntry(pair, index, options, unresolved));
@@ -2809,6 +2929,10 @@ var marksOf2 = (node) => {
   };
 };
 var children2 = (node) => objectsIn(node.children);
+var leftOut = (what, options) => {
+  options.onUnsupported?.(what);
+  return unsupported(what, writesMdx(options.serializers));
+};
 var typeOf = (node) => asString(node.type) ?? "";
 var customBlock = (node, options) => {
   const fields = asObject(node.fields);
@@ -2817,7 +2941,7 @@ var customBlock = (node, options) => {
   if (fields && serializer) {
     return serializer(fields);
   }
-  return unsupported(`Lexical block${blockType ? `: ${blockType}` : ""}`, writesMdx(options.serializers));
+  return leftOut(`Lexical block${blockType ? `: ${blockType}` : ""}`, options);
 };
 var inlineParts2 = (nodes, options) => nodes.flatMap((node) => inlineNodeParts2(node, options));
 var inlineNodeParts2 = (node, options) => {
@@ -2845,12 +2969,12 @@ var inlineNodeParts2 = (node, options) => {
   }
 };
 var inlineText = (nodes, options) => guardBlockStart(renderInline(inlineParts2(nodes, options)));
-var blockText2 = (node, options) => inlineText(children2(node), options);
+var blockText3 = (node, options) => inlineText(children2(node), options);
 var renderUpload = (node, options) => {
   const value = asObject(node.value);
   const url = value ? asString(value.url) : undefined;
   if (!(value && url)) {
-    return unsupported("Lexical upload (fetch with depth 1 to populate it)", writesMdx(options.serializers));
+    return leftOut("Lexical upload (fetch with depth 1 to populate it)", options);
   }
   const alt = asString(value.alt) ?? asString(value.filename) ?? "";
   return image(alt, absoluteUrl(url, options.baseUrl));
@@ -2887,14 +3011,14 @@ ${sub}` : line));
 var renderBlock2 = (node, options) => {
   switch (typeOf(node)) {
     case "paragraph": {
-      return blockText2(node, options);
+      return blockText3(node, options);
     }
     case "heading": {
       const level = Number((asString(node.tag) ?? "h1").slice(1));
-      return `${headingPrefix(level)}${blockText2(node, options)}`;
+      return `${headingPrefix(level)}${blockText3(node, options)}`;
     }
     case "quote": {
-      return blockquote(blockText2(node, options));
+      return blockquote(blockText3(node, options));
     }
     case "list": {
       return renderList2(node, options);
@@ -2909,7 +3033,7 @@ var renderBlock2 = (node, options) => {
       return customBlock(node, options);
     }
     default: {
-      return unsupported(`Lexical node: ${typeOf(node)}`, writesMdx(options.serializers));
+      return leftOut(`Lexical node: ${typeOf(node)}`, options);
     }
   }
 };
@@ -2930,11 +3054,26 @@ var DEFAULT_FIELDS2 = {
 var payloadSource = (options, ctx) => {
   const fields = { ...DEFAULT_FIELDS2, ...options.fields };
   const origin = options.url.replace(/\/+$/u, "");
-  const lower = (body) => lexicalToMarkdown(body, {
+  const lower = (body, leftOut) => lexicalToMarkdown(body, {
     baseUrl: origin,
+    onUnsupported: (what) => leftOut.add(what),
     serializers: options.serializers
   });
-  const fetchEntries = async () => {
+  const toEntry = (doc, draft, warn) => {
+    const leftOut = new Set;
+    const id = asString(doc.id) ?? String(doc.id ?? "");
+    const entry = documentEntry(doc, fields, id, (body) => isJsonObject(body) ? lower(body, leftOut) : "", draft, writesMdx(options.serializers));
+    for (const what of leftOut) {
+      warn({
+        code: "BLUME_SOURCE_UNSUPPORTED_NODE",
+        message: `Source "${options.name}": "${entry.ref}" has content Blume has no Markdown for (${what}), left out as a comment.`,
+        severity: "warning",
+        suggestion: "Map a block type to a component with a serializer on payloadSource, passed to custom(); other nodes have no Markdown equivalent."
+      });
+    }
+    return entry;
+  };
+  const fetchEntries = async (warn) => {
     const preview = ctx?.preview ?? false;
     const token = options.token ?? process.env.PAYLOAD_API_KEY;
     const client = {
@@ -2964,8 +3103,7 @@ var payloadSource = (options, ctx) => {
         if (draft && !preview) {
           continue;
         }
-        const id = asString(doc.id) ?? String(doc.id ?? "");
-        entries.push(documentEntry(doc, fields, id, (body) => isJsonObject(body) ? lower(body) : "", draft, writesMdx(options.serializers)));
+        entries.push(toEntry(doc, draft, warn));
       }
       more = result.hasNextPage === true;
       page += 1;
@@ -3126,15 +3264,22 @@ var sanitySource = (options, ctx) => {
     if (description) {
       data.description = description;
     }
-    const blocks = getPath(doc, fields.body ?? "body") ?? [];
-    const markdown = Array.isArray(blocks) ? portableTextToMarkdown(blocks, {
-      imageUrl: (block) => {
-        const ref = block.asset?._ref;
-        return ref ? imageUrlFromRef(ref, options.projectId, options.dataset) : null;
-      },
-      serializers: options.serializers
-    }) : "";
-    const format = writesMdx(options.serializers) ? "mdx" : "md";
+    const body = getPath(doc, fields.body ?? "body");
+    let markdown = "";
+    let format = writesMdx(options.serializers) ? "mdx" : "md";
+    if (isStringValue2(body)) {
+      markdown = neutralizeUnsafeLinks(`${body.trimEnd()}
+`);
+      format = "md";
+    } else if (Array.isArray(body)) {
+      markdown = portableTextToMarkdown(body, {
+        imageUrl: (block) => {
+          const ref = block.asset?._ref;
+          return ref ? imageUrlFromRef(ref, options.projectId, options.dataset) : null;
+        },
+        serializers: options.serializers
+      });
+    }
     const raw = frontmatter_default.stringify(markdown, data);
     return {
       body: { format, text: markdown },
@@ -3146,13 +3291,22 @@ var sanitySource = (options, ctx) => {
     };
   };
   const load = async (refresh = ctx?.refresh ?? true) => {
+    const empty = [];
     const result = await loadWithCache(options.name, cache, async () => {
       const client = resolveClient(options, ctx?.preview ?? false);
       const docs = await client.fetch(options.query);
+      if (docs.length === 0 && !(options.token ?? process.env.SANITY_TOKEN)) {
+        empty.push({
+          code: "BLUME_MISSING_SECRET",
+          message: `Source "${options.name}" found no documents, and SANITY_TOKEN is not set. A private dataset returns nothing to a query without a token.`,
+          severity: "warning",
+          suggestion: "Set SANITY_TOKEN to a token with read access if the dataset is private."
+        });
+      }
       return docs.map(toEntry);
     }, refresh);
     snapshot = new Map(result.entries.map((entry) => [entry.ref, entry]));
-    return result;
+    return { ...result, diagnostics: [...result.diagnostics, ...empty] };
   };
   const read = async (ref) => {
     const cached = snapshot.get(ref);
@@ -3200,12 +3354,12 @@ var inlineNodeParts3 = (node) => {
     }
   }
 };
-var blockText3 = (nodes) => guardBlockStart(renderInline(inlineParts3(nodes)));
+var blockText4 = (nodes) => guardBlockStart(renderInline(inlineParts3(nodes)));
 var renderList3 = (node) => {
   const ordered = asString(node.format) === "ordered";
   return children3(node).map((item, index) => {
     const kids = children3(item);
-    const line = blockText3(kids.filter((kid) => typeOf2(kid) !== "list"));
+    const line = blockText4(kids.filter((kid) => typeOf2(kid) !== "list"));
     const sub = kids.filter((kid) => typeOf2(kid) === "list").map((list) => renderList3(list)).join(`
 `);
     const body = sub ? `${line}
@@ -3225,13 +3379,13 @@ var renderImage = (node, options) => {
 var renderBlock4 = (node, options) => {
   switch (typeOf2(node)) {
     case "paragraph": {
-      return blockText3(children3(node));
+      return blockText4(children3(node));
     }
     case "heading": {
-      return `${headingPrefix(asNumber(node.level) ?? 1)}${blockText3(children3(node))}`;
+      return `${headingPrefix(asNumber(node.level) ?? 1)}${blockText4(children3(node))}`;
     }
     case "quote": {
-      return blockquote(blockText3(children3(node)));
+      return blockquote(blockText4(children3(node)));
     }
     case "list": {
       return renderList3(node);
@@ -3389,7 +3543,12 @@ var buildSource = (adapter, name, config, context, runtime) => {
       return notionSource({ ...adapter.options, name }, ctx());
     }
     case "contentful": {
-      return contentfulSource({ ...adapter.options, name }, ctx());
+      return contentfulSource({
+        ...adapter.options,
+        i18n: config.i18n,
+        name,
+        versions: config.versions
+      }, ctx());
     }
     case "payload": {
       return payloadSource({ ...adapter.options, name }, ctx());
@@ -3543,7 +3702,20 @@ var substituteEntryVariables = (entry, variables) => {
 };
 var substituteLoadedVariables = (loaded, variables) => hasVariables(variables) ? loaded.flatMap(({ entries }) => entries.flatMap((entry) => substituteEntryVariables(entry, variables))) : [];
 var redirectPageDiagnostics = (config, pages, configFile) => config.redirects.flatMap((redirect) => {
-  const matched = pathsUnderPattern(withBasePath(config.basePath, redirect.from), pages);
+  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."
+      }
+    ] : [];
+  }
+  const matched = pathsUnderPattern(from, pages);
   const [first] = matched;
   if (first === undefined) {
     return [];
@@ -3560,6 +3732,14 @@ var redirectPageDiagnostics = (config, pages, configFile) => config.redirects.fl
   ];
 });
 var bannerLinkHref = (banner) => banner === undefined || isBannerShorthand(banner) ? undefined : banner.link?.href;
+var validatedSources = (config, context, runtime, beforeSources) => {
+  beforeSources?.(config);
+  const sources = resolveSources(config, context, runtime);
+  for (const source of sources) {
+    source.validate?.();
+  }
+  return sources;
+};
 var scanProject = async (root, options = {}) => {
   const mode = options.mode ?? "dev";
   const preview = options.preview ?? false;
@@ -3570,14 +3750,7 @@ var scanProject = async (root, options = {}) => {
   const context = resolveProjectContext(root, config, {
     runtimeDir: options.runtimeDir
   });
-  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);
   const metaSources = sources.flatMap((source) => source.staged || !source.contentRoot ? [] : [
     {
       exclude: source.exclude,
@@ -3681,7 +3854,7 @@ var scanProject = async (root, options = {}) => {
   };
 };
 
-export { directiveSource, resolveLocalizable, validateSearchPopularIcons, validateNavTargets, contentIndexable, buildManifest, findFolderMetaFiles, isWithin, scanProject };
+export { directiveSource, validateSearchPopularIcons, validateNavTargets, contentIndexable, buildManifest, findFolderMetaFiles, isWithin, scanProject };
 
-//# debugId=89E5C13A316C75D864756E2164756E21
-//# sourceMappingURL=chunk-43zcf4gz.js.map
+//# debugId=D6EC9010B970FDF164756E2164756E21
+//# sourceMappingURL=chunk-0pmb4tr4.js.map