blume 2.0.0 → 2.0.2

package/dist/cli/{chunk-zg2gtj10.js → chunk-5r8g91qn.js}

@@ -16,6 +16,10 @@ import {
   localizeRoute,
   localizeInternalPath,
   i18nDiagnostics,
+  normalizeRef,
+  isPageRef,
+  pagesByRef,
+  buildNavigation,
   PUBLIC_API_URL,
   pageMetaSchema,
   folderMetaSchema,
@@ -35,7 +39,9 @@ import {
   parseYouTubeId,
   nodeRequire,
   escapeMarkdownText,
+  guardBlockStart,
   renderInline,
+  destination,
   renderLink,
   headingPrefix,
   blockquote,
@@ -51,10 +57,15 @@ import {
   neutralizeUnsafeLinks,
   columnsPrefix,
   openApiSource,
+  BLUME_IGNORE_DIRS,
+  baselineScanIgnore,
+  BLUME_WATCH_IGNORE_DIRS,
+  excludeDirSegments,
+  ignoringWatchListener,
   createModuleLoader,
   resolveProjectContext,
   loadConfig
-} from "./chunk-xaz13gwg.js";
+} from "./chunk-v6ya5kcb.js";
 import {
   getBlumeVersion,
   BlumeError,
@@ -64,15 +75,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-gs7r695n.js";
 
 // src/core/manifest.ts
 var versionAlternateKey = (versionKey, locale) => `${versionKey}\x00${locale}`;
@@ -105,7 +109,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 +159,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,
@@ -315,7 +320,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 +332,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 +429,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 +461,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 +474,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 +495,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 +531,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 +547,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 +556,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 +623,7 @@ var buildVersionNavigation = (id, versionPages, options, diagnostics) => {
       selectors: options.navigation.selectors,
       sharedFolderMeta: options.sharedFolderMeta,
       sharedMetaPrefix: id,
+      tabRoot: "/",
       tabs: resolveTabLabels(options.navigation.tabs, "")
     })
   };
@@ -1115,12 +651,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,
@@ -1224,7 +772,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 +783,20 @@ 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 metaKeyFor = (prefix, dir) => {
   const clean = prefix ? trimChar(prefix, "/") : "";
   if (!clean) {
@@ -1244,19 +806,25 @@ 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, {
+    const found = await glob(META_FILES, {
       absolute: true,
       cwd: source.root,
-      ignore: ["**/node_modules/**", "**/.blume/**", "**/dist/**"],
+      ignore: [
+        ...source.exclude ?? [],
+        "**/node_modules/**",
+        "**/.blume/**",
+        "**/dist/**"
+      ],
       onlyFiles: true
     });
+    const files = found.filter((file) => withinInclude(relative2(source.root, dirname(file)), source.include));
     const loaded = await Promise.all(files.map(async (file) => {
       try {
         return {
@@ -1277,7 +845,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) {
@@ -1439,11 +1007,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))}${guardBlockStart(renderInlines(children(node), options))}`;
   }
   switch (type) {
     case "paragraph": {
-      return renderInlines(children(node), options);
+      return guardBlockStart(renderInlines(children(node), options));
     }
     case "blockquote": {
       return blockquote(joinBlocks(children(node).map((child) => renderBlock(child, options))));
@@ -1480,6 +1048,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 +1067,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 +1122,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 +1158,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 +1206,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);
@@ -1654,7 +1232,7 @@ var filesystemSource = (options) => {
     files.sort();
     const entries = await Promise.all(files.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 {
@@ -1674,7 +1252,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 +1269,8 @@ var filesystemSource = (options) => {
   };
   return {
     contentRoot,
+    exclude: options.exclude,
+    include: options.include,
     load,
     name: options.name,
     prefix: options.prefix,
@@ -1763,6 +1343,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(mdastToString(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 +1408,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 },
@@ -1836,7 +1472,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 +1506,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)
   };
 };
 
@@ -2013,7 +1650,8 @@ var mdxRemoteSource = (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) => mdxRemoteSource(options, next)
   };
 };
 
@@ -2032,34 +1670,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 +1725,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 +1746,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 +1764,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 +1814,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);
@@ -2202,7 +1851,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 +1871,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 ?? "";
@@ -2234,13 +1885,13 @@ 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)}>
+  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 +1971,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>
@@ -2494,7 +2148,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 +2396,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 +2457,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 +2477,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
     };
@@ -2956,6 +2617,7 @@ var obsidianSource = (options, ctx) => {
     contentRoot: vaultDir,
     load,
     name: options.name,
+    orderedNames: true,
     prefix: options.prefix,
     read,
     staged: true,
@@ -3015,6 +2677,7 @@ var renderInlineNode2 = (node, options) => {
     }
   }
 };
+var blockText = (node, options) => guardBlockStart(renderInlines2(children2(node), options));
 var renderUpload = (node, options) => {
   const value = asObject(node.value);
   const url = value ? asString(value.url) : undefined;
@@ -3045,7 +2708,7 @@ var renderList2 = (node, options) => {
     if (listType === "check") {
       check = item.checked === true ? "[x] " : "[ ] ";
     }
-    const line = `${check}${renderInlines2(inline, options)}`;
+    const line = `${check}${guardBlockStart(renderInlines2(inline, options))}`;
     items.push(listItem(lastMarker, sub ? `${line}
 ${sub}` : line));
     index += 1;
@@ -3056,14 +2719,14 @@ ${sub}` : line));
 var renderBlock2 = (node, options) => {
   switch (typeOf(node)) {
     case "paragraph": {
-      return renderInlines2(children2(node), options);
+      return blockText(node, options);
     }
     case "heading": {
       const level = Number((asString(node.tag) ?? "h1").slice(1));
-      return `${headingPrefix(level)}${renderInlines2(children2(node), options)}`;
+      return `${headingPrefix(level)}${blockText(node, options)}`;
     }
     case "quote": {
-      return blockquote(renderInlines2(children2(node), options));
+      return blockquote(blockText(node, options));
     }
     case "list": {
       return renderList2(node, options);
@@ -3145,7 +2808,8 @@ var payloadSource = (options, ctx) => {
     fetchEntries,
     name: options.name,
     pollInterval: options.pollInterval,
-    prefix: options.prefix
+    prefix: options.prefix,
+    withContext: (next) => payloadSource(options, next)
   }, ctx);
 };
 
@@ -3162,46 +2826,36 @@ var HEADING_STYLES = new Map([
   ["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;
+  const marks = span.marks ?? [];
+  const link = marks.map((mark) => defs.get(mark)).findLast((def) => def?._type === "link");
+  return renderLink(renderInline(span.text ?? "", {
+    bold: marks.includes("strong"),
+    code: marks.includes("code"),
+    italic: marks.includes("em"),
+    strike: marks.includes("strike-through")
+  }), link?.href);
 };
 var renderChildren = (block) => {
   const defs = new Map((block.markDefs ?? []).map((def) => [def._key, def]));
-  return (block.children ?? []).map((span) => renderSpan(span, defs)).join("");
+  return guardBlockStart((block.children ?? []).map((span) => renderSpan(span, defs)).join(""));
 };
 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 +2870,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 +2878,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,7 +2988,8 @@ 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)
   };
 };
 
@@ -3361,11 +3015,12 @@ var renderInlineNode3 = (node) => {
     }
   }
 };
+var blockText2 = (nodes) => guardBlockStart(renderInlines3(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 = blockText2(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 +3040,13 @@ var renderImage = (node, options) => {
 var renderBlock4 = (node, options) => {
   switch (typeOf2(node)) {
     case "paragraph": {
-      return renderInlines3(children3(node));
+      return blockText2(children3(node));
     }
     case "heading": {
-      return `${headingPrefix(asNumber(node.level) ?? 1)}${renderInlines3(children3(node))}`;
+      return `${headingPrefix(asNumber(node.level) ?? 1)}${blockText2(children3(node))}`;
     }
     case "quote": {
-      return blockquote(renderInlines3(children3(node)));
+      return blockquote(blockText2(children3(node)));
     }
     case "list": {
       return renderList3(node);
@@ -3491,7 +3146,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 +3165,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 +3187,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 +3222,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 +3305,7 @@ var normalizeLoadedEntries = (loaded, config) => {
         source: {
           monolingual: source.monolingual,
           name: source.name,
+          orderedNames: source.orderedNames,
           prefix: source.prefix,
           staged: source.staged
         },
@@ -3657,6 +3323,8 @@ var normalizeLoadedEntries = (loaded, config) => {
 };
 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 +3343,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() }))),
@@ -3729,6 +3404,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([
@@ -3768,5 +3444,5 @@ var scanProject = async (root, options = {}) => {
 
 export { validateSearchPopularIcons, validateNavTargets, contentIndexable, buildManifest, isWithin, scanProject };
 
-//# debugId=EBFFBF92D39DE54464756E2164756E21
-//# sourceMappingURL=chunk-zg2gtj10.js.map
+//# debugId=B3E8BA7A9A3228DD64756E2164756E21
+//# sourceMappingURL=chunk-5r8g91qn.js.map