blume 2.0.3 → 2.1.1

package/dist/cli/{chunk-j85vccga.js → chunk-ncj7w596.js}

@@ -6,6 +6,7 @@ import {
   i18nDiagnostics,
   blumeReferences,
   frontmatter_default,
+  resolveLocalizable,
   resolveDocsCollection,
   CHANGELOG_INDEX_ROUTE,
   hasChangelogIndex,
@@ -22,6 +23,11 @@ import {
   pagesByRef,
   buildNavigation,
   PUBLIC_API_URL,
+  isPatternPath,
+  pathsUnderPattern,
+  hasVariables,
+  substituteVariables,
+  undefinedVariables,
   pageMetaSchema,
   folderMetaSchema,
   versionizeRoute,
@@ -29,6 +35,7 @@ import {
   slugify,
   slugifyPath,
   unloadablePathDiagnostic,
+  frontmatterYamlDiagnostic,
   extractHeadings,
   strippedLineOffset,
   isStringValue,
@@ -59,15 +66,17 @@ import {
   neutralizeUnsafeLinks,
   columnsPrefix,
   openApiSource,
-  BLUME_IGNORE_DIRS,
-  baselineScanIgnore,
-  BLUME_WATCH_IGNORE_DIRS,
-  excludeDirSegments,
-  ignoringWatchListener,
+  isJsonObject,
+  getPath,
+  isStringValue2,
+  asString,
+  asObject,
+  asNumber,
+  objectsIn,
   createModuleLoader,
   resolveProjectContext,
   loadConfig
-} from "./chunk-pv29h0wf.js";
+} from "./chunk-ehweg4fr.js";
 import {
   getBlumeVersion,
   BlumeError,
@@ -75,232 +84,18 @@ import {
 } from "./index.js";
 import {
   trimChar,
+  normalizePath,
   isInternalPath,
   withBasePath,
   mountBasePath
-} from "./chunk-3em5wd2y.js";
-
-// src/core/manifest.ts
-var versionAlternateKey = (versionKey, locale) => `${versionKey}\x00${locale}`;
-var versionAlternatesFor = (byKey, versionKey, locale) => {
-  const key = versionAlternateKey(versionKey, locale);
-  const existing = byKey.get(key);
-  if (existing) {
-    return existing;
-  }
-  const list = [];
-  byKey.set(key, list);
-  return list;
-};
-var MANIFEST_VERSION = 1;
-var contentIndexable = (page, config) => !page.meta.search.exclude && (!page.meta.sidebar.hidden || config.search.indexing.includeHiddenPages);
-var routeDescription = (page) => page.meta.seo.description ?? page.description;
-var buildFallbackRoutes = (graph, i18n, alternatesByKey, basePath, versionAlternatesByKey) => {
-  const fallback = resolveFallbackLocale(i18n);
-  if (!fallback) {
-    return [];
-  }
-  const fallbackPages = new Map(graph.pages.flatMap((page) => page.locale === fallback && !page.monolingual ? [[page.translationKey, page]] : []));
-  const routes = [];
-  for (const { code } of i18n.locales) {
-    if (code === fallback) {
-      continue;
-    }
-    const present = new Set(graph.pages.flatMap((page) => page.locale === code ? [page.translationKey] : []));
-    for (const [key, source] of fallbackPages) {
-      if (present.has(key)) {
-        continue;
-      }
-      const path = mountBasePath(basePath, localizeRoute(key, code, i18n));
-      const versionAlternates = versionAlternatesByKey ? versionAlternatesFor(versionAlternatesByKey, source.versionKey, code) : [];
-      if (versionAlternatesByKey) {
-        versionAlternates.push({ path, version: source.version });
-      }
-      routes.push({
-        alternates: alternatesByKey.get(key) ?? [],
-        collection: source.collection ?? "docs",
-        contentType: source.contentType,
-        description: routeDescription(source),
-        draft: source.meta.draft,
-        editUrl: source.editUrl,
-        entryId: source.entryId ?? source.source.ref,
-        fallback: true,
-        hidden: source.meta.sidebar.hidden,
-        id: source.id,
-        indexable: false,
-        lastModified: source.lastModified,
-        locale: code,
-        monolingual: source.monolingual,
-        path,
-        source: source.source,
-        sourcePath: source.sourcePath,
-        title: source.title,
-        version: source.version,
-        versionAlternates
-      });
-    }
-  }
-  return routes;
-};
-var buildManifest = (options) => {
-  const { context, config, graph } = options;
-  const searchEnabled = config.search.provider.mode !== "none";
-  const { i18n } = config;
-  const alternatesByKey = new Map;
-  if (i18n) {
-    for (const page of graph.pages) {
-      const list = alternatesByKey.get(page.translationKey) ?? [];
-      list.push({ locale: page.locale, path: page.route });
-      alternatesByKey.set(page.translationKey, list);
-    }
-  }
-  const versionAlternatesByKey = config.versions ? new Map : undefined;
-  if (versionAlternatesByKey) {
-    for (const page of graph.pages) {
-      versionAlternatesFor(versionAlternatesByKey, page.versionKey, page.locale).push({ path: page.route, version: page.version });
-    }
-  }
-  const routes = graph.pages.map((page) => ({
-    aiExclude: page.meta.ai.exclude,
-    alternates: alternatesByKey.get(page.translationKey) ?? [],
-    collection: page.collection ?? "docs",
-    contentType: page.contentType,
-    description: routeDescription(page),
-    draft: page.meta.draft,
-    editUrl: page.editUrl,
-    entryId: page.entryId ?? page.source.ref,
-    hidden: page.meta.sidebar.hidden,
-    id: page.id,
-    indexable: searchEnabled && contentIndexable(page, config),
-    lastModified: page.lastModified,
-    locale: page.locale,
-    monolingual: page.monolingual,
-    path: page.route,
-    source: page.source,
-    sourcePath: page.sourcePath,
-    title: page.title,
-    version: page.version,
-    versionAlternates: versionAlternatesByKey ? versionAlternatesFor(versionAlternatesByKey, page.versionKey, page.locale) : []
-  }));
-  if (i18n) {
-    routes.push(...buildFallbackRoutes(graph, i18n, alternatesByKey, config.basePath, versionAlternatesByKey));
-  }
-  if (versionAlternatesByKey && config.versions) {
-    const rank = new Map(config.versions.archived.map((version, index) => [version.id, index + 1]));
-    for (const list of versionAlternatesByKey.values()) {
-      list.sort((a, b) => (rank.get(a.version) ?? 0) - (rank.get(b.version) ?? 0));
-    }
-  }
-  routes.sort((a, b) => a.path.localeCompare(b.path));
-  return {
-    blumeVersion: getBlumeVersion(),
-    contentRoot: context.contentRoot,
-    output: config.deployment.options.output,
-    projectRoot: context.root,
-    routes,
-    version: MANIFEST_VERSION
-  };
-};
-
-// src/core/project-graph.ts
-import { isAbsolute as isAbsolute3, relative as relative5 } from "pathe";
-
-// src/core/directive-diagnostics.ts
-import { mdxToMdast } from "satteri";
-
-// src/markdown/directives.ts
-import { toString as mdastToString } from "mdast-util-to-string";
-var CALLOUT_TYPES = new Set([
-  "danger",
-  "info",
-  "note",
-  "success",
-  "tip",
-  "warning"
-]);
-var CALLOUT_ALIASES = {
-  caution: "warning",
-  error: "danger",
-  important: "note",
-  warn: "warning"
-};
-var calloutTypeFor = (name) => {
-  const lower = name.toLowerCase();
-  if (CALLOUT_TYPES.has(lower)) {
-    return lower;
-  }
-  return CALLOUT_ALIASES[lower] ?? null;
-};
-var LITERAL_MARKERS = new Map([
-  ["leafDirective", "::"],
-  ["textDirective", ":"]
-]);
-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.`
-    };
-  });
-};
+} from "./chunk-zccbjcj0.js";
+import {
+  BLUME_IGNORE_DIRS,
+  baselineScanIgnore,
+  BLUME_WATCH_IGNORE_DIRS,
+  excludeDirSegments,
+  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;
@@ -492,41 +287,263 @@ var duplicateLabelDiagnostics = (navigation) => {
       }
     }
   };
-  const sidebars = [
-    { nodes: navigation.sidebar, where: "at the top level" }
-  ];
-  for (const { nodes, where } of sidebars) {
-    checkLevel(nodes, where);
+  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) => {
+  const key = versionAlternateKey(versionKey, locale);
+  const existing = byKey.get(key);
+  if (existing) {
+    return existing;
+  }
+  const list = [];
+  byKey.set(key, list);
+  return list;
+};
+var MANIFEST_VERSION = 1;
+var contentIndexable = (page, config) => !page.meta.search.exclude && (!page.meta.sidebar.hidden || config.search.indexing.includeHiddenPages);
+var routeDescription = (page) => page.meta.seo.description ?? page.description;
+var buildFallbackRoutes = (graph, i18n, alternatesByKey, basePath, versionAlternatesByKey) => {
+  const fallback = resolveFallbackLocale(i18n);
+  if (!fallback) {
+    return [];
+  }
+  const fallbackPages = new Map(graph.pages.flatMap((page) => page.locale === fallback && !page.monolingual ? [[page.translationKey, page]] : []));
+  const routes = [];
+  for (const { code } of i18n.locales) {
+    if (code === fallback) {
+      continue;
+    }
+    const present = new Set(graph.pages.flatMap((page) => page.locale === code ? [page.translationKey] : []));
+    for (const [key, source] of fallbackPages) {
+      if (present.has(key)) {
+        continue;
+      }
+      const path = mountBasePath(basePath, localizeRoute(key, code, i18n));
+      const versionAlternates = versionAlternatesByKey ? versionAlternatesFor(versionAlternatesByKey, source.versionKey, code) : [];
+      if (versionAlternatesByKey) {
+        versionAlternates.push({ path, version: source.version });
+      }
+      routes.push({
+        alternates: alternatesByKey.get(key) ?? [],
+        collection: source.collection ?? "docs",
+        contentType: source.contentType,
+        description: routeDescription(source),
+        draft: source.meta.draft,
+        editUrl: source.editUrl,
+        entryId: source.entryId ?? source.source.ref,
+        fallback: true,
+        hidden: source.meta.sidebar.hidden,
+        id: source.id,
+        indexable: false,
+        lastModified: source.lastModified,
+        locale: code,
+        monolingual: source.monolingual,
+        path,
+        source: source.source,
+        sourcePath: source.sourcePath,
+        title: source.title,
+        version: source.version,
+        versionAlternates
+      });
+    }
+  }
+  return routes;
+};
+var buildManifest = (options) => {
+  const { context, config, graph } = options;
+  const searchEnabled = config.search.provider.mode !== "none";
+  const { i18n } = config;
+  const alternatesByKey = new Map;
+  if (i18n) {
+    for (const page of graph.pages) {
+      const list = alternatesByKey.get(page.translationKey) ?? [];
+      list.push({ locale: page.locale, path: page.route });
+      alternatesByKey.set(page.translationKey, list);
+    }
+  }
+  const versionAlternatesByKey = config.versions ? new Map : undefined;
+  if (versionAlternatesByKey) {
+    for (const page of graph.pages) {
+      versionAlternatesFor(versionAlternatesByKey, page.versionKey, page.locale).push({ path: page.route, version: page.version });
+    }
+  }
+  const routes = graph.pages.map((page) => ({
+    aiExclude: page.meta.ai.exclude,
+    alternates: alternatesByKey.get(page.translationKey) ?? [],
+    collection: page.collection ?? "docs",
+    contentType: page.contentType,
+    description: routeDescription(page),
+    draft: page.meta.draft,
+    editUrl: page.editUrl,
+    entryId: page.entryId ?? page.source.ref,
+    hidden: page.meta.sidebar.hidden,
+    id: page.id,
+    indexable: searchEnabled && contentIndexable(page, config),
+    lastModified: page.lastModified,
+    locale: page.locale,
+    monolingual: page.monolingual,
+    path: page.route,
+    source: page.source,
+    sourcePath: page.sourcePath,
+    title: page.title,
+    version: page.version,
+    versionAlternates: versionAlternatesByKey ? versionAlternatesFor(versionAlternatesByKey, page.versionKey, page.locale) : []
+  }));
+  if (i18n) {
+    routes.push(...buildFallbackRoutes(graph, i18n, alternatesByKey, config.basePath, versionAlternatesByKey));
+  }
+  if (versionAlternatesByKey && config.versions) {
+    const rank = new Map(config.versions.archived.map((version, index) => [version.id, index + 1]));
+    for (const list of versionAlternatesByKey.values()) {
+      list.sort((a, b) => (rank.get(a.version) ?? 0) - (rank.get(b.version) ?? 0));
+    }
+  }
+  routes.sort((a, b) => a.path.localeCompare(b.path));
+  return {
+    blumeVersion: getBlumeVersion(),
+    contentRoot: context.contentRoot,
+    output: config.deployment.options.output,
+    projectRoot: context.root,
+    routes,
+    version: MANIFEST_VERSION
+  };
+};
+
+// src/core/project-graph.ts
+import { isAbsolute as isAbsolute3, relative as relative5 } from "pathe";
+
+// src/core/directive-diagnostics.ts
+import { mdxToMdast } from "satteri";
+
+// src/markdown/directives.ts
+import { toString as mdastToString } from "mdast-util-to-string";
+var CALLOUT_TYPES = new Set([
+  "danger",
+  "info",
+  "note",
+  "success",
+  "tip",
+  "warning"
+]);
+var CALLOUT_ALIASES = {
+  caution: "warning",
+  error: "danger",
+  important: "note",
+  warn: "warning"
+};
+var calloutTypeFor = (name) => {
+  const lower = name.toLowerCase();
+  if (CALLOUT_TYPES.has(lower)) {
+    return lower;
   }
-  return diagnostics;
+  return CALLOUT_ALIASES[lower] ?? null;
 };
-var hiddenInSidebarDiagnostics = (navigation, pages) => {
-  const hidden = new Set(pages.flatMap((page) => page.meta.sidebar.hidden ? [page.id] : []));
-  if (hidden.size === 0) {
+var LITERAL_MARKERS = new Map([
+  ["leafDirective", "::"],
+  ["textDirective", ":"]
+]);
+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 [];
   }
-  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."
-        });
+  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 [];
   }
-  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) => {
@@ -566,13 +583,6 @@ var localePagesFor = (code, real, fallback, fallbackByKey, i18n, basePath) => {
   }
   return [...real, ...filled];
 };
-var isSingleLabel = (label) => typeof label === "string";
-var resolveLabel = (label, locale, defaultLocale) => {
-  if (isSingleLabel(label)) {
-    return label;
-  }
-  return label[locale] ?? (defaultLocale === undefined ? undefined : label[defaultLocale]) ?? Object.values(label)[0] ?? "";
-};
 var localizeSidebarHrefs = (items, localize) => items.map((item) => {
   if (isPageRef(item)) {
     return item;
@@ -590,10 +600,19 @@ var resolveTabLabels = (tabs, locale, defaultLocale) => (tabs ?? []).map((tab) =
   ...tab,
   items: tab.items?.map((item) => ({
     ...item,
-    label: resolveLabel(item.label, locale, defaultLocale)
+    label: resolveLocalizable(item.label, locale, defaultLocale)
   })),
-  label: resolveLabel(tab.label, locale, defaultLocale)
+  label: resolveLocalizable(tab.label, locale, defaultLocale)
 }));
+var withLabel = (link, locale, defaultLocale) => ({
+  ...link,
+  label: resolveLocalizable(link.label, locale, defaultLocale)
+});
+var resolveHeaderLinks = (navigation, locale, defaultLocale) => ({
+  actions: navigation.actions.map((link) => withLabel(link, locale, defaultLocale)),
+  cta: navigation.cta ? withLabel(navigation.cta, locale, defaultLocale) : null,
+  featured: navigation.featured.map((link) => withLabel(link, locale, defaultLocale))
+});
 var mountConfiguredLink = (path, basePath, extraRoutes) => extraRoutes.has(path) ? path : withBasePath(basePath, path);
 var buildLocaleNavigation = (code, pages, fallback, fallbackByKey, options, i18n, diagnostics, version = "") => {
   const basePath = options.basePath ?? "";
@@ -637,17 +656,17 @@ var buildLocaleNavigation = (code, pages, fallback, fallbackByKey, options, i18n
     ...item,
     href: localizeServed(item.href, false)
   });
-  const { actions, cta, featured } = options.navigation;
+  const { actions, cta, featured } = resolveHeaderLinks(options.navigation, code, i18n.defaultLocale);
   const sidebarItems = options.navigation.sidebar.items;
   const navigation = buildNavigation(localePages, {
-    actions: actions?.map(localizeHref),
+    actions: actions.map(localizeHref),
     basePath,
     cta: cta ? localizeHref(cta) : null,
     diagnostics,
     display: options.navigation.sidebar.display,
     extraRoutes: options.extraRoutes,
     fallbackMetaPrefix,
-    featured: featured?.map(localizeHref),
+    featured: featured.map(localizeHref),
     folderMeta: options.folderMeta,
     localizedRoot: localizeRoute(versionizeRoute("/", version), code, i18n),
     metaPrefix: [version, localeDir].filter(Boolean).join("/"),
@@ -709,13 +728,11 @@ var buildVersionNavigation = (id, versionPages, options, diagnostics) => {
   }
   return {
     "": buildNavigation(versionPages, {
-      actions: options.navigation.actions,
+      ...resolveHeaderLinks(options.navigation, ""),
       basePath: options.basePath ?? "",
-      cta: options.navigation.cta,
       diagnostics,
       display: options.navigation.sidebar.display,
       extraRoutes: options.extraRoutes,
-      featured: options.navigation.featured,
       folderMeta: options.folderMeta,
       localizedRoot: versionizeRoute("/", id),
       metaPrefix: id,
@@ -737,13 +754,11 @@ var buildContentGraph = (pages, options) => {
     ({ navigation, navigationByLocale } = buildI18nNavigation(currentPages, options, i18n, diagnostics));
   } else {
     navigation = buildNavigation(currentPages, {
-      actions: options.navigation.actions,
+      ...resolveHeaderLinks(options.navigation, ""),
       basePath: options.basePath ?? "",
-      cta: options.navigation.cta,
       diagnostics,
       display: options.navigation.sidebar.display,
       extraRoutes: options.extraRoutes,
-      featured: options.navigation.featured,
       folderMeta: options.folderMeta,
       selectors: options.navigation.selectors,
       sharedFolderMeta: options.sharedFolderMeta,
@@ -986,30 +1001,6 @@ var discoverFolderMeta = async (sources, options = {}) => {
 // src/core/sources/resolve.ts
 import { join as join7 } from "pathe";
 
-// src/core/sources/json.ts
-var isJsonObject = (value) => typeof value === "object" && value !== null;
-var getPath = (doc, path) => {
-  let current = doc;
-  for (const key of path.split(".")) {
-    if (isJsonObject(current)) {
-      current = current[key];
-    } else {
-      return;
-    }
-  }
-  return current;
-};
-var isStringValue2 = (value) => typeof value === "string";
-var asString = (value) => isStringValue2(value) ? value : undefined;
-var asArray = (value) => Array.isArray(value) ? value : [];
-var asObject = (value) => isJsonObject(value) && !Array.isArray(value) ? value : undefined;
-var isNumberValue = (value) => typeof value === "number";
-var asNumber = (value) => isNumberValue(value) ? value : undefined;
-var objectsIn = (value) => asArray(value).flatMap((item) => {
-  const object = asObject(item);
-  return object ? [object] : [];
-});
-
 // src/core/sources/contentful-rich-text.ts
 var HEADING = /^heading-(?<level>[1-6])$/u;
 var CELL_PIPE = /\|/gu;
@@ -1020,7 +1011,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)
   };
@@ -1088,6 +1081,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) }];
     }
@@ -1139,7 +1137,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);
@@ -1161,9 +1166,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);
@@ -1194,6 +1207,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;
@@ -1215,9 +1234,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));
@@ -1230,6 +1249,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";
@@ -1244,8 +1267,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",
@@ -1255,20 +1278,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;
@@ -1282,15 +1335,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) {
@@ -1306,16 +1362,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,
@@ -1330,6 +1390,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) => {
@@ -1352,11 +1413,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,
@@ -1365,6 +1434,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 = () => {
@@ -1530,11 +1607,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));
@@ -1645,6 +1728,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;
@@ -1683,7 +1771,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 [];
@@ -1700,7 +1788,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;
@@ -1721,7 +1815,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 };
   };
@@ -1742,12 +1836,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 = [];
@@ -2119,7 +2222,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) => {
@@ -2315,6 +2422,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;
@@ -2647,6 +2755,9 @@ var readNote = async (vaultDir, rel, options) => {
       rel
     };
   } catch (error) {
+    if (error instanceof YAMLException2) {
+      return frontmatterYamlDiagnostic(error, absPath);
+    }
     if (error.code === "ENOENT") {
       return null;
     }
@@ -2737,7 +2848,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));
@@ -2813,6 +2925,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);
@@ -2821,7 +2937,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) => {
@@ -2854,7 +2970,7 @@ 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));
@@ -2913,7 +3029,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);
     }
   }
 };
@@ -2934,11 +3050,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 = {
@@ -2968,8 +3099,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;
@@ -3130,15 +3260,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 },
@@ -3150,13 +3287,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);
@@ -3393,7 +3539,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());
@@ -3523,7 +3674,68 @@ var gitContentRoots = (sources, gitRoot) => {
 var isLogoShorthand = (logo) => typeof logo === "string";
 var logoHref = (logo) => logo === undefined || isLogoShorthand(logo) ? "/" : logo.href ?? "/";
 var isBannerShorthand = (banner) => typeof banner === "string";
+var substituteEntryVariables = (entry, variables) => {
+  const { expanded } = entry;
+  const text = expanded?.text ?? entry.body.text;
+  const offset = expanded ? 0 : strippedLineOffset(entry.raw, entry.body.text);
+  const diagnostics = undefinedVariables(text, variables).map(({ line, name }) => {
+    const origin = expanded?.origins[line - 1];
+    return {
+      code: "BLUME_UNDEFINED_VARIABLE",
+      file: origin?.file ?? entry.sourcePath,
+      line: origin?.line ?? line + offset,
+      message: `{{${name}}} isn't a defined variable, so it would show as written.`,
+      severity: "error",
+      suggestion: `Define "${name}" under variables in blume.config.ts, or put it in inline code to show it as written.`
+    };
+  });
+  if (expanded) {
+    expanded.text = substituteVariables(expanded.text, variables);
+  } else {
+    entry.body.text = substituteVariables(entry.body.text, variables);
+  }
+  return diagnostics;
+};
+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 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 [];
+  }
+  const more = matched.length > 1 ? ` and ${matched.length - 1} more` : "";
+  return [
+    {
+      code: "BLUME_REDIRECT_MATCHES_PAGE",
+      file: configFile ?? undefined,
+      message: `The redirect from ${redirect.from} also matches the page ${first}${more}, which some hosts would redirect and others would serve.`,
+      severity: "error",
+      suggestion: "Narrow the pattern to the paths that moved, or move the pages out from under it."
+    }
+  ];
+});
 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;
@@ -3534,14 +3746,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,
@@ -3576,6 +3781,7 @@ var scanProject = async (root, options = {}) => {
       includeDiagnostics.push(...expansion.errors);
     });
   }));
+  const variableDiagnostics = substituteLoadedVariables(loaded, config.variables);
   const sharedFolderMeta = new Map([
     ...loaded.flatMap(({ folderMeta: sourceMeta }) => Object.entries(sourceMeta ?? {})),
     ...folderMeta.shared
@@ -3602,14 +3808,15 @@ var scanProject = async (root, options = {}) => {
     lastModifiedWarnings.push(...lastModifiedShallowWarning(context.root, undated));
   }
   const customPages = context.pagesRoot ? await discoverPages(context.pagesRoot) : [];
+  const extraRoutes = new Set([
+    ...customStaticRoutes(customPages),
+    ...hasChangelogIndex(pages, config) ? [CHANGELOG_INDEX_ROUTE] : []
+  ]);
   const graph = buildContentGraph(pages, {
     bannerHref: bannerLinkHref(config.banner),
     basePath: config.basePath,
     brandHref: logoHref(config.logo),
-    extraRoutes: new Set([
-      ...customStaticRoutes(customPages),
-      ...hasChangelogIndex(pages, config) ? [CHANGELOG_INDEX_ROUTE] : []
-    ]),
+    extraRoutes,
     folderMeta: folderMeta.meta,
     i18n: config.i18n,
     navigation: config.navigation,
@@ -3625,12 +3832,14 @@ var scanProject = async (root, options = {}) => {
     diagnostics: [
       ...contentDiagnostics,
       ...includeDiagnostics,
+      ...variableDiagnostics,
       ...folderMeta.diagnostics,
       ...entryIdDiagnostics(pages, resolveDocsCollection(config, context.root).base),
       ...graph.diagnostics,
       ...i18nWarnings,
       ...versionWarnings,
-      ...lastModifiedWarnings
+      ...lastModifiedWarnings,
+      ...redirectPageDiagnostics(config, [...manifest.routes.map((route) => route.path), ...extraRoutes], context.configFile)
     ],
     droppedPages,
     graph,
@@ -3643,5 +3852,5 @@ var scanProject = async (root, options = {}) => {
 
 export { directiveSource, validateSearchPopularIcons, validateNavTargets, contentIndexable, buildManifest, findFolderMetaFiles, isWithin, scanProject };
 
-//# debugId=B7A86608D56AB00864756E2164756E21
-//# sourceMappingURL=chunk-j85vccga.js.map
+//# debugId=1F41F69354D6E33464756E2164756E21
+//# sourceMappingURL=chunk-ncj7w596.js.map