blume 2.0.1 → 2.0.3

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

@@ -1,5 +1,9 @@
 #!/usr/bin/env node
 import {
+  resolveFallbackLocale,
+  localizeRoute,
+  localizeInternalPath,
+  i18nDiagnostics,
   blumeReferences,
   frontmatter_default,
   resolveDocsCollection,
@@ -12,10 +16,11 @@ import {
   pollingWatch,
   snapshotCache,
   loadWithCache,
-  resolveFallbackLocale,
-  localizeRoute,
-  localizeInternalPath,
-  i18nDiagnostics,
+  MDX_BODY_FEATURES,
+  normalizeRef,
+  isPageRef,
+  pagesByRef,
+  buildNavigation,
   PUBLIC_API_URL,
   pageMetaSchema,
   folderMetaSchema,
@@ -23,6 +28,7 @@ import {
   versionsDiagnostics,
   slugify,
   slugifyPath,
+  unloadablePathDiagnostic,
   extractHeadings,
   strippedLineOffset,
   isStringValue,
@@ -35,8 +41,10 @@ import {
   parseYouTubeId,
   nodeRequire,
   escapeMarkdownText,
+  guardBlockStart,
   renderInline,
-  renderLink,
+  destination,
+  linkParts,
   headingPrefix,
   blockquote,
   listItem,
@@ -51,10 +59,15 @@ import {
   neutralizeUnsafeLinks,
   columnsPrefix,
   openApiSource,
+  BLUME_IGNORE_DIRS,
+  baselineScanIgnore,
+  BLUME_WATCH_IGNORE_DIRS,
+  excludeDirSegments,
+  ignoringWatchListener,
   createModuleLoader,
   resolveProjectContext,
   loadConfig
-} from "./chunk-qkqwkpte.js";
+} from "./chunk-pv29h0wf.js";
 import {
   getBlumeVersion,
   BlumeError,
@@ -64,15 +77,8 @@ import {
   trimChar,
   isInternalPath,
   withBasePath,
-  stripBasePath
-} from "./chunk-jts8mvcz.js";
-import {
-  BLUME_IGNORE_DIRS,
-  baselineScanIgnore,
-  BLUME_WATCH_IGNORE_DIRS,
-  excludeDirSegments,
-  ignoringWatchListener
-} from "./chunk-abh8yjkn.js";
+  mountBasePath
+} from "./chunk-3em5wd2y.js";
 
 // src/core/manifest.ts
 var versionAlternateKey = (versionKey, locale) => `${versionKey}\x00${locale}`;
@@ -105,7 +111,7 @@ var buildFallbackRoutes = (graph, i18n, alternatesByKey, basePath, versionAltern
       if (present.has(key)) {
         continue;
       }
-      const path = withBasePath(basePath, localizeRoute(key, code, i18n));
+      const path = mountBasePath(basePath, localizeRoute(key, code, i18n));
       const versionAlternates = versionAlternatesByKey ? versionAlternatesFor(versionAlternatesByKey, source.versionKey, code) : [];
       if (versionAlternatesByKey) {
         versionAlternates.push({ path, version: source.version });
@@ -155,6 +161,7 @@ var buildManifest = (options) => {
     }
   }
   const routes = graph.pages.map((page) => ({
+    aiExclude: page.meta.ai.exclude,
     alternates: alternatesByKey.get(page.translationKey) ?? [],
     collection: page.collection ?? "docs",
     contentType: page.contentType,
@@ -198,6 +205,103 @@ var buildManifest = (options) => {
 // 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.`
+    };
+  });
+};
+
 // 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;
@@ -315,7 +419,7 @@ var validateNavTargets = (navigation, routes) => {
     if (!isInternalPath(path) || path.startsWith("/#") || seen.has(path)) {
       continue;
     }
-    if (!resolvesToPages(routes, path.split("#")[0] ?? path)) {
+    if (!resolvesToPages(routes, path.split(/[?#]/u)[0] ?? path)) {
       seen.add(path);
       diagnostics.push({
         code: "BLUME_NAV_MISSING_PAGE",
@@ -327,6 +431,44 @@ var validateNavTargets = (navigation, routes) => {
   }
   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) => {
@@ -386,541 +528,6 @@ var validateNavStructure = (navigation, pages) => [
   ...hiddenInSidebarDiagnostics(navigation, pages)
 ];
 
-// src/core/navigation.ts
-import { extname } from "pathe";
-var NUMERIC_PREFIX = /^(?<order>\d+)[-_.]/u;
-var GROUP_FOLDER = /^\((?<label>.+)\)$/u;
-var WORD_SPLIT = /[-_]/u;
-var isUnderPath = (route, base) => base === "/" || route === base || route.startsWith(`${base}/`);
-var isRootTab = (tab, root) => isUnderPath(root, tab.path);
-var sidebarIcon = (page) => page.meta.sidebar.icon ?? page.meta.icon;
-var WORD_FORMS = new Map([
-  ["ai", "AI"],
-  ["api", "API"],
-  ["apis", "APIs"],
-  ["asyncapi", "AsyncAPI"],
-  ["cli", "CLI"],
-  ["css", "CSS"],
-  ["faq", "FAQ"],
-  ["faqs", "FAQs"],
-  ["graphql", "GraphQL"],
-  ["html", "HTML"],
-  ["http", "HTTP"],
-  ["https", "HTTPS"],
-  ["id", "ID"],
-  ["ids", "IDs"],
-  ["ios", "iOS"],
-  ["js", "JS"],
-  ["json", "JSON"],
-  ["jwt", "JWT"],
-  ["llm", "LLM"],
-  ["llms", "LLMs"],
-  ["macos", "macOS"],
-  ["mcp", "MCP"],
-  ["oauth", "OAuth"],
-  ["openapi", "OpenAPI"],
-  ["rss", "RSS"],
-  ["sdk", "SDK"],
-  ["sdks", "SDKs"],
-  ["seo", "SEO"],
-  ["sql", "SQL"],
-  ["sso", "SSO"],
-  ["ts", "TS"],
-  ["ui", "UI"],
-  ["url", "URL"],
-  ["urls", "URLs"],
-  ["xml", "XML"],
-  ["yaml", "YAML"]
-]);
-var humanize = (segment) => segment.replace(NUMERIC_PREFIX, "").split(WORD_SPLIT).filter(Boolean).map((word) => WORD_FORMS.get(word) ?? word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
-var numericOrder = (segment) => {
-  const value = segment.match(NUMERIC_PREFIX)?.groups?.order;
-  return value ? Math.trunc(Number(value)) : Number.POSITIVE_INFINITY;
-};
-var segmentKey = (raw) => {
-  const group = raw.match(GROUP_FOLDER)?.groups?.label;
-  return (group ?? raw).replace(NUMERIC_PREFIX, "");
-};
-var isIndexStem = (stem) => stem.replace(NUMERIC_PREFIX, "") === "index";
-var stemOf = (filename) => filename.replace(extname(filename), "");
-var navStem = (navPath) => stemOf(navPath.split("/").at(-1) ?? navPath);
-var createGroup = (key, path, label, order) => ({
-  children: [],
-  index: new Map,
-  key,
-  kind: "group",
-  label,
-  order,
-  path
-});
-var ensureGroup = (parent, rawSegment) => {
-  const existing = parent.index.get(rawSegment);
-  if (existing) {
-    return existing;
-  }
-  const path = parent.path ? `${parent.path}/${rawSegment}` : rawSegment;
-  const group = createGroup(segmentKey(rawSegment), path, humanize(rawSegment.match(GROUP_FOLDER)?.groups?.label ?? rawSegment), numericOrder(rawSegment));
-  parent.index.set(rawSegment, group);
-  parent.children.push(group);
-  return group;
-};
-var pageOrder = (page, filename) => {
-  if (page.meta.sidebar.order !== undefined) {
-    return { order: page.meta.sidebar.order, orderIsAuthored: true };
-  }
-  if (isIndexStem(stemOf(filename))) {
-    return { order: Number.NEGATIVE_INFINITY, orderIsAuthored: false };
-  }
-  if (page.contentType === "changelog") {
-    const iso = page.meta.date ?? page.meta.changelog?.date;
-    const time = iso ? Date.parse(iso) : Number.NaN;
-    if (!Number.isNaN(time)) {
-      return { order: -time, orderIsAuthored: false };
-    }
-  }
-  const order = numericOrder(filename);
-  return {
-    order,
-    orderIsAuthored: page.contentType !== "changelog" && Number.isFinite(order)
-  };
-};
-var metaKey = (path, metaPrefix) => {
-  if (!metaPrefix) {
-    return path;
-  }
-  return path ? `${metaPrefix}/${path}` : metaPrefix;
-};
-var applyFolderMeta = (group, folderMeta, sharedMeta, metaPrefix, sharedMetaPrefix, indexDisplay, indexRoute) => {
-  group.route = indexRoute.get(group.path);
-  const meta = folderMeta.get(metaKey(group.path, metaPrefix)) ?? sharedMeta.get(metaKey(group.path, sharedMetaPrefix));
-  group.display = indexDisplay.get(group.path) ?? meta?.display;
-  if (meta) {
-    group.label = meta.title ?? group.label;
-    group.icon = meta.icon ?? group.icon;
-    group.order = meta.order ?? group.order;
-    group.collapsed = meta.collapsed ?? group.collapsed;
-    if (meta.pages) {
-      const rank = new Map(meta.pages.map((key, i) => [key, i]));
-      for (const child of group.children) {
-        const position = rank.get(child.key);
-        if (position !== undefined) {
-          child.order = position;
-          if (child.kind === "page") {
-            child.orderIsAuthored = true;
-          }
-        }
-      }
-    }
-  }
-  for (const child of group.children) {
-    if (child.kind === "group") {
-      applyFolderMeta(child, folderMeta, sharedMeta, metaPrefix, sharedMetaPrefix, indexDisplay, indexRoute);
-    }
-  }
-};
-var indexTitleMismatchDiagnostic = (page, folderPath, folderMeta, sharedMeta, metaPrefix, sharedMetaPrefix) => {
-  if (!(page.meta.title && page.meta.sidebar.hidden) || page.fallback || folderPath === "") {
-    return;
-  }
-  const meta = folderMeta.get(metaKey(folderPath, metaPrefix)) ?? sharedMeta.get(metaKey(folderPath, sharedMetaPrefix));
-  if (!meta?.title || meta.title === page.title) {
-    return;
-  }
-  return {
-    code: "BLUME_NAV_INDEX_TITLE_MISMATCH",
-    file: page.sourcePath ?? page.id,
-    message: `Index page "${page.navPath}" has title "${page.title}", but its folder's meta.title is "${meta.title}" — the sidebar shows the folder title while the page's own <title>/heading still say "${page.title}".`,
-    severity: "warning",
-    suggestion: `Update the page's frontmatter title to match ("${meta.title}"), or leave it if the divergence is intentional.`
-  };
-};
-var sidebarDisplayIgnoredDiagnostics = (pages, explicitSidebar) => {
-  const diagnostics = [];
-  for (const page of pages) {
-    if (!page.meta.sidebar.display) {
-      continue;
-    }
-    const isIndex = isIndexStem(navStem(page.navPath));
-    if (explicitSidebar) {
-      diagnostics.push({
-        code: "BLUME_SIDEBAR_DISPLAY_IGNORED",
-        file: page.sourcePath ?? page.id,
-        message: `"${page.navPath}" sets sidebar.display, but the explicit navigation.sidebar config owns each group's display mode — the value is ignored.`,
-        severity: "warning",
-        suggestion: "Set display on the matching group in navigation.sidebar, or remove the frontmatter key."
-      });
-      continue;
-    }
-    if (isIndex && !page.navPath.includes("/")) {
-      diagnostics.push({
-        code: "BLUME_SIDEBAR_DISPLAY_IGNORED",
-        file: page.sourcePath ?? page.id,
-        message: `"${page.navPath}" sets sidebar.display, but the content root is not a sidebar group — the value is ignored.`,
-        severity: "warning",
-        suggestion: "Set navigation.sidebar.display in blume.config to change the sidebar-wide mode."
-      });
-      continue;
-    }
-    if (isIndex) {
-      continue;
-    }
-    diagnostics.push({
-      code: "BLUME_SIDEBAR_DISPLAY_IGNORED",
-      file: page.sourcePath ?? page.id,
-      message: `"${page.navPath}" sets sidebar.display, but only a folder's index page can set its group's display mode — the value is ignored.`,
-      severity: "warning",
-      suggestion: "Move display to the folder's index page frontmatter, or set it in the folder's meta.ts."
-    });
-  }
-  return diagnostics;
-};
-var isAuthoredOrder = (node) => node.kind === "group" || node.orderIsAuthored;
-var duplicateOrderDiagnostics = (nodes) => {
-  const byOrder = new Map;
-  for (const node of nodes) {
-    if (!Number.isFinite(node.order) || !isAuthoredOrder(node)) {
-      continue;
-    }
-    const tied = byOrder.get(node.order);
-    if (tied) {
-      tied.push(node);
-    } else {
-      byOrder.set(node.order, [node]);
-    }
-  }
-  const diagnostics = [];
-  for (const [order, tied] of byOrder) {
-    if (tied.length > 1) {
-      const names = tied.map((node) => `"${node.label}"`);
-      const list = names.length > 2 ? `${names.slice(0, -1).join(", ")}, and ${names.at(-1)}` : names.join(" and ");
-      const verb = tied.length > 2 ? "all have" : "both have";
-      const file = tied.find((node) => node.kind === "page")?.file;
-      diagnostics.push({
-        code: "BLUME_DUPLICATE_SIDEBAR_ORDER",
-        file,
-        message: `${list} ${verb} sidebar order ${order}; falling back to alphabetical order.`,
-        severity: "warning",
-        suggestion: "Give each item a distinct sidebar.order (or folder meta order)."
-      });
-    }
-  }
-  return diagnostics;
-};
-var sortNodes = (nodes, diagnostics) => {
-  diagnostics.push(...duplicateOrderDiagnostics(nodes));
-  nodes.sort((a, b) => {
-    if (a.order !== b.order) {
-      return a.order - b.order;
-    }
-    return a.label.localeCompare(b.label);
-  });
-  for (const node of nodes) {
-    if (node.kind === "group") {
-      sortNodes(node.children, diagnostics);
-    }
-  }
-};
-var hoistPages = (nodes, display, hoist) => {
-  const groups = nodes.filter((node) => node.kind === "group");
-  if (hoist || groups.some((group) => (group.display ?? display) === "flat")) {
-    const pages = nodes.filter((node) => node.kind === "page");
-    nodes.splice(0, nodes.length, ...pages, ...groups);
-  }
-  for (const group of groups) {
-    hoistPages(group.children, display, false);
-  }
-};
-var hoistTabSections = (nodes, tabPaths, display) => {
-  for (const node of nodes) {
-    if (node.kind !== "group") {
-      continue;
-    }
-    if (node.routePath !== undefined && tabPaths.has(node.routePath)) {
-      hoistPages(node.children, display, true);
-    }
-    hoistTabSections(node.children, tabPaths, display);
-  }
-};
-var toNavNode = (node, display) => {
-  if (node.kind === "page") {
-    return {
-      badge: node.badge,
-      deprecated: node.deprecated || undefined,
-      description: node.description,
-      icon: node.icon,
-      kind: "page",
-      label: node.label,
-      pageId: node.pageId,
-      route: node.route
-    };
-  }
-  return {
-    children: node.children.map((child) => toNavNode(child, display)),
-    collapsed: node.collapsed,
-    display: node.display ?? display,
-    icon: node.icon,
-    kind: "group",
-    label: node.label,
-    path: node.routePath,
-    route: node.route
-  };
-};
-var buildFileSystemSidebar = (pages, folderMeta, sharedMeta, metaPrefix, sharedMetaPrefix, display, tabPaths, diagnostics = []) => {
-  const root = createGroup("", "", "", 0);
-  const indexDisplay = new Map;
-  const indexRoute = new Map;
-  for (const page of pages) {
-    const parts = page.navPath.split("/");
-    const filename = parts.at(-1) ?? page.navPath;
-    const stem = stemOf(filename);
-    const dirs = parts.slice(0, -1);
-    if (isIndexStem(stem)) {
-      const diagnostic = indexTitleMismatchDiagnostic(page, dirs.join("/"), folderMeta, sharedMeta, metaPrefix, sharedMetaPrefix);
-      if (diagnostic) {
-        diagnostics.push(diagnostic);
-      }
-      if (page.meta.sidebar.display && !page.fallback) {
-        indexDisplay.set(dirs.join("/"), page.meta.sidebar.display);
-      }
-      if (dirs.length > 0) {
-        indexRoute.set(dirs.join("/"), page.route);
-      }
-    }
-    if (page.meta.sidebar.hidden) {
-      continue;
-    }
-    const routeSegments = page.route.split("/").filter(Boolean);
-    const folderParts = isIndexStem(stem) ? routeSegments : routeSegments.slice(0, -1);
-    const routeDirCount = dirs.filter((dir) => !GROUP_FOLDER.test(dir)).length;
-    const offset = Math.max(0, folderParts.length - routeDirCount);
-    let parent = root;
-    let consumed = offset;
-    for (const dir of dirs) {
-      parent = ensureGroup(parent, dir);
-      if (!GROUP_FOLDER.test(dir)) {
-        consumed += 1;
-      }
-      parent.routePath ??= `/${folderParts.slice(0, consumed).join("/")}`;
-    }
-    const { order, orderIsAuthored } = pageOrder(page, filename);
-    parent.children.push({
-      badge: page.meta.sidebar.badge,
-      deprecated: page.meta.deprecated || undefined,
-      description: page.description,
-      file: page.sourcePath,
-      icon: sidebarIcon(page),
-      key: segmentKey(stem),
-      kind: "page",
-      label: page.meta.sidebar.label ?? page.title,
-      order,
-      orderIsAuthored,
-      pageId: page.id,
-      route: page.route
-    });
-  }
-  applyFolderMeta(root, folderMeta, sharedMeta, metaPrefix, sharedMetaPrefix, indexDisplay, indexRoute);
-  sortNodes(root.children, diagnostics);
-  hoistPages(root.children, display, true);
-  hoistTabSections(root.children, tabPaths, display);
-  return root.children.map((child) => toNavNode(child, display));
-};
-var normalizeRef = (ref) => {
-  if (ref === "index") {
-    return "/";
-  }
-  const withSlash = ref.startsWith("/") ? ref : `/${ref}`;
-  const noTrailing = withSlash.replace(/\/+$/u, "");
-  const trimmed = noTrailing.endsWith("/index") ? noTrailing.slice(0, -"/index".length) : noTrailing;
-  return trimmed === "" ? "/" : trimmed;
-};
-var routeForRef = (ref, byRoute, basePath) => {
-  if (!ref) {
-    return;
-  }
-  const normalized = normalizeRef(ref);
-  return byRoute.get(normalized)?.route ?? withBasePath(basePath, normalized);
-};
-var isPageRef = (item) => typeof item === "string";
-var configItemToNode = (item, byRoute, basePath) => {
-  if (isPageRef(item)) {
-    const page = byRoute.get(normalizeRef(item));
-    if (!page) {
-      return null;
-    }
-    return {
-      badge: page.meta.sidebar.badge,
-      deprecated: page.meta.deprecated || undefined,
-      description: page.description,
-      icon: sidebarIcon(page),
-      kind: "page",
-      label: page.meta.sidebar.label ?? page.title,
-      pageId: page.id,
-      route: page.route
-    };
-  }
-  if (item.root) {
-    const page = byRoute.get(normalizeRef(item.root));
-    return {
-      badge: item.badge,
-      deprecated: page?.meta.deprecated || undefined,
-      icon: item.icon,
-      kind: "page",
-      label: item.label,
-      pageId: page?.id ?? "",
-      route: page?.route ?? withBasePath(basePath, normalizeRef(item.root))
-    };
-  }
-  if (item.href) {
-    return {
-      badge: item.badge,
-      icon: item.icon,
-      kind: "page",
-      label: item.label,
-      pageId: "",
-      route: withBasePath(basePath, item.href)
-    };
-  }
-  return null;
-};
-var buildConfigSidebar = (items, byRoute, display, basePath) => {
-  const nodes = [];
-  for (const item of items) {
-    if (!isPageRef(item) && item.items) {
-      nodes.push({
-        badge: item.badge,
-        children: buildConfigSidebar(item.items, byRoute, display, basePath),
-        collapsed: item.collapsed,
-        directory: item.directory,
-        display: item.display ?? display,
-        icon: item.icon,
-        kind: "group",
-        label: item.label,
-        route: routeForRef(item.root, byRoute, basePath)
-      });
-      continue;
-    }
-    const node = configItemToNode(item, byRoute, basePath);
-    if (node) {
-      nodes.push(node);
-    }
-  }
-  return nodes;
-};
-var resolveTabHref = (sidebar, path, extraRoutes, basePath) => {
-  if (extraRoutes.has(path)) {
-    return path;
-  }
-  let first;
-  const walk = (nodes) => {
-    for (const node of nodes) {
-      const { route } = node;
-      if (route === path) {
-        return true;
-      }
-      if (first === undefined && route !== undefined && route.startsWith(`${path}/`)) {
-        first = route;
-      }
-      if (node.kind === "group" && walk(node.children)) {
-        return true;
-      }
-    }
-    return false;
-  };
-  if (walk(sidebar)) {
-    return path;
-  }
-  const bare = stripBasePath(basePath, path);
-  return extraRoutes.has(bare) ? bare : first ?? path;
-};
-var withTabHrefs = (tabs, sidebar, extraRoutes, basePath) => tabs.map((tab) => {
-  const href = tab.href ?? resolveTabHref(sidebar, tab.path, extraRoutes, basePath);
-  return href === tab.path ? tab : { ...tab, href };
-});
-var rebaseNavChrome = (basePath, options) => {
-  const actions = options.actions ?? [];
-  const cta = options.cta ?? null;
-  const featured = options.featured ?? [];
-  const selectors = options.selectors ?? [];
-  const tabs = options.tabs ?? [];
-  if (!basePath) {
-    return { actions, cta, featured, selectors, tabs };
-  }
-  const rebaseHref = (item) => ({
-    ...item,
-    href: withBasePath(basePath, item.href)
-  });
-  const rebasePath = (item) => ({
-    ...item,
-    path: withBasePath(basePath, item.path)
-  });
-  return {
-    actions: actions.map(rebaseHref),
-    cta: cta ? rebaseHref(cta) : null,
-    featured: featured.map(rebaseHref),
-    selectors: selectors.map((selector) => ({
-      ...selector,
-      items: selector.items.map(rebasePath)
-    })),
-    tabs: tabs.map((tab) => {
-      const rebased = {
-        ...tab,
-        items: tab.items?.map(rebasePath),
-        path: withBasePath(basePath, tab.path)
-      };
-      if (tab.href) {
-        rebased.href = withBasePath(basePath, tab.href);
-      }
-      return rebased;
-    })
-  };
-};
-var buildNavigation = (pages, options) => {
-  const basePath = options.basePath ?? "";
-  const display = options.display ?? "flat";
-  const metaPrefix = options.metaPrefix ?? "";
-  const sharedMetaPrefix = options.sharedMetaPrefix ?? "";
-  const sharedFolderMeta = options.sharedFolderMeta ?? new Map;
-  const extraRoutes = options.extraRoutes ?? new Set;
-  const { actions, cta, featured, selectors, tabs } = rebaseNavChrome(basePath, options);
-  const byRoute = new Map(pages.map((page) => [
-    options.refByLogical ? page.translationKey : page.route,
-    page
-  ]));
-  if (basePath && !options.refByLogical) {
-    for (const page of pages) {
-      const bare = stripBasePath(basePath, page.route);
-      if (!byRoute.has(bare)) {
-        byRoute.set(bare, page);
-      }
-    }
-  }
-  const rootTabPath = withBasePath(basePath, options.localizedRoot ?? "/");
-  const diagnostics = options.diagnostics ?? [];
-  diagnostics.push(...sidebarDisplayIgnoredDiagnostics(pages, Boolean(options.sidebar)));
-  if (options.sidebar) {
-    const sidebar = buildConfigSidebar(options.sidebar, byRoute, display, basePath);
-    return {
-      actions,
-      cta,
-      featured,
-      root: rootTabPath,
-      selectors,
-      sidebar,
-      tabs: withTabHrefs(tabs, sidebar, extraRoutes, basePath)
-    };
-  }
-  const sidebar = buildFileSystemSidebar(pages, options.folderMeta, sharedFolderMeta, metaPrefix, sharedMetaPrefix, display, new Set(tabs.flatMap((tab) => isRootTab(tab, rootTabPath) ? [] : [tab.path])), diagnostics);
-  return {
-    actions,
-    cta,
-    featured,
-    root: rootTabPath,
-    selectors,
-    sidebar,
-    tabs: withTabHrefs(tabs, sidebar, extraRoutes, basePath)
-  };
-};
-
 // src/core/graph.ts
 var collectRoutes = (pages) => {
   const routes = new Map;
@@ -953,7 +560,7 @@ var localePagesFor = (code, real, fallback, fallbackByKey, i18n, basePath) => {
         ...source,
         fallback: true,
         locale: code,
-        route: withBasePath(basePath, localizeRoute(key, code, i18n))
+        route: mountBasePath(basePath, localizeRoute(key, code, i18n))
       });
     }
   }
@@ -966,6 +573,19 @@ var resolveLabel = (label, locale, defaultLocale) => {
   }
   return label[locale] ?? (defaultLocale === undefined ? undefined : label[defaultLocale]) ?? Object.values(label)[0] ?? "";
 };
+var localizeSidebarHrefs = (items, localize) => items.map((item) => {
+  if (isPageRef(item)) {
+    return item;
+  }
+  const localized = { ...item };
+  if (item.href !== undefined) {
+    localized.href = localize(item.href);
+  }
+  if (item.items) {
+    localized.items = localizeSidebarHrefs(item.items, localize);
+  }
+  return localized;
+});
 var resolveTabLabels = (tabs, locale, defaultLocale) => (tabs ?? []).map((tab) => ({
   ...tab,
   items: tab.items?.map((item) => ({
@@ -974,6 +594,7 @@ var resolveTabLabels = (tabs, locale, defaultLocale) => (tabs ?? []).map((tab) =
   })),
   label: resolveLabel(tab.label, 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 ?? "";
   const real = pages.filter((page) => page.locale === code);
@@ -1009,12 +630,15 @@ var buildLocaleNavigation = (code, pages, fallback, fallbackByKey, options, i18n
     }
     return localized;
   });
-  const localeDir = i18n.parser === "dir" && code !== i18n.defaultLocale ? code : "";
+  const localeDirOf = (locale) => i18n.parser === "dir" && locale !== i18n.defaultLocale ? locale : "";
+  const localeDir = localeDirOf(code);
+  const fallbackMetaPrefix = fallback && code !== fallback ? [version, localeDirOf(fallback)].filter(Boolean).join("/") : undefined;
   const localizeHref = (item) => ({
     ...item,
     href: localizeServed(item.href, false)
   });
   const { actions, cta, featured } = options.navigation;
+  const sidebarItems = options.navigation.sidebar.items;
   const navigation = buildNavigation(localePages, {
     actions: actions?.map(localizeHref),
     basePath,
@@ -1022,6 +646,7 @@ var buildLocaleNavigation = (code, pages, fallback, fallbackByKey, options, i18n
     diagnostics,
     display: options.navigation.sidebar.display,
     extraRoutes: options.extraRoutes,
+    fallbackMetaPrefix,
     featured: featured?.map(localizeHref),
     folderMeta: options.folderMeta,
     localizedRoot: localizeRoute(versionizeRoute("/", version), code, i18n),
@@ -1030,10 +655,19 @@ var buildLocaleNavigation = (code, pages, fallback, fallbackByKey, options, i18n
     selectors: options.navigation.selectors,
     sharedFolderMeta: options.sharedFolderMeta,
     sharedMetaPrefix: version,
-    sidebar: version ? undefined : options.navigation.sidebar.items,
+    sidebar: version || !sidebarItems ? undefined : localizeSidebarHrefs(sidebarItems, (href) => localizeServed(href, false)),
+    tabRoot: localizeRoute("/", code, i18n),
     tabs
   });
-  return options.brandHref === undefined ? navigation : { ...navigation, brandHref: localizeServed(options.brandHref, false) };
+  const localizedBrand = (href) => {
+    const localized = localizeServed(href, false);
+    return localized === href ? localized : withBasePath(basePath, localized);
+  };
+  const branded = options.brandHref === undefined ? navigation : { ...navigation, brandHref: localizedBrand(options.brandHref) };
+  return options.bannerHref === undefined ? branded : {
+    ...branded,
+    bannerHref: mountConfiguredLink(localizeServed(options.bannerHref, false), basePath, extraRoutes)
+  };
 };
 var buildI18nNavigation = (pages, options, i18n, diagnostics, version = "") => {
   const fallback = resolveFallbackLocale(i18n);
@@ -1088,6 +722,7 @@ var buildVersionNavigation = (id, versionPages, options, diagnostics) => {
       selectors: options.navigation.selectors,
       sharedFolderMeta: options.sharedFolderMeta,
       sharedMetaPrefix: id,
+      tabRoot: "/",
       tabs: resolveTabLabels(options.navigation.tabs, "")
     })
   };
@@ -1115,12 +750,24 @@ var buildContentGraph = (pages, options) => {
       sidebar: options.navigation.sidebar.items,
       tabs: resolveTabLabels(options.navigation.tabs, "")
     });
+    if (options.bannerHref !== undefined) {
+      navigation = {
+        ...navigation,
+        bannerHref: mountConfiguredLink(options.bannerHref, options.basePath ?? "", options.extraRoutes ?? new Set)
+      };
+    }
   }
   const navigationByVersion = {};
   for (const { id } of options.versions?.archived ?? []) {
     navigationByVersion[id] = buildVersionNavigation(id, pages.filter((page) => page.version === id), options, diagnostics);
   }
   diagnostics.push(...validateNavIcons(navigation), ...validateNavStructure(navigation, currentPages));
+  const sidebarItems = options.navigation.sidebar.items;
+  if (sidebarItems) {
+    const byRef = pagesByRef(currentPages, options.basePath ?? "", Boolean(i18n));
+    const extraRoutes = options.extraRoutes ?? new Set;
+    diagnostics.push(...validateSidebarItems(sidebarItems, (route) => byRef.has(route) || extraRoutes.has(route)));
+  }
   return {
     diagnostics,
     navigation,
@@ -1133,7 +780,8 @@ var buildContentGraph = (pages, options) => {
 
 // src/core/last-modified.ts
 import { execFileSync } from "node:child_process";
-import { relative } from "pathe";
+import { realpathSync } from "node:fs";
+import { normalize as normalize2, relative } from "pathe";
 var GIT_LOCATION_VARS = new Set([
   "GIT_COMMON_DIR",
   "GIT_DIR",
@@ -1157,6 +805,13 @@ var parseGitLog = (output) => {
   }
   return times;
 };
+var realPath = (path) => {
+  try {
+    return normalize2(realpathSync.native(path));
+  } catch {
+    return path;
+  }
+};
 var gitRepositoryRoot = (root) => {
   try {
     return execFileSync("git", ["-C", root, "rev-parse", "--show-toplevel"], { encoding: "utf-8", env: gitEnv(), stdio: ["ignore", "pipe", "ignore"] }).trim();
@@ -1172,6 +827,7 @@ var gitLastModifiedTimes = (root, contentRoots, sourcePaths, repositoryRoot) =>
   if (gitRoot === null) {
     return new Map;
   }
+  const top = realPath(gitRoot);
   try {
     const output = execFileSync("git", [
       "-C",
@@ -1182,12 +838,12 @@ var gitLastModifiedTimes = (root, contentRoots, sourcePaths, repositoryRoot) =>
       "--format=%x00%cI",
       "--name-only",
       "--",
-      ...contentRoots
+      ...contentRoots.map(realPath)
     ], { encoding: "utf-8", env: gitEnv(), maxBuffer: 256 * 1024 * 1024 });
     const byRepoPath = parseGitLog(output);
     const result = new Map;
     for (const sourcePath of sourcePaths) {
-      const iso = byRepoPath.get(relative(gitRoot, sourcePath));
+      const iso = byRepoPath.get(relative(top, realPath(sourcePath)));
       if (iso) {
         result.set(sourcePath, iso);
       }
@@ -1224,7 +880,7 @@ var lastModifiedShallowWarning = (root, undatedCount) => {
 
 // src/core/meta.ts
 import { basename, dirname, relative as relative2 } from "pathe";
-import { glob } from "tinyglobby";
+import { glob, isDynamicPattern } from "tinyglobby";
 var META_FILES = [
   "**/meta.ts",
   "**/meta.js",
@@ -1235,6 +891,34 @@ var META_FILES = [
 ];
 var isMetaFactory = (mod) => typeof mod === "function";
 var resolveMeta = async (mod) => isMetaFactory(mod) ? await mod() : mod;
+var globBase = (pattern) => {
+  const literal = [];
+  for (const segment of pattern.split("/").slice(0, -1)) {
+    if (isDynamicPattern(segment)) {
+      break;
+    }
+    if (segment !== "" && segment !== ".") {
+      literal.push(segment);
+    }
+  }
+  return literal.join("/");
+};
+var onPathOf = (dir, base) => dir === base || base === "" || dir === "" || dir.startsWith(`${base}/`) || base.startsWith(`${dir}/`);
+var withinInclude = (dir, include) => include === undefined || include.some((pattern) => !pattern.startsWith("!") && onPathOf(dir, globBase(pattern)));
+var findFolderMetaFiles = async (source, patterns = META_FILES) => {
+  const found = await glob([...patterns], {
+    absolute: true,
+    cwd: source.root,
+    ignore: [
+      ...source.exclude ?? [],
+      "**/node_modules/**",
+      "**/.blume/**",
+      "**/dist/**"
+    ],
+    onlyFiles: true
+  });
+  return found.filter((file) => withinInclude(relative2(source.root, dirname(file)), source.include));
+};
 var metaKeyFor = (prefix, dir) => {
   const clean = prefix ? trimChar(prefix, "/") : "";
   if (!clean) {
@@ -1244,19 +928,14 @@ var metaKeyFor = (prefix, dir) => {
 };
 var discoverFolderMeta = async (sources, options = {}) => {
   const list = Array.isArray(sources) ? sources : [{ root: sources }];
-  const localeDirs = new Set(options.localeDirs);
+  const localeDirs = new Map((options.localeDirs ?? []).map((code) => [code.toLowerCase(), code]));
   const versionDirs = new Set(options.versionDirs);
   const load = createModuleLoader();
   const meta = new Map;
   const shared = new Map;
   const diagnostics = [];
   const perSource = await Promise.all(list.map(async (source) => {
-    const files = await glob(META_FILES, {
-      absolute: true,
-      cwd: source.root,
-      ignore: ["**/node_modules/**", "**/.blume/**", "**/dist/**"],
-      onlyFiles: true
-    });
+    const files = await findFolderMetaFiles(source);
     const loaded = await Promise.all(files.map(async (file) => {
       try {
         return {
@@ -1277,7 +956,7 @@ var discoverFolderMeta = async (sources, options = {}) => {
       const version = head && versionDirs.has(head) ? head : "";
       const afterVersion = version ? tail : [head ?? "", ...tail];
       const [localeHead, ...localeTail] = afterVersion;
-      const locale = localeHead && localeDirs.has(localeHead) ? localeHead : "";
+      const locale = localeHead ? localeDirs.get(localeHead.toLowerCase()) ?? "" : "";
       const rest = (locale ? localeTail : afterVersion).filter(Boolean).join("/");
       const key = [version, locale, metaKeyFor(source.prefix, rest)].filter(Boolean).join("/");
       if (!entry.ok) {
@@ -1397,30 +1076,31 @@ var embeddedEntry = (node, options) => {
   }
   return unsupported(`Contentful embedded entry${contentType ? `: ${contentType}` : ""}`, writesMdx(options.serializers));
 };
-var renderInlines = (nodes, options) => nodes.map((node) => renderInlineNode(node, options)).join("");
-var renderInlineNode = (node, options) => {
+var inlineParts = (nodes, options) => nodes.flatMap((node) => inlineNodeParts(node, options));
+var inlineNodeParts = (node, options) => {
   switch (asString(node.nodeType)) {
     case "text": {
-      return renderInline(asString(node.value) ?? "", marksOf(node));
+      return [{ marks: marksOf(node), text: asString(node.value) ?? "" }];
     }
     case "hyperlink": {
-      return renderLink(renderInlines(children(node), options), asString(getPath(node, "data.uri")));
+      return linkParts(inlineParts(children(node), options), asString(getPath(node, "data.uri")));
     }
     case "asset-hyperlink": {
-      return renderLink(renderInlines(children(node), options), linkedAsset(node, options)?.url);
+      return linkParts(inlineParts(children(node), options), linkedAsset(node, options)?.url);
     }
     case "embedded-entry-inline": {
-      return embeddedEntry(node, options);
+      return [{ markdown: embeddedEntry(node, options) }];
     }
     default: {
-      return renderInlines(children(node), options);
+      return inlineParts(children(node), options);
     }
   }
 };
+var blockText = (node, options) => guardBlockStart(renderInline(inlineParts(children(node), options)));
 var renderList = (items, marker, options) => items.map((item, index) => listItem(marker(index), children(item).map((child) => renderBlock(child, options)).filter((block) => block !== "").join(`
 `))).join(`
 `);
-var cellText = (cell, options) => children(cell).map((paragraph) => renderInlines(children(paragraph), options)).join(" ").replaceAll(CELL_BREAK, " ").replaceAll(CELL_PIPE, String.raw`\|`);
+var cellText = (cell, options) => children(cell).map((paragraph) => blockText(paragraph, options)).join(" ").replaceAll(CELL_BREAK, " ").replaceAll(CELL_PIPE, String.raw`\|`);
 var tableRow = (cells) => `| ${cells.join(" | ")} |`;
 var renderTable = (node, options) => {
   const rows = children(node).map((row) => children(row).map((cell) => cellText(cell, options)));
@@ -1439,11 +1119,11 @@ var renderBlock = (node, options) => {
   const type = asString(node.nodeType) ?? "";
   const heading = HEADING.exec(type)?.groups?.level;
   if (heading) {
-    return `${headingPrefix(Number(heading))}${renderInlines(children(node), options)}`;
+    return `${headingPrefix(Number(heading))}${blockText(node, options)}`;
   }
   switch (type) {
     case "paragraph": {
-      return renderInlines(children(node), options);
+      return blockText(node, options);
     }
     case "blockquote": {
       return blockquote(joinBlocks(children(node).map((child) => renderBlock(child, options))));
@@ -1480,6 +1160,7 @@ var remoteSource = (options, ctx) => {
   const cache = snapshotCache(ctx?.cacheDir ?? join(".blume", "cache", options.name));
   let snapshot = new Map;
   const load = async (refresh = ctx?.refresh ?? true) => {
+    options.assertConfigured?.();
     const result = await loadWithCache(options.name, cache, options.fetchEntries, refresh);
     snapshot = new Map(result.entries.map((entry) => [entry.ref, entry]));
     return result;
@@ -1498,7 +1179,8 @@ var remoteSource = (options, ctx) => {
     prefix: options.prefix,
     read,
     staged: true,
-    watch: options.pollInterval ? pollingWatch(() => load(true), options.pollInterval, () => load()) : undefined
+    watch: options.pollInterval ? pollingWatch(() => load(true), options.pollInterval, () => load()) : undefined,
+    withContext: options.withContext
   };
 };
 var stagedEntry = (slug, data, markdown, lastModified, format = "md") => {
@@ -1552,8 +1234,8 @@ var documentEntry = (doc, fields, id, lower, draft = false, lowersToMdx = false)
   let markdown = "";
   let format = "md";
   if (isStringValue2(body)) {
-    markdown = `${body.trimEnd()}
-`;
+    markdown = neutralizeUnsafeLinks(`${body.trimEnd()}
+`);
   } else if (body !== undefined) {
     markdown = lower(body);
     format = lowersToMdx ? "mdx" : "md";
@@ -1588,14 +1270,20 @@ var contentfulSource = (options, ctx) => {
       serializers: options.serializers
     }) : "", false, writesMdx(options.serializers));
   };
-  const fetchEntries = async () => {
-    const preview = ctx?.preview ?? false;
-    const deliveryToken = options.token ?? process.env.CONTENTFUL_ACCESS_TOKEN;
-    const previewToken = options.previewToken ?? process.env.CONTENTFUL_PREVIEW_TOKEN;
-    if (preview && !previewToken) {
-      throw new Error("Contentful --preview needs a Preview API token: set previewToken or CONTENTFUL_PREVIEW_TOKEN.");
+  const preview = ctx?.preview ?? false;
+  const previewToken = () => options.previewToken ?? process.env.CONTENTFUL_PREVIEW_TOKEN;
+  const assertConfigured = () => {
+    if (preview && !previewToken()) {
+      throw new BlumeError({
+        code: "BLUME_SOURCE_MISCONFIGURED",
+        message: `Source "${options.name}": Contentful --preview needs a Preview API token.`,
+        severity: "error",
+        suggestion: "Set previewToken on contentfulSource, or the CONTENTFUL_PREVIEW_TOKEN environment variable."
+      });
     }
-    const token = preview ? previewToken : deliveryToken;
+  };
+  const fetchEntries = async () => {
+    const token = preview ? previewToken() : options.token ?? process.env.CONTENTFUL_ACCESS_TOKEN;
     const client = {
       fetchImpl: options.fetchImpl,
       headers: token ? { authorization: `Bearer ${token}` } : {}
@@ -1630,17 +1318,19 @@ var contentfulSource = (options, ctx) => {
     return entries;
   };
   return remoteSource({
+    assertConfigured,
     fetchEntries,
     name: options.name,
     pollInterval: options.pollInterval,
-    prefix: options.prefix
+    prefix: options.prefix,
+    withContext: (next) => contentfulSource(options, next)
   }, ctx);
 };
 
 // src/core/sources/filesystem.ts
 import { existsSync, watch as fsWatch } from "node:fs";
 import { readFile } from "node:fs/promises";
-import { extname as extname2, isAbsolute, join as join2, relative as relative3, resolve } from "pathe";
+import { extname, isAbsolute, join as join2, relative as relative3, resolve } from "pathe";
 import { glob as glob2 } from "tinyglobby";
 var filesystemSource = (options) => {
   const contentRoot = isAbsolute(options.root) ? options.root : join2(resolve(options.projectRoot), options.root);
@@ -1652,9 +1342,19 @@ var filesystemSource = (options) => {
       onlyFiles: true
     });
     files.sort();
-    const entries = await Promise.all(files.map(async (file) => {
+    const diagnostics = [];
+    const loadable = [];
+    for (const file of files) {
+      const unloadable = unloadablePathDiagnostic(relative3(contentRoot, file), file);
+      if (unloadable) {
+        diagnostics.push(unloadable);
+      } else {
+        loadable.push(file);
+      }
+    }
+    const entries = await Promise.all(loadable.map(async (file) => {
       const source = await readFile(file, "utf-8");
-      const ext = extname2(file).toLowerCase();
+      const ext = extname(file).toLowerCase();
       const format = ext === ".mdx" ? "mdx" : "md";
       const parsed = frontmatter_default(source);
       return {
@@ -1665,7 +1365,7 @@ var filesystemSource = (options) => {
         sourcePath: file
       };
     }));
-    return { diagnostics: [], entries };
+    return { diagnostics, entries };
   };
   const validate = () => {
     if (!existsSync(contentRoot)) {
@@ -1674,7 +1374,7 @@ var filesystemSource = (options) => {
         file: contentRoot,
         message: `Content root not found: ${options.root}`,
         severity: "error",
-        suggestion: `Create a "${options.root}" folder with at least one .md or .mdx file, or set content.root in blume.config.ts.`
+        suggestion: `Create a "${options.root}" folder with at least one .md or .mdx file, or point Blume at your docs folder: content.root in blume.config.ts, or the filesystem() source's root when you list content.sources.`
       });
     }
   };
@@ -1691,6 +1391,8 @@ var filesystemSource = (options) => {
   };
   return {
     contentRoot,
+    exclude: options.exclude,
+    include: options.include,
     load,
     name: options.name,
     prefix: options.prefix,
@@ -1704,7 +1406,7 @@ var filesystemSource = (options) => {
 // src/core/sources/github-releases.ts
 import { fromMarkdown } from "mdast-util-from-markdown";
 import { gfmFromMarkdown } from "mdast-util-gfm";
-import { toString as mdastToString } from "mdast-util-to-string";
+import { toString as mdastToString2 } from "mdast-util-to-string";
 import { gfm } from "micromark-extension-gfm";
 import stringWidth from "string-width";
 var DEFAULT_LIMIT = 100;
@@ -1723,7 +1425,7 @@ var releaseDescription = (body) => {
     extensions: [gfm()],
     mdastExtensions: [gfmFromMarkdown()]
   });
-  const text = tree.children.filter((node) => !NON_PROSE.has(node.type)).map((node) => mdastToString(node, { includeHtml: false, includeImageAlt: false })).join(" ").replaceAll(WHITESPACE, " ").trim();
+  const text = tree.children.filter((node) => !NON_PROSE.has(node.type)).map((node) => mdastToString2(node, { includeHtml: false, includeImageAlt: false })).join(" ").replaceAll(WHITESPACE, " ").trim();
   if (!text) {
     return;
   }
@@ -1763,6 +1465,62 @@ var liftHeadings = (body) => {
   }
   return lifted;
 };
+var WEB_PROTOCOL = /^https?:$/u;
+var TITLE_SPECIALS = /["\\]/gu;
+var webOrigin = (site) => {
+  const parsed = site ? URL.parse(site) : null;
+  return parsed && WEB_PROTOCOL.test(parsed.protocol) ? parsed.origin : null;
+};
+var titleSuffix = (title) => title ? ` "${title.replaceAll(TITLE_SPECIALS, String.raw`\$&`)}"` : "";
+var rewrittenLink = (markdown, node, path) => {
+  const target = `${destination(path)}${titleSuffix(node.title)}`;
+  if (node.type === "definition") {
+    return `[${node.label ?? node.identifier}]: ${target}`;
+  }
+  const start = node.position?.start.offset ?? 0;
+  if (markdown[start] !== "[") {
+    return `[${escapeMarkdownText(mdastToString2(node))}](${target})`;
+  }
+  const first = node.children.at(0)?.position?.start.offset ?? start + 1;
+  const last = node.children.at(-1)?.position?.end.offset ?? first;
+  return `[${markdown.slice(first, last)}](${target})`;
+};
+var relativizeOwnLinks = (markdown, site) => {
+  const origin = webOrigin(site);
+  if (!origin) {
+    return markdown;
+  }
+  const spans = [];
+  const visit = (node) => {
+    if (node.type === "link" || node.type === "definition") {
+      const parsed = URL.parse(node.url);
+      if (parsed?.origin === origin) {
+        spans.push({
+          end: node.position?.end.offset ?? 0,
+          start: node.position?.start.offset ?? 0,
+          text: rewrittenLink(markdown, node, `${parsed.pathname}${parsed.search}${parsed.hash}`)
+        });
+        return;
+      }
+    }
+    if ("children" in node) {
+      for (const child of node.children) {
+        visit(child);
+      }
+    }
+  };
+  visit(fromMarkdown(markdown, {
+    extensions: [gfm()],
+    mdastExtensions: [gfmFromMarkdown()]
+  }));
+  let out = "";
+  let cursor = 0;
+  for (const span of spans) {
+    out += markdown.slice(cursor, span.start) + span.text;
+    cursor = span.end;
+  }
+  return out + markdown.slice(cursor);
+};
 var slugifyTag = (tag) => tag.toLowerCase().replaceAll(NON_SLUG, "-").replaceAll(EDGE_DASHES, "");
 var githubHeaders = () => {
   const headers = new Headers({ Accept: "application/vnd.github+json" });
@@ -1772,14 +1530,14 @@ var githubHeaders = () => {
   }
   return headers;
 };
-var releaseToEntry = (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 body = liftHeadings(neutralizeUnsafeLinks((release.body ?? "").replaceAll(`\r
+  const body = liftHeadings(relativizeOwnLinks(neutralizeUnsafeLinks((release.body ?? "").replaceAll(`\r
 `, `
-`)).trim());
+`)).trim(), site));
   const description = releaseDescription(body);
   const data = {
     changelog: { category, version },
@@ -1813,11 +1571,21 @@ var githubReleasesSource = (options, ctx) => {
   const include = (release) => (options.drafts || !release.draft) && (options.prereleases || !release.prerelease);
   const fetchPage = async (page) => {
     const url = `${base}/repos/${options.owner}/${options.repo}/releases?per_page=${PER_PAGE}&page=${page}`;
-    const res = await doFetch(url, { headers: githubHeaders() });
-    if (!res.ok) {
-      throw new Error(`${url} -> ${res.status}`);
+    try {
+      const res = await doFetch(url, {
+        headers: githubHeaders(),
+        signal: AbortSignal.timeout(REMOTE_TIMEOUT_MS)
+      });
+      if (!res.ok) {
+        throw new Error(`${url} -> ${res.status}`);
+      }
+      return await res.json();
+    } catch (error) {
+      if (error instanceof DOMException && error.name === "TimeoutError") {
+        throw new Error(`${url} did not respond within ${REMOTE_TIMEOUT_MS / 1000}s`, { cause: error });
+      }
+      throw error;
     }
-    return await res.json();
   };
   const fetchReleases = async () => {
     const collected = [];
@@ -1836,7 +1604,7 @@ var githubReleasesSource = (options, ctx) => {
     try {
       const result = await loadWithCache(options.name, cache, async () => {
         const releases = await fetchReleases();
-        return releases.map(releaseToEntry);
+        return releases.map((release) => releaseToEntry(release, options.site));
       }, refresh);
       snapshot = new Map(result.entries.map((entry) => [entry.ref, entry]));
       return result;
@@ -1870,7 +1638,8 @@ var githubReleasesSource = (options, ctx) => {
     prefix: options.prefix,
     read,
     staged: true,
-    watch: options.pollInterval ? pollingWatch(() => load(true), options.pollInterval, () => load()) : undefined
+    watch: options.pollInterval ? pollingWatch(() => load(true), options.pollInterval, () => load()) : undefined,
+    withContext: (next) => githubReleasesSource(options, next)
   };
 };
 
@@ -1890,15 +1659,29 @@ var githubHeaders2 = (url) => {
   }
   return GITHUB_HOSTS.has(host) ? { authorization: `Bearer ${token}` } : {};
 };
+var fetchText = async (url, doFetch) => {
+  try {
+    const res = await doFetch(url, {
+      headers: githubHeaders2(url),
+      signal: AbortSignal.timeout(REMOTE_TIMEOUT_MS)
+    });
+    if (!res.ok) {
+      throw new Error(`${url} -> ${res.status}`);
+    }
+    return await res.text();
+  } catch (error) {
+    if (error instanceof DOMException && error.name === "TimeoutError") {
+      throw new Error(`${url} did not respond within ${REMOTE_TIMEOUT_MS / 1000}s`, { cause: error });
+    }
+    throw error;
+  }
+};
 var enumerateGithub = async (github, include, doFetch) => {
   const { owner, repo, ref } = github;
   const base = github.path.replaceAll(/^\/|\/$/gu, "");
   const treeUrl = `https://api.github.com/repos/${owner}/${repo}/git/trees/${ref}?recursive=1`;
-  const res = await doFetch(treeUrl, { headers: githubHeaders2(treeUrl) });
-  if (!res.ok) {
-    throw new Error(`${treeUrl} -> ${res.status}`);
-  }
-  const body = await res.json();
+  const text = await fetchText(treeUrl, doFetch);
+  const body = JSON.parse(text);
   const prefix = base ? `${base}/` : "";
   const included = picomatch(include);
   const refs = (body.tree ?? []).flatMap((node) => {
@@ -1943,13 +1726,7 @@ var mdxRemoteSource = (options, ctx) => {
     return { refs, truncated: false };
   };
   const fetchEntry = async (item) => {
-    const res = await doFetch(item.fetchUrl, {
-      headers: githubHeaders2(item.fetchUrl)
-    });
-    if (!res.ok) {
-      throw new Error(`${item.fetchUrl} -> ${res.status}`);
-    }
-    const text = await res.text();
+    const text = await fetchText(item.fetchUrl, doFetch);
     const parsed = frontmatter_default(text);
     const format = item.ref.toLowerCase().endsWith(".mdx") ? "mdx" : "md";
     return {
@@ -1973,13 +1750,16 @@ var mdxRemoteSource = (options, ctx) => {
           severity: "warning"
         });
       }
+      const reasons = [];
       const settled = await Promise.all(refs.map(async (ref) => {
         try {
           return await fetchEntry(ref);
         } catch (error) {
+          const reason = error.message;
+          reasons.push(reason);
           skipped.push({
             code: "BLUME_SOURCE_FETCH_FAILED",
-            message: `Source "${options.name}" skipped "${ref.ref}" (${error.message}); the rest were imported.`,
+            message: `Source "${options.name}" skipped "${ref.ref}" (${reason}); the rest were imported.`,
             severity: "warning"
           });
           return null;
@@ -1988,7 +1768,7 @@ var mdxRemoteSource = (options, ctx) => {
       const entries = settled.filter((entry) => entry !== null);
       if (refs.length > 0 && entries.length === 0) {
         skipped.length = 0;
-        throw new Error(`all ${refs.length} remote file(s) failed to fetch`);
+        throw new Error(`all ${refs.length} remote file(s) failed to fetch (${reasons[0]})`);
       }
       return entries;
     }, refresh);
@@ -2010,10 +1790,12 @@ var mdxRemoteSource = (options, ctx) => {
   return {
     load,
     name: options.name,
+    orderedNames: true,
     prefix: options.prefix,
     read,
     staged: true,
-    watch: options.pollInterval ? pollingWatch(() => load(true), options.pollInterval, () => load()) : undefined
+    watch: options.pollInterval ? pollingWatch(() => load(true), options.pollInterval, () => load()) : undefined,
+    withContext: (next) => mdxRemoteSource(options, next)
   };
 };
 
@@ -2032,34 +1814,45 @@ import {
   rm,
   writeFile
 } from "node:fs/promises";
-import { extname as extname3, join as join3 } from "pathe";
-var MD_IMAGE = /!\[(?<alt>[^\]]*)\]\((?<url>[^)\s]+)\)/gu;
+import { extname as extname2, join as join3 } from "pathe";
+var MD_IMAGE = /!\[(?<alt>(?:\\.|[^\\\]])*)\]\((?:<(?<pointy>(?:\\.|[^\\<>\n])*)>|(?<bare>(?:\\.|[^\\\s)])+))\)/gu;
+var DESTINATION_ESCAPE = /\\(?<char>[!-/:-@[-`{-~])/gu;
 var HTML_VIDEO_SRC = /(?<open><video\b[^>]*?\ssrc=")(?<url>[^"]+)(?<close>")/gu;
 var REMOTE = /^https?:\/\//u;
-var SAFE_EXT = /^\.[a-z0-9]+$/iu;
 var CODE_FENCE_BLOCK = /^(?<fence>`{3,}|~{3,})[^\n]*\n[\s\S]*?^\k<fence>[^\n]*(?=\n|$)/gmu;
 var FENCE_TOKEN = /\u0000blume-fence-(?<index>\d+)\u0000/gu;
 var EXT_BY_MIME = new Map([
+  ["image/apng", ".apng"],
   ["image/avif", ".avif"],
+  ["image/bmp", ".bmp"],
   ["image/gif", ".gif"],
   ["image/jpeg", ".jpg"],
+  ["image/jpg", ".jpg"],
   ["image/png", ".png"],
   ["image/svg+xml", ".svg"],
+  ["image/tiff", ".tiff"],
+  ["image/vnd.microsoft.icon", ".ico"],
   ["image/webp", ".webp"],
+  ["image/x-icon", ".ico"],
   ["video/mp4", ".mp4"],
   ["video/ogg", ".ogv"],
   ["video/quicktime", ".mov"],
   ["video/webm", ".webm"]
 ]);
-var UNKNOWN_EXT = ".bin";
-var NON_MEDIA_TYPE = /^(?:text\/|application\/(?:[\w.-]+\+)?(?:json|xml|javascript))/u;
+var MEDIA_EXTS = new Set([...EXT_BY_MIME.values(), ".jpeg"]);
+var OPAQUE_TYPES = new Set([
+  "",
+  "application/octet-stream",
+  "binary/octet-stream"
+]);
 var PART_SUFFIX = ".part";
 var DEFAULT_TIMEOUT_MS = 120000;
 var extFromUrl = (url) => {
   const clean = url.split("?")[0] ?? url;
-  const ext = extname3(clean);
-  return SAFE_EXT.test(ext) ? ext.toLowerCase() : null;
+  const ext = extname2(clean).toLowerCase();
+  return MEDIA_EXTS.has(ext) ? ext : null;
 };
+var imageUrl = (pointy, bare) => (pointy ?? bare ?? "").replaceAll(DESTINATION_ESCAPE, "$<char>");
 var mediaType = (res) => res.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase() ?? "";
 var exists = async (path) => {
   try {
@@ -2076,9 +1869,16 @@ var completedFor = async (dir, stem) => {
   } catch {
     return null;
   }
-  const candidates = names.filter((name) => name.startsWith(`${stem}.`) && !name.endsWith(PART_SUFFIX));
+  const candidates = names.filter((name) => name.startsWith(stem) && MEDIA_EXTS.has(name.slice(stem.length)));
   return candidates.length === 1 ? candidates[0] ?? null : null;
 };
+var extFor = (type, urlExt) => {
+  const ext = EXT_BY_MIME.get(type) ?? (OPAQUE_TYPES.has(type) ? urlExt : null);
+  if (ext) {
+    return ext;
+  }
+  throw new Error(OPAQUE_TYPES.has(type) ? `responded with ${type || "no content type"} and its URL names no image or video file` : `responded with ${type}, not an image or video`);
+};
 var materializeAssets = async (markdown, ctx) => {
   const doFetch = ctx.fetchImpl ?? globalThis.fetch;
   const limit = ctx.limit ?? ((task) => task());
@@ -2090,21 +1890,17 @@ var materializeAssets = async (markdown, ctx) => {
     fences.push(block);
     return `\x00blume-fence-${fences.length - 1}\x00`;
   });
-  const urls = new Set;
-  for (const pattern of [MD_IMAGE, HTML_VIDEO_SRC]) {
-    for (const match of masked.matchAll(pattern)) {
-      const url = match.groups?.url;
-      if (url && REMOTE.test(url)) {
-        urls.add(url);
-      }
-    }
-  }
+  const referenced = [
+    ...[...masked.matchAll(MD_IMAGE)].map((match) => imageUrl(match.groups?.pointy, match.groups?.bare)),
+    ...[...masked.matchAll(HTML_VIDEO_SRC)].map((match) => match.groups?.url ?? "")
+  ];
+  const urls = new Set(referenced.filter((url) => REMOTE.test(url)));
   const download = async (url, stem) => {
     const urlExt = extFromUrl(url);
     if (urlExt && await exists(join3(ctx.assetsDir, `${stem}${urlExt}`))) {
       return `${stem}${urlExt}`;
     }
-    const completed = urlExt ? null : await completedFor(ctx.assetsDir, stem);
+    const completed = await completedFor(ctx.assetsDir, stem);
     if (completed) {
       return completed;
     }
@@ -2112,14 +1908,11 @@ var materializeAssets = async (markdown, ctx) => {
     if (!res.ok) {
       throw new Error(`${res.status}`);
     }
-    const type = mediaType(res);
-    if (NON_MEDIA_TYPE.test(type)) {
-      throw new Error(`responded with ${type}, not a media file`);
-    }
+    const ext = extFor(mediaType(res), urlExt);
     if (!res.body) {
       throw new Error("empty response body");
     }
-    const file = `${stem}${urlExt ?? EXT_BY_MIME.get(type) ?? UNKNOWN_EXT}`;
+    const file = `${stem}${ext}`;
     const target = join3(ctx.assetsDir, file);
     await mkdir(ctx.assetsDir, { recursive: true });
     const part = `${target}.${randomUUID()}${PART_SUFFIX}`;
@@ -2165,8 +1958,8 @@ var materializeAssets = async (markdown, ctx) => {
       });
     }
   }));
-  const rewritten = masked.replaceAll(MD_IMAGE, (match, alt, url) => {
-    const local = rewrites.get(url);
+  const rewritten = masked.replaceAll(MD_IMAGE, (match, alt, pointy, bare) => {
+    const local = rewrites.get(imageUrl(pointy, bare));
     return local ? `![${alt}](${local})` : match;
   }).replaceAll(HTML_VIDEO_SRC, (match, open, url, close) => {
     const local = rewrites.get(url);
@@ -2176,12 +1969,27 @@ var materializeAssets = async (markdown, ctx) => {
 };
 
 // src/core/sources/notion.ts
-var richToMarkdown = (rich = []) => rich.map(({ annotations = {}, href, plain_text: text }) => renderLink(renderInline(text, {
-  bold: annotations.bold,
-  code: annotations.code,
-  italic: annotations.italic,
-  strike: annotations.strikethrough
-}), href ?? undefined)).join("");
+var richToMarkdown = (rich = []) => {
+  const linked = [];
+  for (const { annotations = {}, href, plain_text: text } of rich) {
+    const run = {
+      marks: {
+        bold: annotations.bold,
+        code: annotations.code,
+        italic: annotations.italic,
+        strike: annotations.strikethrough
+      },
+      text
+    };
+    const last = linked.at(-1);
+    if (last && last.href === (href ?? undefined)) {
+      last.runs.push(run);
+    } else {
+      linked.push({ href: href ?? undefined, runs: [run] });
+    }
+  }
+  return renderInline(linked.flatMap(({ href, runs }) => linkParts(runs, href)));
+};
 var isBlockPayload = (value) => typeof value === "object";
 var payloadOf = (block) => {
   const value = block[block.type];
@@ -2202,7 +2010,8 @@ var withNotionRetry = async (call, attempt = 0) => {
     if (status !== RATE_LIMITED || attempt === MAX_RETRIES) {
       throw error;
     }
-    const retryAfter = Number(error.headers?.["retry-after"]);
+    const { headers } = error;
+    const retryAfter = Number(headers?.get?.("retry-after"));
     const wait = retryAfter > 0 ? retryAfter * SECOND_MS : BASE_DELAY_MS * 2 ** attempt * (1 + Math.random());
     await sleep(wait);
     return withNotionRetry(call, attempt + 1);
@@ -2221,6 +2030,7 @@ var LIST_BLOCKS = new Set([
 var isListItem = (block) => block !== undefined && LIST_BLOCKS.has(block.type);
 var richToPlain = (rich = []) => rich.map((node) => node.plain_text).join("");
 var jsxString = (value) => `{${JSON.stringify(value)}}`;
+var FRAME_ESCAPED = /\\(?=[<>])/gu;
 var YOUTUBE_HOST = /(?:^|\.)(?:youtube(?:-nocookie)?\.com|youtu\.be)$/u;
 var isYouTubeUrl = (url) => {
   const host = URL.parse(url)?.hostname ?? "";
@@ -2233,14 +2043,14 @@ var renderVideo = (data) => {
   }
   const caption = richToMarkdown(data.caption);
   const title = caption ? ` title=${jsxString(richToPlain(data.caption))}` : "";
-  const media = isYouTubeUrl(url) ? `<YouTube${title} url=${JSON.stringify(url)} />` : `<video controls src=${JSON.stringify(url)} />`;
-  return caption ? `<Frame caption=${jsxString(caption)}>
+  const media = isYouTubeUrl(url) ? `<YouTube${title} url=${jsxString(url)} />` : `<video controls src="${url.replaceAll('"', "%22")}" />`;
+  return caption ? `<Frame caption=${jsxString(caption.replaceAll(FRAME_ESCAPED, ""))}>
 ${media}
 </Frame>` : media;
 };
 var renderLeaf = (block) => {
   const data = payloadOf(block) ?? {};
-  const text = richToMarkdown(blockField(block));
+  const text = guardBlockStart(richToMarkdown(blockField(block)));
   switch (block.type) {
     case "paragraph": {
       return text;
@@ -2320,7 +2130,10 @@ var notionSource = (options, ctx) => {
       return render(client, await childrenOf(client, target.id));
     };
     if (block.type === "callout") {
-      const body = [richToMarkdown(blockField(block)), await children(block)].filter(Boolean).join(`
+      const body = [
+        guardBlockStart(richToMarkdown(blockField(block))),
+        await children(block)
+      ].filter(Boolean).join(`
 
 `);
       return `<Callout>
@@ -2420,7 +2233,7 @@ ${nested}`;
       data.sidebar = { order };
     }
     const slugProp = richToPlain(page.properties[props.slug ?? "Slug"]?.rich_text);
-    const slug = slugifyPath(slugProp || title) || page.id;
+    const slug = (slugProp ? slugifyPath(slugProp) : slugify(title.replaceAll("/", "-"))) || page.id;
     return { data, slug };
   };
   const toEntry = async (client, page) => {
@@ -2494,7 +2307,8 @@ ${nested}`;
     prefix: options.prefix,
     read,
     staged: true,
-    watch: options.pollInterval ? pollingWatch(() => load(true), options.pollInterval, () => load()) : undefined
+    watch: options.pollInterval ? pollingWatch(() => load(true), options.pollInterval, () => load()) : undefined,
+    withContext: (next) => notionSource(options, next)
   };
 };
 
@@ -2741,7 +2555,7 @@ var buildLinkIndex = (notes, options) => {
     if (cached) {
       return cached;
     }
-    const route = resolveEntryRoute({ ref: note.rel, slug: entrySlugFor(note.placement.navPath) }, ".md", isStringValue(note.data.slug) ? note.data.slug : undefined, options);
+    const route = resolveEntryRoute({ ref: note.rel, slug: entrySlugFor(note.placement.navPath) }, ".md", isStringValue(note.data.slug) ? note.data.slug : undefined, { ...options, orderingPrefixes: true });
     const built = {
       anchors: new Map,
       locales: route.locales,
@@ -2802,11 +2616,15 @@ var noteToEntry = (pair, index, options, unresolved) => {
   const keep = keptKeysFor(note.data, options);
   const data = Object.fromEntries(Object.entries(note.data).filter(([key]) => !OBSIDIAN_NATIVE_KEYS.has(key) && (PAGE_META_KEYS.has(key) || keep.has(key))));
   const merged = title === undefined ? data : { ...data, title };
-  const text = transformBody(note.content.trim(), index, pair.self, unresolved);
+  const body = note.content.trim();
+  const text = transformBody(body, index, pair.self, unresolved);
   const raw = frontmatter_default.stringify(`${text}
 `, merged);
+  const leading = note.content.slice(0, note.content.indexOf(body));
   return {
     body: { format: "md", text },
+    bodyLineOffset: note.frontmatterLines + leading.split(`
+`).length - 1,
     data: merged,
     hash: hashText(raw),
     raw,
@@ -2818,11 +2636,13 @@ var noteToEntry = (pair, index, options, unresolved) => {
 var readNote = async (vaultDir, rel, options) => {
   const absPath = join5(vaultDir, rel);
   try {
-    const { content, data } = frontmatter_default(await readFile2(absPath, "utf-8"));
+    const file = await readFile2(absPath, "utf-8");
+    const { content, data } = frontmatter_default(file);
     return {
       absPath,
       content,
       data,
+      frontmatterLines: strippedLineOffset(file, content),
       placement: placeEntryRef(rel, ".md", options),
       rel
     };
@@ -2906,14 +2726,26 @@ var obsidianSource = (options, ctx) => {
   const vaultDir = resolve2(ctx.projectRoot, options.vault);
   const exclude = new Set([...BLUME_IGNORE_DIRS, ...options.exclude ?? []]);
   const load = async () => {
-    const files = await walkVault(vaultDir, vaultDir, exclude);
+    const skipped = [];
+    const files = [];
+    for (const rel of await walkVault(vaultDir, vaultDir, exclude)) {
+      const unloadable = unloadablePathDiagnostic(rel, join5(vaultDir, rel));
+      if (unloadable) {
+        skipped.push(unloadable);
+      } else {
+        files.push(rel);
+      }
+    }
     const read = await Promise.all(files.map((rel) => readNote(vaultDir, rel, options)));
     const notes = read.filter((note) => note !== null);
     const { index, pairs } = buildLinkIndex(notes, options);
     const unresolved = noTargets();
     const entries = pairs.map((pair) => noteToEntry(pair, index, options, unresolved));
     return {
-      diagnostics: unresolvedDiagnostics(options.name, unresolved),
+      diagnostics: [
+        ...skipped,
+        ...unresolvedDiagnostics(options.name, unresolved)
+      ],
       entries
     };
   };
@@ -2956,6 +2788,7 @@ var obsidianSource = (options, ctx) => {
     contentRoot: vaultDir,
     load,
     name: options.name,
+    orderedNames: true,
     prefix: options.prefix,
     read,
     staged: true,
@@ -2990,31 +2823,33 @@ var customBlock = (node, options) => {
   }
   return unsupported(`Lexical block${blockType ? `: ${blockType}` : ""}`, writesMdx(options.serializers));
 };
-var renderInlines2 = (nodes, options) => nodes.map((node) => renderInlineNode2(node, options)).join("");
-var renderInlineNode2 = (node, options) => {
+var inlineParts2 = (nodes, options) => nodes.flatMap((node) => inlineNodeParts2(node, options));
+var inlineNodeParts2 = (node, options) => {
   switch (typeOf(node)) {
     case "text": {
-      return renderInline(asString(node.text) ?? "", marksOf2(node));
+      return [{ marks: marksOf2(node), text: asString(node.text) ?? "" }];
     }
     case "linebreak": {
-      return `
-`;
+      return [{ markdown: `
+` }];
     }
     case "tab": {
-      return "\t";
+      return [{ markdown: "\t" }];
     }
     case "link":
     case "autolink": {
-      return renderLink(renderInlines2(children2(node), options), asString(getPath(node, "fields.url")) ?? asString(node.url));
+      return linkParts(inlineParts2(children2(node), options), asString(getPath(node, "fields.url")) ?? asString(node.url));
     }
     case "inlineBlock": {
-      return customBlock(node, options);
+      return [{ markdown: customBlock(node, options) }];
     }
     default: {
-      return renderInlines2(children2(node), options);
+      return inlineParts2(children2(node), options);
     }
   }
 };
+var inlineText = (nodes, options) => guardBlockStart(renderInline(inlineParts2(nodes, options)));
+var blockText2 = (node, options) => inlineText(children2(node), options);
 var renderUpload = (node, options) => {
   const value = asObject(node.value);
   const url = value ? asString(value.url) : undefined;
@@ -3045,7 +2880,7 @@ var renderList2 = (node, options) => {
     if (listType === "check") {
       check = item.checked === true ? "[x] " : "[ ] ";
     }
-    const line = `${check}${renderInlines2(inline, options)}`;
+    const line = `${check}${inlineText(inline, options)}`;
     items.push(listItem(lastMarker, sub ? `${line}
 ${sub}` : line));
     index += 1;
@@ -3056,14 +2891,14 @@ ${sub}` : line));
 var renderBlock2 = (node, options) => {
   switch (typeOf(node)) {
     case "paragraph": {
-      return renderInlines2(children2(node), options);
+      return blockText2(node, options);
     }
     case "heading": {
       const level = Number((asString(node.tag) ?? "h1").slice(1));
-      return `${headingPrefix(level)}${renderInlines2(children2(node), options)}`;
+      return `${headingPrefix(level)}${blockText2(node, options)}`;
     }
     case "quote": {
-      return blockquote(renderInlines2(children2(node), options));
+      return blockquote(blockText2(node, options));
     }
     case "list": {
       return renderList2(node, options);
@@ -3145,7 +2980,8 @@ var payloadSource = (options, ctx) => {
     fetchEntries,
     name: options.name,
     pollInterval: options.pollInterval,
-    prefix: options.prefix
+    prefix: options.prefix,
+    withContext: (next) => payloadSource(options, next)
   }, ctx);
 };
 
@@ -3161,47 +2997,49 @@ var HEADING_STYLES = new Map([
   ["h5", "##### "],
   ["h6", "###### "]
 ]);
-var renderSpan = (span, defs) => {
-  const isCode = span.marks?.includes("code") ?? false;
-  let text = isCode ? span.text ?? "" : escapeMarkdownText(span.text ?? "");
-  if (!span.marks || span.marks.length === 0) {
-    return text;
-  }
-  let link;
-  for (const mark of span.marks) {
-    switch (mark) {
-      case "strong": {
-        text = `**${text}**`;
-        break;
-      }
-      case "em": {
-        text = `*${text}*`;
-        break;
-      }
-      case "code": {
-        text = `\`${text}\``;
-        break;
-      }
-      case "strike-through": {
-        text = `~~${text}~~`;
-        break;
-      }
-      default: {
-        const def = defs.get(mark);
-        if (def?._type === "link") {
-          link = def;
-        }
-      }
-    }
-  }
-  return link?.href ? `[${text}](${link.href})` : text;
+var spanRun = (span) => {
+  const marks = span.marks ?? [];
+  return {
+    marks: {
+      bold: marks.includes("strong"),
+      code: marks.includes("code"),
+      italic: marks.includes("em"),
+      strike: marks.includes("strike-through")
+    },
+    text: span.text ?? ""
+  };
 };
 var renderChildren = (block) => {
   const defs = new Map((block.markDefs ?? []).map((def) => [def._key, def]));
-  return (block.children ?? []).map((span) => renderSpan(span, defs)).join("");
+  const linked = [];
+  for (const span of block.children ?? []) {
+    const link = (span.marks ?? []).map((mark) => defs.get(mark)).findLast((def) => def?._type === "link");
+    const last = linked.at(-1);
+    if (last && last.link === link) {
+      last.runs.push(spanRun(span));
+    } else {
+      linked.push({ link, runs: [spanRun(span)] });
+    }
+  }
+  return guardBlockStart(renderInline(linked.flatMap(({ link, runs }) => linkParts(runs, link?.href))));
 };
 var isAltText = (value) => typeof value === "string";
-var renderBlock3 = (block, options) => {
+var listMarker = (block) => block.listItem === "number" ? "1." : "-";
+var listIndents = (blocks) => {
+  const columns = [];
+  return blocks.map((block) => {
+    if (!block.listItem) {
+      columns.length = 0;
+      return 0;
+    }
+    const depth = Math.min(Math.max(0, (block.level ?? 1) - 1), columns.length);
+    const indent = columns[depth - 1] ?? 0;
+    columns.length = depth;
+    columns.push(indent + listMarker(block).length + 1);
+    return indent;
+  });
+};
+var renderBlock3 = (block, options, indent) => {
   const custom = options.serializers?.[block._type];
   if (custom) {
     return custom(block);
@@ -3216,9 +3054,7 @@ var renderBlock3 = (block, options) => {
   }
   const inline = renderChildren(block);
   if (block.listItem) {
-    const indent = "  ".repeat(Math.max(0, (block.level ?? 1) - 1));
-    const marker = block.listItem === "number" ? "1." : "-";
-    return `${indent}${marker} ${inline}`;
+    return `${" ".repeat(indent)}${listMarker(block)} ${inline}`;
   }
   if (block.style === "blockquote") {
     return `> ${inline}`;
@@ -3226,7 +3062,8 @@ var renderBlock3 = (block, options) => {
   return `${HEADING_STYLES.get(block.style ?? "normal") ?? ""}${inline}`;
 };
 var portableTextToMarkdown = (blocks, options = {}) => {
-  const lines = blocks.map((block) => renderBlock3(block, options));
+  const indents = listIndents(blocks);
+  const lines = blocks.map((block, i) => renderBlock3(block, options, indents[i] ?? 0));
   const out = [];
   for (let i = 0;i < lines.length; i += 1) {
     const line = lines[i] ?? "";
@@ -3335,37 +3172,44 @@ var sanitySource = (options, ctx) => {
     prefix: options.prefix,
     read,
     staged: true,
-    watch: options.pollInterval ? pollingWatch(() => load(true), options.pollInterval, () => load()) : undefined
+    watch: options.pollInterval ? pollingWatch(() => load(true), options.pollInterval, () => load()) : undefined,
+    withContext: (next) => sanitySource(options, next)
   };
 };
 
 // src/core/sources/strapi-blocks.ts
 var children3 = (node) => objectsIn(node.children);
 var typeOf2 = (node) => asString(node.type) ?? "";
-var renderInlines3 = (nodes) => nodes.map((node) => renderInlineNode3(node)).join("");
-var renderInlineNode3 = (node) => {
+var inlineParts3 = (nodes) => nodes.flatMap((node) => inlineNodeParts3(node));
+var inlineNodeParts3 = (node) => {
   switch (typeOf2(node)) {
     case "text": {
-      return renderInline(asString(node.text) ?? "", {
-        bold: node.bold === true,
-        code: node.code === true,
-        italic: node.italic === true,
-        strike: node.strikethrough === true
-      });
+      return [
+        {
+          marks: {
+            bold: node.bold === true,
+            code: node.code === true,
+            italic: node.italic === true,
+            strike: node.strikethrough === true
+          },
+          text: asString(node.text) ?? ""
+        }
+      ];
     }
     case "link": {
-      return renderLink(renderInlines3(children3(node)), asString(node.url));
+      return linkParts(inlineParts3(children3(node)), asString(node.url));
     }
     default: {
-      return renderInlines3(children3(node));
+      return inlineParts3(children3(node));
     }
   }
 };
+var blockText3 = (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 = renderInlines3(kids.filter((kid) => typeOf2(kid) !== "list"));
+    const line = blockText3(kids.filter((kid) => typeOf2(kid) !== "list"));
     const sub = kids.filter((kid) => typeOf2(kid) === "list").map((list) => renderList3(list)).join(`
 `);
     const body = sub ? `${line}
@@ -3385,13 +3229,13 @@ var renderImage = (node, options) => {
 var renderBlock4 = (node, options) => {
   switch (typeOf2(node)) {
     case "paragraph": {
-      return renderInlines3(children3(node));
+      return blockText3(children3(node));
     }
     case "heading": {
-      return `${headingPrefix(asNumber(node.level) ?? 1)}${renderInlines3(children3(node))}`;
+      return `${headingPrefix(asNumber(node.level) ?? 1)}${blockText3(children3(node))}`;
     }
     case "quote": {
-      return blockquote(renderInlines3(children3(node)));
+      return blockquote(blockText3(children3(node)));
     }
     case "list": {
       return renderList3(node);
@@ -3491,7 +3335,8 @@ var strapiSource = (options, ctx) => {
     fetchEntries,
     name: options.name,
     pollInterval: options.pollInterval,
-    prefix: options.prefix
+    prefix: options.prefix,
+    withContext: (next) => strapiSource(options, next)
   }, ctx);
 };
 
@@ -3509,10 +3354,18 @@ var uniqueNamer = () => {
     return name;
   };
 };
-var sourceContext = (context, name, runtime) => ({
+var snapshotKey = (adapter, runtime) => {
+  const mode = runtime.preview ? "preview" : "published";
+  if (adapter.kind === "custom") {
+    return mode;
+  }
+  const { pollInterval: _paced, ...fetched } = adapter.options;
+  return `${mode}-${hashText(JSON.stringify(fetched))}`;
+};
+var sourceContext = (context, name, runtime, snapshot) => ({
   assetsBaseUrl: `/blume-assets/${name}`,
   assetsDir: join7(context.outDir, "public", "blume-assets", name),
-  cacheDir: join7(context.outDir, "cache", name),
+  cacheDir: snapshot === undefined ? join7(context.outDir, "cache", name) : join7(context.outDir, "cache", name, snapshot),
   mode: runtime.mode,
   preview: runtime.preview,
   projectRoot: context.root,
@@ -3523,29 +3376,30 @@ var typeFrontmatterKeys = (config) => Object.fromEntries(Object.entries(config.c
   Object.keys(def.frontmatter)
 ]));
 var buildSource = (adapter, name, config, context, runtime) => {
+  const ctx = () => sourceContext(context, name, runtime, snapshotKey(adapter, runtime));
   switch (adapter.kind) {
     case "filesystem": {
       const { pollInterval: _ignored, ...options } = adapter.options;
       return filesystemSource({ ...options, name, projectRoot: context.root });
     }
     case "custom": {
-      const source = adapter.options;
+      const source = adapter.options.withContext?.(ctx()) ?? adapter.options;
       return source.name === name ? source : { ...source, name };
     }
     case "sanity": {
-      return sanitySource({ ...adapter.options, name }, sourceContext(context, name, runtime));
+      return sanitySource({ ...adapter.options, name }, ctx());
     }
     case "notion": {
-      return notionSource({ ...adapter.options, name }, sourceContext(context, name, runtime));
+      return notionSource({ ...adapter.options, name }, ctx());
     }
     case "contentful": {
-      return contentfulSource({ ...adapter.options, name }, sourceContext(context, name, runtime));
+      return contentfulSource({ ...adapter.options, name }, ctx());
     }
     case "payload": {
-      return payloadSource({ ...adapter.options, name }, sourceContext(context, name, runtime));
+      return payloadSource({ ...adapter.options, name }, ctx());
     }
     case "strapi": {
-      return strapiSource({ ...adapter.options, name }, sourceContext(context, name, runtime));
+      return strapiSource({ ...adapter.options, name }, ctx());
     }
     case "obsidian": {
       const { pollInterval: _ignored, ...options } = adapter.options;
@@ -3557,22 +3411,22 @@ var buildSource = (adapter, name, config, context, runtime) => {
         name,
         typeFrontmatterKeys: typeFrontmatterKeys(config),
         versions: config.versions
-      }, sourceContext(context, name, runtime));
+      }, ctx());
     }
     case "github-releases": {
-      return githubReleasesSource({ ...adapter.options, name }, sourceContext(context, name, runtime));
+      return githubReleasesSource({ ...adapter.options, name, site: config.deployment.options.site }, ctx());
     }
     default: {
       break;
     }
   }
-  return mdxRemoteSource({ ...adapter.options, name }, sourceContext(context, name, runtime));
+  return mdxRemoteSource({ ...adapter.options, name }, ctx());
 };
 var baseName = (adapter) => {
   if (adapter.kind === "custom") {
     return adapter.options.name;
   }
-  return adapter.options.prefix ?? adapter.kind;
+  return trimChar(adapter.options.prefix ?? "", "/") || adapter.kind;
 };
 var resolveSources = (config, context, runtime) => {
   const nameFor = uniqueNamer();
@@ -3640,6 +3494,7 @@ var normalizeLoadedEntries = (loaded, config) => {
         source: {
           monolingual: source.monolingual,
           name: source.name,
+          orderedNames: source.orderedNames,
           prefix: source.prefix,
           staged: source.staged
         },
@@ -3651,12 +3506,24 @@ var normalizeLoadedEntries = (loaded, config) => {
       }
       pages.push(...normalized.pages);
       allDiagnostics.push(...normalized.diagnostics);
+      if (normalized.pages.length > 0) {
+        allDiagnostics.push(...unknownDirectiveDiagnostics(entry, source.name));
+      }
     }
   }
   return { diagnostics: allDiagnostics, droppedPages, pages };
 };
+var gitContentRoots = (sources, gitRoot) => {
+  if (gitRoot === null) {
+    return [];
+  }
+  const top = realPath(gitRoot);
+  return sources.flatMap((source) => source.contentRoot ? [source.contentRoot] : []).filter((dir) => isWithin(top, realPath(dir)));
+};
 var isLogoShorthand = (logo) => typeof logo === "string";
 var logoHref = (logo) => logo === undefined || isLogoShorthand(logo) ? "/" : logo.href ?? "/";
+var isBannerShorthand = (banner) => typeof banner === "string";
+var bannerLinkHref = (banner) => banner === undefined || isBannerShorthand(banner) ? undefined : banner.link?.href;
 var scanProject = async (root, options = {}) => {
   const mode = options.mode ?? "dev";
   const preview = options.preview ?? false;
@@ -3675,7 +3542,14 @@ var scanProject = async (root, options = {}) => {
   for (const source of sources) {
     source.validate?.();
   }
-  const metaSources = sources.flatMap((source) => source.staged || !source.contentRoot ? [] : [{ prefix: source.prefix, root: source.contentRoot }]);
+  const metaSources = sources.flatMap((source) => source.staged || !source.contentRoot ? [] : [
+    {
+      exclude: source.exclude,
+      include: source.include,
+      prefix: source.prefix,
+      root: source.contentRoot
+    }
+  ]);
   const localeDirs = config.i18n && config.i18n.parser === "dir" ? config.i18n.locales.flatMap((locale) => locale.code === config.i18n?.defaultLocale ? [] : [locale.code]) : undefined;
   const [loaded, folderMeta] = await Promise.all([
     Promise.all(sources.map(async (source) => ({ source, ...await source.load() }))),
@@ -3717,7 +3591,7 @@ var scanProject = async (root, options = {}) => {
   if (lastModified.enabled && lastModified.source === "git") {
     const fsPaths = pages.map((page) => page.sourcePath).filter((path) => path !== undefined);
     const gitRoot = gitRepositoryRoot(context.root);
-    const contentRoots = sources.flatMap((source) => source.contentRoot ? [source.contentRoot] : []).filter((dir) => gitRoot !== null && isWithin(gitRoot, dir));
+    const contentRoots = gitContentRoots(sources, gitRoot);
     const gitTimes = gitLastModifiedTimes(context.root, contentRoots, fsPaths, gitRoot);
     for (const page of pages) {
       if (!page.lastModified && page.sourcePath) {
@@ -3729,6 +3603,7 @@ var scanProject = async (root, options = {}) => {
   }
   const customPages = context.pagesRoot ? await discoverPages(context.pagesRoot) : [];
   const graph = buildContentGraph(pages, {
+    bannerHref: bannerLinkHref(config.banner),
     basePath: config.basePath,
     brandHref: logoHref(config.logo),
     extraRoutes: new Set([
@@ -3766,7 +3641,7 @@ var scanProject = async (root, options = {}) => {
   };
 };
 
-export { validateSearchPopularIcons, validateNavTargets, contentIndexable, buildManifest, isWithin, scanProject };
+export { directiveSource, validateSearchPopularIcons, validateNavTargets, contentIndexable, buildManifest, findFolderMetaFiles, isWithin, scanProject };
 
-//# debugId=EBFFBF92D39DE54464756E2164756E21
-//# sourceMappingURL=chunk-fs23ddbb.js.map
+//# debugId=B7A86608D56AB00864756E2164756E21
+//# sourceMappingURL=chunk-j85vccga.js.map