blume 1.7.3 → 2.0.0

package/src/core/links.ts

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 
-import { basename, dirname, join, relative, resolve } from "pathe";
+import { basename, dirname, join, normalize, relative, resolve } from "pathe";
 
 import { stripBasePath, withBasePath } from "./base-path.ts";
 import {
@@ -80,6 +80,8 @@ interface LinkContext {
   /** Servable routes outside the graph (custom pages, generated routes); their
    * headings are unknown, so anchors there are accepted unchecked. */
   extraRoutes: Set<string>;
+  /** Where content files publish, for file links (`./setup.mdx`). */
+  fileRoutes: FileRouteIndex;
   /** Locale routing, when the site is multi-locale; drives served-route resolution. */
   i18n: LocaleRouting | null;
   publicDir: string | null;
@@ -156,6 +158,81 @@ const toRoute = (path: string): string => {
   return route === "" ? "/" : route;
 };
 
+/** The page a relative link is written on, as the resolver sees it. */
+export interface RelativeLinkBase {
+  /** Whether the page is its folder's index (its route is its directory). */
+  isIndex: boolean;
+  /** The page's own route, base path included. */
+  route: string;
+}
+
+/** A root-relative path, a bare `#fragment` or `?query`, or any scheme. */
+const NOT_RELATIVE = /^(?:[#?/]|[a-z][a-z0-9+.-]*:)/iu;
+
+/**
+ * Where a relative page link written on `from` lands: a root-relative route
+ * with the authored `?query#hash` kept — or `undefined` when `href` isn't a
+ * relative page link (a root-relative path, a bare `#fragment` or `?query`,
+ * an external URL or other scheme, or a relative asset like `./diagram.png`).
+ *
+ * The one reading `blume validate` checks links against and the Markdown
+ * pipeline rewrites them to, so the built `href`, the link check, and the
+ * browser agree. Relative paths resolve file-style: a leaf page's links
+ * resolve against its parent directory, while an index page's route already is
+ * its directory — `./install` on `guides/index.mdx` (`/guides`) lands on
+ * `/guides/install`, where a browser reading the slashless URL would go to
+ * `/install`. A `.md`/`.mdx` target is a file link: `resolveFile` maps its
+ * decoded path, relative to the linking file, to the route that file
+ * publishes at, so a target with its own `slug` or an ordering prefix still
+ * lands on its page instead of on its raw Markdown source. Without
+ * `resolveFile`, or for a file it doesn't know, the target resolves
+ * route-relative with the extension dropped.
+ *
+ * Any other extension (`./diagram.png`) marks an asset, except where a page
+ * publishes at the resolved path: `hasRoute` answers that, so a dotted page
+ * name (`./node.js` for `node.js.mdx`, `./v1.2`) is still a page link.
+ */
+export const resolveRelativeHref = (
+  href: string,
+  from: RelativeLinkBase,
+  resolveFile?: (path: string) => string | undefined,
+  hasRoute?: (route: string) => boolean
+): string | undefined => {
+  if (href === "" || NOT_RELATIVE.test(href)) {
+    return undefined;
+  }
+  const suffixAt = href.search(/[?#]/u);
+  const path = suffixAt === -1 ? href : href.slice(0, suffixAt);
+  const suffix = suffixAt === -1 ? "" : href.slice(suffixAt);
+  if (FILE_EXT.test(path) && !DOC_EXT.test(path)) {
+    const route = toRoute(resolveRelative(from.route, path, from.isIndex));
+    return hasRoute?.(decodePercent(route)) ? `${route}${suffix}` : undefined;
+  }
+  const fileRoute = DOC_EXT.test(path)
+    ? resolveFile?.(decodePercent(path))
+    : undefined;
+  return `${fileRoute ?? toRoute(resolveRelative(from.route, path, from.isIndex))}${suffix}`;
+};
+
+/**
+ * Whether a content file is its folder's index, from its name as written on
+ * disk: `index.md(x)` after an ordering prefix, optionally carrying one of
+ * `localeTokens` before the extension (`index.fr.mdx` under the `dot` locale
+ * parser, `index.$.mdx` for a file shared by every locale).
+ */
+export const isIndexFileName = (
+  name: string,
+  localeTokens: readonly string[] = []
+): boolean => {
+  const stem = basename(name).replace(NUMERIC_PREFIX, "");
+  const match = /^index(?:\.(?<token>[^./]+))?\.(?:md|mdx)$/iu.exec(stem);
+  if (!match) {
+    return false;
+  }
+  const token = match.groups?.token;
+  return token === undefined || localeTokens.includes(token);
+};
+
 /** Build a map of route -> set of heading anchor slugs. */
 const buildAnchorIndex = (pages: PageRecord[]): Map<string, Set<string>> => {
   const anchors = new Map<string, Set<string>>();
@@ -329,6 +406,92 @@ const checkExternalLinks = async (
   return diagnostics;
 };
 
+/** Where content files publish, for resolving file links (`./setup.mdx`). */
+export interface FileRouteIndex {
+  /**
+   * Absolute source path → the route that file publishes at. A file shared by
+   * every locale publishes once per locale; the default locale's route stands
+   * for it (a link from a localized page moves into that locale afterwards,
+   * exactly as the rendered link does). Fallback copies render another
+   * locale's file, so they never stand for it.
+   */
+  bySource: Map<string, string>;
+  /**
+   * A default-locale page's locale-stripped path (`navPath`) → its route. A
+   * page in a locale folder that links a sibling not translated yet
+   * (`fr/guides/setup.mdx` missing) means the default tree's file
+   * (`guides/setup.mdx`), whose route — its own `slug` included — then moves
+   * into the reader's locale onto the fallback copy.
+   */
+  byDefaultNavPath: Map<string, string>;
+}
+
+/** The linking side of a file link: where the page's source lives. */
+export interface FileLinkBase {
+  navPath: string;
+  sourcePath: string;
+}
+
+export const buildFileRouteIndex = (
+  pages: readonly PageRecord[],
+  i18n: LocaleRouting | null
+): FileRouteIndex => {
+  const bySource = new Map<string, string>();
+  const byDefaultNavPath = new Map<string, string>();
+  for (const page of pages) {
+    const { sourcePath } = page;
+    if (!sourcePath || page.fallback) {
+      continue;
+    }
+    const isDefault = page.locale === i18n?.defaultLocale;
+    if (!bySource.has(sourcePath) || isDefault) {
+      bySource.set(sourcePath, page.route);
+    }
+    if (isDefault) {
+      byDefaultNavPath.set(normalize(page.navPath), page.route);
+    }
+  }
+  return { byDefaultNavPath, bySource };
+};
+
+/**
+ * The route a file link written on `from` lands on: the linked file's own
+ * route, or — when a locale folder doesn't have that file yet — the default
+ * tree's file at the same place.
+ */
+export const routeOfLinkedFile = (
+  index: FileRouteIndex,
+  from: FileLinkBase,
+  path: string
+): string | undefined =>
+  index.bySource.get(resolve(dirname(from.sourcePath), path)) ??
+  index.byDefaultNavPath.get(normalize(join(dirname(from.navPath), path)));
+
+/**
+ * The path a relative link on `page` resolves to — the same reading the
+ * Markdown pipeline rewrites the rendered `href` to (see
+ * {@link resolveRelativeHref}), so what's checked is what ships. A relative
+ * asset (`./diagram.png`) isn't a page link; it resolves against the route's
+ * directory for the public-dir probe.
+ */
+const relativeTarget = (
+  page: PageRecord,
+  rawPath: string,
+  ctx: LinkContext
+): string => {
+  const base = { isIndex: isIndexPage(page), route: page.route };
+  const { navPath, sourcePath } = page;
+  const resolveFile = sourcePath
+    ? (path: string) =>
+        routeOfLinkedFile(ctx.fileRoutes, { navPath, sourcePath }, path)
+    : undefined;
+  return (
+    resolveRelativeHref(rawPath, base, resolveFile, (route) =>
+      ctx.routes.has(route)
+    ) ?? resolveRelative(page.route, rawPath, base.isIndex)
+  );
+};
+
 /** Classify a single link, queueing external refs via `onExternal`. */
 const classifyLink = (
   page: PageRecord,
@@ -382,7 +545,7 @@ const classifyLink = (
 
   const resolved = rawPath.startsWith("/")
     ? rawPath
-    : resolveRelative(page.route, rawPath, isIndexPage(page));
+    : relativeTarget(page, rawPath, ctx);
   return checkPathLink(resolved, fragment, page, link, site, ctx, via);
 };
 
@@ -416,6 +579,7 @@ export const validateLinks = async (
     anchors: buildAnchorIndex(graph.pages),
     basePath,
     extraRoutes: new Set((options.extraRoutes ?? []).map(toRoute)),
+    fileRoutes: buildFileRouteIndex(graph.pages, options.i18n ?? null),
     i18n: options.i18n ?? null,
     publicDir: options.publicDir,
     redirects: new Set(

package/src/core/manifest.ts

@@ -82,9 +82,14 @@ const buildFallbackRoutes = (
   if (!fallback) {
     return [];
   }
+  // A monolingual page (a GitHub release) publishes in one language only, so it
+  // gets no copy at every other locale's URL: those would be duplicates of the
+  // same text under a translated chrome.
   const fallbackPages = new Map(
     graph.pages.flatMap((page) =>
-      page.locale === fallback ? [[page.translationKey, page] as const] : []
+      page.locale === fallback && !page.monolingual
+        ? [[page.translationKey, page] as const]
+        : []
     )
   );
   const routes: RouteManifestEntry[] = [];
@@ -126,6 +131,7 @@ const buildFallbackRoutes = (
         indexable: false,
         lastModified: source.lastModified,
         locale: code,
+        monolingual: source.monolingual,
         path,
         source: source.source,
         sourcePath: source.sourcePath,
@@ -145,7 +151,7 @@ export const buildManifest = (options: {
   graph: ContentGraph;
 }): BlumeManifest => {
   const { context, config, graph } = options;
-  const searchEnabled = config.search.provider !== "none";
+  const searchEnabled = config.search.provider.mode !== "none";
   const { i18n } = config;
 
   // Real translations per logical page, for `hreflang` and the switcher. Built
@@ -189,6 +195,7 @@ export const buildManifest = (options: {
     indexable: searchEnabled && contentIndexable(page, config),
     lastModified: page.lastModified,
     locale: page.locale,
+    monolingual: page.monolingual,
     path: page.route,
     source: page.source,
     sourcePath: page.sourcePath,
@@ -234,7 +241,7 @@ export const buildManifest = (options: {
   return {
     blumeVersion: getBlumeVersion(),
     contentRoot: context.contentRoot,
-    output: config.deployment.output,
+    output: config.deployment.options.output,
     projectRoot: context.root,
     routes,
     version: MANIFEST_VERSION,

package/src/core/navigation.ts

@@ -43,12 +43,66 @@ export const isUnderPath = (route: string, base: string): boolean =>
 export const isRootTab = (tab: NavTab, root: string): boolean =>
   isUnderPath(root, tab.path);
 
+/**
+ * A page's sidebar icon: `sidebar.icon`, or the top-level `icon` shorthand
+ * (the Mintlify-style spelling) when the nested key is unset.
+ */
+const sidebarIcon = (page: PageRecord): string | undefined =>
+  page.meta.sidebar.icon ?? page.meta.icon;
+
+/**
+ * Words a folder name spells in lowercase that read wrong capitalized: the
+ * acronyms and brand casings docs folders are named after (`api-reference`
+ * is "API Reference", not "Api Reference").
+ */
+const 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"],
+]);
+
 const humanize = (segment: string): string =>
   segment
     .replace(NUMERIC_PREFIX, "")
     .split(WORD_SPLIT)
     .filter(Boolean)
-    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .map(
+      (word) =>
+        WORD_FORMS.get(word) ?? word.charAt(0).toUpperCase() + word.slice(1)
+    )
     .join(" ");
 
 const numericOrder = (segment: string): number => {
@@ -276,6 +330,12 @@ const applyFolderMeta = (
  * update the folder's `meta.ts` and forget the index page's own frontmatter
  * (or vice versa), and a correct-looking sidebar hides the mismatch.
  *
+ * Only fires when the index page's own sidebar row is hidden
+ * (`sidebar.hidden`), so the linked group header is the only sidebar label the
+ * page has. A visible index row shows the page's own label beneath the header,
+ * so the sidebar already carries both titles and a divergence there is a
+ * deliberate pairing ("CLI" over "Overview"), not drift.
+ *
  * Only fires when the page has an explicit frontmatter `title` of its own:
  * when it's absent, `page.title` is derived from the first heading or the
  * filename, so it almost never coincidentally matches a custom folder title —
@@ -298,7 +358,11 @@ const indexTitleMismatchDiagnostic = (
   metaPrefix: string,
   sharedMetaPrefix: string
 ): Diagnostic | undefined => {
-  if (!page.meta.title || page.fallback || folderPath === "") {
+  if (
+    !(page.meta.title && page.meta.sidebar.hidden) ||
+    page.fallback ||
+    folderPath === ""
+  ) {
     return undefined;
   }
   const meta =
@@ -552,8 +616,9 @@ const buildFileSystemSidebar = (
     const stem = stemOf(filename);
     const dirs = parts.slice(0, -1);
 
-    // Checked before the hidden filter: a sidebar-hidden index page still
-    // renders with its own <title>, so title drift matters there just the same.
+    // Checked before the hidden filter: the title check fires only for a
+    // sidebar-hidden index page, whose own <title> the header label stands in
+    // for, so it must see the pages the filter drops.
     if (isIndexStem(stem)) {
       const diagnostic = indexTitleMismatchDiagnostic(
         page,
@@ -612,7 +677,7 @@ const buildFileSystemSidebar = (
       deprecated: page.meta.deprecated || undefined,
       description: page.description,
       file: page.sourcePath,
-      icon: page.meta.sidebar.icon,
+      icon: sidebarIcon(page),
       key: segmentKey(stem),
       kind: "page",
       label: page.meta.sidebar.label ?? page.title,
@@ -691,7 +756,7 @@ const configItemToNode = (
       badge: page.meta.sidebar.badge,
       deprecated: page.meta.deprecated || undefined,
       description: page.description,
-      icon: page.meta.sidebar.icon,
+      icon: sidebarIcon(page),
       kind: "page",
       label: page.meta.sidebar.label ?? page.title,
       pageId: page.id,
@@ -760,10 +825,26 @@ const buildConfigSidebar = (
 /**
  * Resolve a tab's clickable target. A tab's `path` scopes its sidebar section
  * but need not be a real route — a section with no index page would 404 if the
- * tab linked straight to it. Prefer an exact page/group at the path; otherwise
- * fall back to the first linkable route in the section (sidebar order).
+ * tab linked straight to it. Prefer the path itself when it's served outside
+ * the content tree (the generated changelog index) or is a page/group in the
+ * tree; otherwise fall back to the first linkable route in the section
+ * (sidebar order).
+ *
+ * Routes outside the content tree are served at their own path, not under
+ * `basePath` (`pages/changelog.astro` answers `/changelog` on a `/docs`-based
+ * site), while tab paths arrive based (`/docs/changelog`). So when the based
+ * path is neither an outside route nor a tree node, the base-less path is
+ * checked against the outside routes before the section's first page wins.
  */
-const resolveTabHref = (sidebar: NavNode[], path: string): string => {
+const resolveTabHref = (
+  sidebar: NavNode[],
+  path: string,
+  extraRoutes: ReadonlySet<string>,
+  basePath: string
+): string => {
+  if (extraRoutes.has(path)) {
+    return path;
+  }
   let first: string | undefined;
   const walk = (nodes: NavNode[]): boolean => {
     for (const node of nodes) {
@@ -784,19 +865,30 @@ const resolveTabHref = (sidebar: NavNode[], path: string): string => {
     }
     return false;
   };
-  return walk(sidebar) ? path : (first ?? path);
+  if (walk(sidebar)) {
+    return path;
+  }
+  const bare = stripBasePath(basePath, path);
+  return extraRoutes.has(bare) ? bare : (first ?? path);
 };
 
 /**
  * Attach a resolved `href` to each tab whose section has no index page. An
  * author-declared `href` is the tab's stated target, so it's kept as-is —
  * resolution only fills in the tabs that didn't declare one. That's what lets a
- * tab point at a route outside the content tree (a generated `/changelog`
- * index, a custom `.astro` page), which resolution can't see.
+ * tab point at a route outside the content tree that resolution can't see (a
+ * custom `.astro` page); the generated changelog index arrives in
+ * `extraRoutes`, so a `/changelog` tab needs no `href`.
  */
-const withTabHrefs = (tabs: NavTab[], sidebar: NavNode[]): NavTab[] =>
+const withTabHrefs = (
+  tabs: NavTab[],
+  sidebar: NavNode[],
+  extraRoutes: ReadonlySet<string>,
+  basePath: string
+): NavTab[] =>
   tabs.map((tab) => {
-    const href = tab.href ?? resolveTabHref(sidebar, tab.path);
+    const href =
+      tab.href ?? resolveTabHref(sidebar, tab.path, extraRoutes, basePath);
     return href === tab.path ? tab : { ...tab, href };
   });
 
@@ -913,6 +1005,12 @@ export const buildNavigation = (
      * into in place; omit to discard.
      */
     diagnostics?: Diagnostic[];
+    /**
+     * Routes served outside the content tree that a tab `path` may name
+     * directly (the generated changelog index), so the tab links there instead
+     * of falling back to its section's first page.
+     */
+    extraRoutes?: ReadonlySet<string>;
   }
 ): Navigation => {
   const basePath = options.basePath ?? "";
@@ -920,6 +1018,7 @@ export const buildNavigation = (
   const metaPrefix = options.metaPrefix ?? "";
   const sharedMetaPrefix = options.sharedMetaPrefix ?? "";
   const sharedFolderMeta = options.sharedFolderMeta ?? new Map();
+  const extraRoutes = options.extraRoutes ?? new Set<string>();
 
   // Content-derived sidebar routes are already based via `page.route`; the
   // based tab paths also feed tab-scoping below, so they must agree with the
@@ -981,7 +1080,7 @@ export const buildNavigation = (
       root: rootTabPath,
       selectors,
       sidebar,
-      tabs: withTabHrefs(tabs, sidebar),
+      tabs: withTabHrefs(tabs, sidebar, extraRoutes, basePath),
     };
   }
 
@@ -1004,6 +1103,6 @@ export const buildNavigation = (
     root: rootTabPath,
     selectors,
     sidebar,
-    tabs: withTabHrefs(tabs, sidebar),
+    tabs: withTabHrefs(tabs, sidebar, extraRoutes, basePath),
   };
 };

package/src/core/new-tab.ts

@@ -0,0 +1,35 @@
+/**
+ * Links that open in a new tab. Every such link Blume renders — chrome (header
+ * actions, featured sidebar links, page actions), content components (Card,
+ * Tile, Tooltip), and Markdown links under `markdown.externalLinks` — points
+ * `aria-describedby` at one hidden, localized "Opens in a new tab" element each
+ * layout renders once per page, so screen-reader users hear the same warning
+ * sighted readers get from the arrow icon or the new tab itself.
+ */
+
+import { isExternalUrl } from "./base-path.ts";
+
+/** The id of the layout's hidden "Opens in a new tab" description. */
+export const NEW_TAB_HINT_ID = "blume-new-tab-hint";
+
+/** The attributes a new-tab link carries (spread onto an `<a>`). */
+export interface NewTabAttrs {
+  "aria-describedby"?: string;
+  rel?: string;
+  target?: string;
+}
+
+/** A link that always opens in a new tab (a repo link, an edit link). */
+export const NEW_TAB_ATTRS: NewTabAttrs = {
+  "aria-describedby": NEW_TAB_HINT_ID,
+  rel: "noreferrer",
+  target: "_blank",
+};
+
+/**
+ * {@link NEW_TAB_ATTRS} for an external href (the shared `isExternalUrl`
+ * predicate), and nothing for a site route, fragment, or `mailto:` link, which
+ * stay in the current tab.
+ */
+export const newTabAttrs = (href?: string): NewTabAttrs =>
+  href !== undefined && isExternalUrl(href) ? NEW_TAB_ATTRS : {};

package/src/core/node-require.ts

@@ -0,0 +1,21 @@
+import { createRequire } from "node:module";
+
+/**
+ * Node's own `require`, for the SDKs and heavy modules Blume loads only when a
+ * feature needs them. Resolution starts from this file, inside the installed
+ * package, exactly like the `import()` it stands in for, and Node 22.12+ loads
+ * ES modules through it too.
+ *
+ * Never `import()` in their place. When Node can't import the generated Astro
+ * config itself — it refuses to strip types from TypeScript under
+ * `node_modules`, which is where an installed Blume's runtime source lives —
+ * Astro evaluates the config, and every Blume module it reaches, in a Vite
+ * module runner that it closes as soon as the config has loaded. A dynamic
+ * `import()` in one of those modules resolves through that runner, so a call
+ * made any later (an `astro:build:done` hook, a Markdown plugin) throws "Vite
+ * module runner has been closed". `require` is Node's, so it works however the
+ * calling module was evaluated. The repo itself never sees the failure: its
+ * workspace link puts Blume outside `node_modules`, so Node imports the config
+ * natively.
+ */
+export const nodeRequire = createRequire(import.meta.url);

package/src/core/project-graph.ts

@@ -1,7 +1,8 @@
 import { isAbsolute, relative } from "pathe";
 
+import { CHANGELOG_INDEX_ROUTE, hasChangelogIndex } from "./changelog-index.ts";
 import { loadConfig } from "./config.ts";
-import { applyDeploymentEnv } from "./deployment-env.ts";
+import { customStaticRoutes, discoverPages } from "./custom-pages.ts";
 import { buildContentGraph } from "./graph.ts";
 import { i18nDiagnostics } from "./i18n.ts";
 import { expandIncludes, hasIncludeStatements } from "./includes.ts";
@@ -36,12 +37,6 @@ export type BuildMode = "dev" | "build";
 export interface ConfigOverrides {
   /** Override `content.root` (`blume dev --content-dir`). */
   contentRoot?: string;
-  /** Override `deployment.adapter` (`blume build --adapter`). */
-  adapter?: ResolvedConfig["deployment"]["adapter"];
-  /** Override `deployment.base` (`blume build --base`). */
-  base?: string;
-  /** Override `deployment.output` (`blume build --output`). */
-  output?: ResolvedConfig["deployment"]["output"];
 }
 
 /**
@@ -61,18 +56,20 @@ const applyConfigOverrides = (
   if (!overrides) {
     return config;
   }
+  // `--content-dir` re-roots every filesystem source: with one (the
+  // zero-config case) it is exactly the old `content.root` override, and
+  // several must share a root anyway (see `resolveDocsCollection`).
+  const { contentRoot } = overrides;
+  const sources = contentRoot
+    ? config.content.sources.map((source) =>
+        source.kind === "filesystem"
+          ? { ...source, options: { ...source.options, root: contentRoot } }
+          : source
+      )
+    : config.content.sources;
   return {
     ...config,
-    content: {
-      ...config.content,
-      root: overrides.contentRoot ?? config.content.root,
-    },
-    deployment: {
-      ...config.deployment,
-      adapter: overrides.adapter ?? config.deployment.adapter,
-      base: overrides.base ?? config.deployment.base,
-      output: overrides.output ?? config.deployment.output,
-    },
+    content: { ...config.content, sources },
   };
 };
 
@@ -138,7 +135,7 @@ const entryIdDiagnostics = (
         message: `Content source "${page.source.name}" is rooted outside the docs collection base, so ${page.route} resolves entry id "${entryId}" but the collection would generate "${expected}" — the page would 404 at runtime.`,
         severity: "error",
         suggestion:
-          "Use a single filesystem source (the docs collection roots at it), or root every filesystem source at content.root and partition them with include globs — a root at a subdirectory of content.root still mismatches.",
+          "Use a single filesystem() source (the docs collection roots at it), or give every filesystem() source the same root and partition them with include globs — a root at a subdirectory of the first source's root still mismatches.",
       });
     }
   }
@@ -185,6 +182,7 @@ const normalizeLoadedEntries = (
         frontmatterExtend,
         i18n: config.i18n,
         source: {
+          monolingual: source.monolingual,
           name: source.name,
           prefix: source.prefix,
           staged: source.staged,
@@ -208,6 +206,15 @@ const normalizeLoadedEntries = (
  * Collects all diagnostics without throwing on content-level problems so
  * callers can decide how strict to be.
  */
+/** Narrows the logo config's image shorthand from its object form. */
+const isLogoShorthand = (
+  logo: NonNullable<ResolvedConfig["logo"]>
+): logo is string => typeof logo === "string";
+
+/** The configured brand link: `logo.href`, else the site root. */
+const logoHref = (logo: ResolvedConfig["logo"]): string =>
+  logo === undefined || isLogoShorthand(logo) ? "/" : (logo.href ?? "/");
+
 export const scanProject = async (
   root: string,
   options: {
@@ -226,13 +233,7 @@ export const scanProject = async (
   const configResult = await loadConfig(root, {
     devServerUrl: options.devServerUrl,
   });
-  // Re-run platform detection after CLI overrides: `loadConfig` already ran it,
-  // but adapter inference keys off `deployment.output`, which `--output server`
-  // only sets here. Idempotent for already-resolved fields — `deployment.site`
-  // keeps loadConfig's explicit > platform env > devServerUrl precedence.
-  const config = applyDeploymentEnv(
-    applyConfigOverrides(configResult.config, options.overrides)
-  );
+  const config = applyConfigOverrides(configResult.config, options.overrides);
   const context = resolveProjectContext(root, config, {
     runtimeDir: options.runtimeDir,
   });
@@ -373,8 +374,20 @@ export const scanProject = async (
     );
   }
 
+  // Custom `.astro` pages and the generated changelog index aren't content
+  // pages, so name them for navigation: a `/changelog` tab should open the
+  // timeline, not the newest entry, and a tab or brand link to a custom page
+  // must stay on its route in every locale.
+  const customPages = context.pagesRoot
+    ? await discoverPages(context.pagesRoot)
+    : [];
   const graph = buildContentGraph(pages, {
     basePath: config.basePath,
+    brandHref: logoHref(config.logo),
+    extraRoutes: new Set([
+      ...customStaticRoutes(customPages),
+      ...(hasChangelogIndex(pages, config) ? [CHANGELOG_INDEX_ROUTE] : []),
+    ]),
     folderMeta: folderMeta.meta,
     i18n: config.i18n,
     navigation: config.navigation,
@@ -397,7 +410,10 @@ export const scanProject = async (
       ...contentDiagnostics,
       ...includeDiagnostics,
       ...folderMeta.diagnostics,
-      ...entryIdDiagnostics(pages, resolveDocsCollection(config, context).base),
+      ...entryIdDiagnostics(
+        pages,
+        resolveDocsCollection(config, context.root).base
+      ),
       ...graph.diagnostics,
       ...i18nWarnings,
       ...versionWarnings,