blume 2.0.3 → 2.1.1

package/src/core/graph.ts

@@ -4,6 +4,7 @@ import {
   localizeRoute,
   resolveFallbackLocale,
 } from "./i18n.ts";
+import { resolveLocalizable } from "./localizable.ts";
 import {
   validateNavIcons,
   validateNavStructure,
@@ -97,31 +98,6 @@ const localePagesFor = (
   return [...real, ...filled];
 };
 
-/**
- * Resolve a possibly-per-locale header label to the string a locale renders:
- * the active locale's entry, else the default locale's, else the map's first
- * entry (which is also what a single-locale site gets).
- */
-/** A label is either one string for every locale or a per-locale map. */
-const isSingleLabel = (label: LocalizableLabel): label is string =>
-  typeof label === "string";
-
-const resolveLabel = (
-  label: LocalizableLabel,
-  locale: string,
-  defaultLocale?: string
-): string => {
-  if (isSingleLabel(label)) {
-    return label;
-  }
-  return (
-    label[locale] ??
-    (defaultLocale === undefined ? undefined : label[defaultLocale]) ??
-    Object.values(label)[0] ??
-    ""
-  );
-};
-
 /**
  * An explicit sidebar with every item's `href` passed through `localize` (page
  * refs and `root`s resolve against each locale's own pages already).
@@ -154,11 +130,36 @@ const resolveTabLabels = (
     ...tab,
     items: tab.items?.map((item) => ({
       ...item,
-      label: resolveLabel(item.label, locale, defaultLocale),
+      label: resolveLocalizable(item.label, locale, defaultLocale),
     })),
-    label: resolveLabel(tab.label, locale, defaultLocale),
+    label: resolveLocalizable(tab.label, locale, defaultLocale),
   }));
 
+/** A configured header or footer link with its label resolved for a locale. */
+const withLabel = <T extends { label: LocalizableLabel }>(
+  link: T,
+  locale: string,
+  defaultLocale?: string
+): Omit<T, "label"> & { label: string } => ({
+  ...link,
+  label: resolveLocalizable(link.label, locale, defaultLocale),
+});
+
+/** The configured header links (plain, call to action, featured) in `locale`. */
+const resolveHeaderLinks = (
+  navigation: BuildContentGraphOptions["navigation"],
+  locale: string,
+  defaultLocale?: string
+) => ({
+  actions: navigation.actions.map((link) =>
+    withLabel(link, locale, defaultLocale)
+  ),
+  cta: navigation.cta ? withLabel(navigation.cta, locale, defaultLocale) : null,
+  featured: navigation.featured.map((link) =>
+    withLabel(link, locale, defaultLocale)
+  ),
+});
+
 /**
  * Mount a configured link authored as if the site were served at root (the
  * banner's): under `basePath`, except a route served outside the content tree
@@ -274,18 +275,22 @@ const buildLocaleNavigation = (
     ...item,
     href: localizeServed(item.href, false),
   });
-  const { actions, cta, featured } = options.navigation;
+  const { actions, cta, featured } = resolveHeaderLinks(
+    options.navigation,
+    code,
+    i18n.defaultLocale
+  );
   const sidebarItems = options.navigation.sidebar.items;
 
   const navigation = buildNavigation(localePages, {
-    actions: actions?.map(localizeHref),
+    actions: actions.map(localizeHref),
     basePath,
     cta: cta ? localizeHref(cta) : null,
     diagnostics,
     display: options.navigation.sidebar.display,
     extraRoutes: options.extraRoutes,
     fallbackMetaPrefix,
-    featured: featured?.map(localizeHref),
+    featured: featured.map(localizeHref),
     folderMeta: options.folderMeta,
     // The localized tree root ("/" for the hidden default, "/fr" otherwise;
     // "/fr/v1.0" inside a snapshot): the tab pointing here spans the whole
@@ -415,13 +420,11 @@ const buildVersionNavigation = (
   }
   return {
     "": buildNavigation(versionPages, {
-      actions: options.navigation.actions,
+      ...resolveHeaderLinks(options.navigation, ""),
       basePath: options.basePath ?? "",
-      cta: options.navigation.cta,
       diagnostics,
       display: options.navigation.sidebar.display,
       extraRoutes: options.extraRoutes,
-      featured: options.navigation.featured,
       folderMeta: options.folderMeta,
       localizedRoot: versionizeRoute("/", id),
       metaPrefix: id,
@@ -465,13 +468,13 @@ export const buildContentGraph = (
     ));
   } else {
     navigation = buildNavigation(currentPages, {
-      actions: options.navigation.actions,
+      // No locale to prefer: a per-locale label map resolves to its first
+      // entry on a single-locale site.
+      ...resolveHeaderLinks(options.navigation, ""),
       basePath: options.basePath ?? "",
-      cta: options.navigation.cta,
       diagnostics,
       display: options.navigation.sidebar.display,
       extraRoutes: options.extraRoutes,
-      featured: options.navigation.featured,
       folderMeta: options.folderMeta,
       selectors: options.navigation.selectors,
       sharedFolderMeta: options.sharedFolderMeta,

package/src/core/i18n-ui.ts

@@ -15,6 +15,8 @@ const uiStringsObject = z.object({
     .object({
       addToCursor: z.string().default("Add to Cursor"),
       addToVscode: z.string().default("Add to VS Code"),
+      // A code block's button that opens the assistant with the code attached.
+      askAboutCode: z.string().default("Ask about this code"),
       connectMcp: z.string().default("Connect to MCP"),
       copied: z.string().default("Copied!"),
       copyClaudeCode: z.string().default("Copy Claude Code command"),
@@ -47,11 +49,32 @@ const uiStringsObject = z.object({
       copy: z.string().default("Copy conversation"),
       empty: z.string().default("Ask a question about the docs."),
       error: z.string().default("Sorry, something went wrong."),
+      // The question sent about an attached code block when the reader
+      // writes none.
+      explainCode: z.string().default("Explain this code."),
       label: z.string().default("Ask a question"),
+      // The header trigger's tooltip.
+      open: z.string().default("Open assistant"),
       placeholder: z.string().default("Ask a question…"),
+      // The answer when the rate limit (`rateLimit`) turns a question away.
+      rateLimited: z
+        .string()
+        .default(
+          "You've asked a lot of questions. Try again in a few minutes."
+        ),
+      // The attached code block's dismiss button.
+      removeCode: z.string().default("Remove code"),
       send: z.string().default("Send"),
+      // The link to your support channel (`ai.assistant.support`), and the
+      // subject of an email it starts.
+      support: z.string().default("Contact support"),
+      supportSubject: z.string().default("Question from the docs"),
       tip: z.string().default("Tip: You can open and close chat with"),
       title: z.string().default("Assistant"),
+      // The answer when the bot check (`ai.assistant.captcha`) fails.
+      verifyFailed: z
+        .string()
+        .default("We couldn't check that you're human. Try again."),
       you: z.string().default("You"),
     })
     .prefault({}),
@@ -67,9 +90,28 @@ const uiStringsObject = z.object({
         .default(
           "Product updates, new features, and fixes from every release."
         ),
+      // What the index says when it has no entries to list.
+      empty: z.string().default("No changelog entries yet."),
       title: z.string().default("Changelog"),
     })
     .prefault({}),
+  // The built-in cookie consent banner (`consent: native()`) and the footer
+  // link that reopens a consent manager's preferences.
+  consent: z
+    .object({
+      accept: z.string().default("Accept"),
+      decline: z.string().default("Decline"),
+      // The banner's accessible name.
+      label: z.string().default("Cookie consent"),
+      message: z
+        .string()
+        .default(
+          "We'd like to use cookies to understand how these docs are used."
+        ),
+      policy: z.string().default("Privacy policy"),
+      settings: z.string().default("Cookie settings"),
+    })
+    .prefault({}),
   content: z
     .object({
       // `<Component>`'s source tab.
@@ -89,7 +131,12 @@ const uiStringsObject = z.object({
       prop: z.string().default("Prop"),
       // `<Tabs dropdown>`: the accessible name of the tab picker.
       selectTab: z.string().default("Select tab"),
-      // `<Expandable>`'s toggle when it sets no `title`.
+      // `<View>`: the accessible name of the page's view picker.
+      selectView: z.string().default("Select view"),
+      // An expanded `expandable` code block's toggle.
+      showLess: z.string().default("Show less"),
+      // `<Expandable>`'s toggle when it sets no `title`, and a collapsed
+      // `expandable` code block's.
       showMore: z.string().default("Show more"),
       stars: z.string().default("Stars"),
       // An untitled tab's label; `{n}` is replaced with its position.
@@ -102,8 +149,11 @@ const uiStringsObject = z.object({
     .prefault({}),
   feedback: z
     .object({
+      // The written comment box after the rating (`feedback.comments`).
+      comment: z.string().default("Tell us more (optional)"),
       no: z.string().default("No"),
       question: z.string().default("Was this page helpful?"),
+      send: z.string().default("Send"),
       thanks: z.string().default("Thanks for your feedback!"),
       yes: z.string().default("Yes"),
     })
@@ -114,6 +164,36 @@ const uiStringsObject = z.object({
       untranslated: z.string().default("Not translated"),
     })
     .prefault({}),
+  narration: z
+    .object({
+      // Spoken, not shown: the cues that introduce a callout of each type, a
+      // step (`{n}` is its number), a tab (`{title}` is its label), and a
+      // collapsible section. End each with a full stop so it reads as its own
+      // sentence.
+      cueDanger: z.string().default("Danger."),
+      cueInfo: z.string().default("Info."),
+      cueNote: z.string().default("Note."),
+      cueSection: z.string().default("Expandable section."),
+      cueStep: z.string().default("Step {n}."),
+      cueSuccess: z.string().default("Success."),
+      cueTab: z.string().default("{title} tab."),
+      cueTip: z.string().default("Tip."),
+      cueWarning: z.string().default("Warning."),
+      error: z.string().default("The narration couldn't load."),
+      // Resumes following the sentence being read after the reader scrolls away.
+      follow: z.string().default("Follow along"),
+      label: z.string().default("Listen to this page"),
+      // The estimated listening time; `{n}` is whole minutes.
+      minutes: z.string().default("{n} min"),
+      next: z.string().default("Next sentence"),
+      pause: z.string().default("Pause"),
+      play: z.string().default("Play"),
+      previous: z.string().default("Previous sentence"),
+      progress: z.string().default("Narration progress"),
+      speed: z.string().default("Playback speed"),
+      stop: z.string().default("Stop listening"),
+    })
+    .prefault({}),
   nav: z
     .object({
       back: z.string().default("Back"),
@@ -128,7 +208,7 @@ const uiStringsObject = z.object({
       primary: z.string().default("Primary"),
       sections: z.string().default("Sections"),
       toggleNavigation: z.string().default("Toggle navigation"),
-      toggleTheme: z.string().default("Toggle color theme"),
+      toggleTheme: z.string().default("Toggle theme"),
     })
     .prefault({}),
   notFound: z
@@ -154,6 +234,8 @@ const uiStringsObject = z.object({
       next: z.string().default("Next"),
       pagination: z.string().default("Pagination"),
       previous: z.string().default("Previous"),
+      // The heading over a page's `related` links.
+      related: z.string().default("Related pages"),
       skipToContent: z.string().default("Skip to content"),
     })
     .prefault({}),

package/src/core/includes.ts

@@ -7,6 +7,7 @@ import type { FenceState } from "./code-fences.ts";
 import matter from "./frontmatter.ts";
 import { INLINE_CODE, MD_IMAGE, targetOffsetIn } from "./sources/normalize.ts";
 import type { Diagnostic } from "./types.ts";
+import { substituteVariables } from "./variables.ts";
 
 /**
  * Content includes: `<include>./relative.mdx</include>` on a line of its own
@@ -98,6 +99,12 @@ export interface IncludeAttributes {
   lang?: string;
   /** Fence meta string in code-block mode (e.g. `title="lib.ts"`). */
   meta?: string;
+  /**
+   * Every other attribute with a value: the snippet's own variables.
+   * `<include plan="Pro">` makes `{{plan}}` in the included file read `Pro`,
+   * ahead of any site-wide variable of the same name.
+   */
+  props?: Record<string, string>;
 }
 
 /** A parsed include statement. */
@@ -108,8 +115,8 @@ export interface IncludeStatement {
 
 /**
  * Parse one trimmed line as an include statement, or `null` when it isn't
- * one. Only `lang` and `meta` are meaningful; unknown attributes parse and
- * are ignored so a future attribute degrades gracefully on older versions.
+ * one. `lang` and `meta` shape a code include; every other attribute with a
+ * value becomes a prop, a variable scoped to the included file.
  */
 export const parseIncludeStatement = (
   line: string
@@ -128,6 +135,9 @@ export const parseIncludeStatement = (
     if (name === "meta" && value) {
       attributes.meta = value;
     }
+    if (name && name !== "lang" && name !== "meta" && value !== undefined) {
+      attributes.props = { ...attributes.props, [name]: value };
+    }
   }
   return { attributes, target: match.groups.target ?? "" };
 };
@@ -232,7 +242,7 @@ export const malformedIncludeDiagnostic = (
     "This <include> isn't a statement Blume can read, so the page shows it as written.",
   severity: "warning",
   suggestion:
-    "Write <include>./path.mdx</include> on a line of its own, or wrap it with the path on its own line and no blank lines; only lang and meta attributes are read.",
+    'Write <include>./path.mdx</include> on a line of its own, or wrap it with the path on its own line and no blank lines. Attributes take lowercase names and quoted values (plan="Pro"): lang and meta shape a code include, and any other is a prop the included file reads as {{name}}.',
 });
 
 /**
@@ -519,8 +529,15 @@ const expandStatement = async (
     lines.shift();
     origins.shift();
   }
+  // Props replace their `{{name}}` references line by line, so every line
+  // keeps its origin; they reach the file's own nested includes too.
+  const { props } = statement.attributes;
   return {
-    lines: rebaseImages(lines, dirname(path), dirname(filePath)),
+    lines: rebaseImages(
+      props ? lines.map((text) => substituteVariables(text, props)) : lines,
+      dirname(path),
+      dirname(filePath)
+    ),
     origins,
   };
 };

package/src/core/links.ts

@@ -10,6 +10,7 @@ import {
 import type { LocaleRouting } from "./i18n.ts";
 import { localizeLinkPath } from "./locale-links.ts";
 import { gradeExternal, probeAll } from "./probe.ts";
+import { isPatternPath, pathsUnderPattern } from "./redirect-patterns.ts";
 import type {
   ContentGraph,
   Diagnostic,
@@ -87,6 +88,8 @@ interface LinkContext {
   publicDir: string | null;
   /** Normalized `redirect.from` paths — valid targets that resolve at runtime. */
   redirects: Set<string>;
+  /** Pattern `redirect.from`s (`/beta/:slug*`), based like `redirects`. */
+  redirectPatterns: string[];
   routes: Set<string>;
 }
 
@@ -309,10 +312,13 @@ const checkPathLink = (
 ): LinkResult => {
   // Page routes carry the site-wide base; an absolute author path is written
   // as if mounted at root, so base it for the route lookup (idempotent — a
-  // relative link already resolved against the based `page.route`). A real
-  // route always wins over the asset-extension heuristic, so a dotted route
-  // (e.g. `/releases/v1.0`) isn't misread as a missing asset.
-  const authoredRoute = toRoute(withBasePath(ctx.basePath, resolved));
+  // relative link already resolved against the based `page.route`). A raw
+  // `<a href>` ships unbased, so it's looked up as written. A real route
+  // always wins over the asset-extension heuristic, so a dotted route (e.g.
+  // `/releases/v1.0`) isn't misread as a missing asset.
+  const authoredRoute = toRoute(
+    link.raw ? resolved : withBasePath(ctx.basePath, resolved)
+  );
   const route = servedRoute(authoredRoute, page, ctx);
   if (ctx.routes.has(route)) {
     return fragment ? checkAnchor(route, fragment, site, ctx, via) : null;
@@ -322,10 +328,16 @@ const checkPathLink = (
   if (ctx.extraRoutes.has(route)) {
     return null;
   }
-  // A configured `redirect.from` resolves at runtime, so it's a valid target.
+  // A configured `redirect.from`, or a path a pattern `from` covers, resolves
+  // at runtime, so it's a valid target.
   // Its destination (and any anchor there) is validated on its own page, so we
   // don't follow the redirect to check the fragment here.
-  if (ctx.redirects.has(route)) {
+  if (
+    ctx.redirects.has(route) ||
+    ctx.redirectPatterns.some(
+      (from) => pathsUnderPattern(from, [route]).length > 0
+    )
+  ) {
     return null;
   }
 
@@ -427,6 +439,12 @@ export interface FileRouteIndex {
    * into the reader's locale onto the fallback copy.
    */
   byDefaultNavPath: Map<string, string>;
+  /**
+   * A staged page's entry id (`<source>/<ref>`) → its route. A remote
+   * source's files have no path on disk, so a file link between two of them
+   * (`./02-errors.mdx`) resolves by entry id, as the rendered link does.
+   */
+  byEntryId: Map<string, string>;
 }
 
 /** The linking side of a file link: where the page's source lives. */
@@ -441,12 +459,19 @@ export const buildFileRouteIndex = (
 ): FileRouteIndex => {
   const bySource = new Map<string, string>();
   const byDefaultNavPath = new Map<string, string>();
+  const byEntryId = new Map<string, string>();
   for (const page of pages) {
-    const { sourcePath } = page;
-    if (!sourcePath || page.fallback) {
+    const { entryId, sourcePath } = page;
+    if (page.fallback) {
       continue;
     }
     const isDefault = page.locale === i18n?.defaultLocale;
+    if (entryId && (!byEntryId.has(entryId) || isDefault)) {
+      byEntryId.set(entryId, page.route);
+    }
+    if (!sourcePath) {
+      continue;
+    }
     if (!bySource.has(sourcePath) || isDefault) {
       bySource.set(sourcePath, page.route);
     }
@@ -454,7 +479,7 @@ export const buildFileRouteIndex = (
       byDefaultNavPath.set(normalize(page.navPath), page.route);
     }
   }
-  return { byDefaultNavPath, bySource };
+  return { byDefaultNavPath, byEntryId, bySource };
 };
 
 /**
@@ -483,11 +508,15 @@ const relativeTarget = (
   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;
+  const { entryId, navPath, sourcePath } = page;
+  let resolveFile: ((path: string) => string | undefined) | undefined;
+  if (sourcePath) {
+    resolveFile = (path) =>
+      routeOfLinkedFile(ctx.fileRoutes, { navPath, sourcePath }, path);
+  } else if (entryId) {
+    resolveFile = (path) =>
+      ctx.fileRoutes.byEntryId.get(normalize(join(dirname(entryId), path)));
+  }
   return (
     resolveRelativeHref(rawPath, base, resolveFile, (route) =>
       ctx.routes.has(route)
@@ -546,9 +575,14 @@ const classifyLink = (
     return fragment ? checkAnchor(page.route, fragment, site, ctx, via) : null;
   }
 
-  const resolved = rawPath.startsWith("/")
-    ? rawPath
-    : relativeTarget(page, rawPath, ctx);
+  let resolved = rawPath;
+  if (!rawPath.startsWith("/")) {
+    // A raw `<a href>` isn't rewritten, so the browser resolves it against
+    // the page's slashless URL: its parent directory, even on an index page.
+    resolved = link.raw
+      ? resolveRelative(page.route, rawPath, false)
+      : relativeTarget(page, rawPath, ctx);
+  }
   return checkPathLink(resolved, fragment, page, link, site, ctx, via);
 };
 
@@ -573,6 +607,8 @@ export const validateLinks = async (
     i18n?: LocaleRouting | null;
     publicDir: string | null;
     checkExternal?: boolean;
+    /** External URLs not to request (`--ignore`). Internal links are always checked. */
+    ignore?: (url: string) => boolean;
     /** Configured redirects; their `from` paths count as valid link targets. */
     redirects?: { from: string }[];
   }
@@ -585,6 +621,11 @@ export const validateLinks = async (
     fileRoutes: buildFileRouteIndex(graph.pages, options.i18n ?? null),
     i18n: options.i18n ?? null,
     publicDir: options.publicDir,
+    redirectPatterns: (options.redirects ?? []).flatMap((redirect) =>
+      isPatternPath(redirect.from)
+        ? [withBasePath(basePath, redirect.from)]
+        : []
+    ),
     redirects: new Set(
       (options.redirects ?? []).map((redirect) =>
         toRoute(withBasePath(basePath, redirect.from))
@@ -615,8 +656,11 @@ export const validateLinks = async (
     });
   }
 
-  if (options.checkExternal && external.length > 0) {
-    diagnostics.push(...(await checkExternalLinks(external)));
+  // `--ignore` names URLs that can't be checked from where this runs: a
+  // placeholder host, a local server, a site that turns bots away.
+  const probed = external.filter((ref) => !options.ignore?.(ref.url));
+  if (options.checkExternal && probed.length > 0) {
+    diagnostics.push(...(await checkExternalLinks(probed)));
   }
 
   // A partial spliced into several pages (or every locale of one) yields the

package/src/core/localizable.ts

@@ -0,0 +1,26 @@
+import type { LocalizableLabel } from "./schema.ts";
+
+/** A label is either one string for every locale or a per-locale map. */
+const isSingleLabel = (label: LocalizableLabel): label is string =>
+  typeof label === "string";
+
+/**
+ * Resolve a possibly-per-locale label to the string a locale renders: the
+ * active locale's entry, else the default locale's, else the map's first
+ * entry (which is also what a single-locale site gets).
+ */
+export const resolveLocalizable = (
+  label: LocalizableLabel,
+  locale?: string,
+  defaultLocale?: string
+): string => {
+  if (isSingleLabel(label)) {
+    return label;
+  }
+  return (
+    (locale === undefined ? undefined : label[locale]) ??
+    (defaultLocale === undefined ? undefined : label[defaultLocale]) ??
+    Object.values(label)[0] ??
+    ""
+  );
+};

package/src/core/navigation.ts

@@ -3,6 +3,7 @@ import { extname } from "pathe";
 import { stripBasePath, withBasePath } from "./base-path.ts";
 import { orderingPrefix, stripOrderingPrefix } from "./ordering-prefix.ts";
 import type {
+  DirectoryMode,
   FolderMeta,
   SidebarDisplay,
   SidebarItemConfig,
@@ -202,6 +203,7 @@ interface MutableGroup {
   label: string;
   icon?: string;
   collapsed?: boolean;
+  directory?: DirectoryMode;
   display?: SidebarDisplay;
   order: number;
   /** Whether `order` is the node's position in its folder meta `pages` list. */
@@ -305,9 +307,19 @@ interface FallbackFolderMeta {
   meta: (path: string) => FolderMeta | undefined;
 }
 
+/** A folder meta's own fields onto its group, over what the folder implied. */
+const applyMetaFields = (group: MutableGroup, meta: FolderMeta): void => {
+  group.label = meta.title ?? group.label;
+  group.icon = meta.icon ?? group.icon;
+  group.order = meta.order ?? group.order;
+  group.collapsed = meta.collapsed ?? group.collapsed;
+  group.directory = meta.directory ?? group.directory;
+};
+
 /**
- * Apply folder meta (title/order/icon/collapsed/display and explicit page
- * order), plus the index-frontmatter display sugar collected per folder path.
+ * Apply folder meta (title/order/icon/collapsed/display/directory and
+ * explicit page order), plus the index-frontmatter display sugar collected
+ * per folder path.
  */
 const applyFolderMeta = (
   group: MutableGroup,
@@ -346,10 +358,7 @@ const applyFolderMeta = (
     (mirrored ? fallback.indexDisplay.get(group.path) : undefined) ??
     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;
+    applyMetaFields(group, meta);
   }
 
   for (const child of group.children) {
@@ -630,7 +639,15 @@ const hoistTabSections = (
   }
 };
 
-const toNavNode = (node: MutableNode, display: SidebarDisplay): NavNode => {
+/**
+ * A group's directory mode: its own, else the nearest one set above it (see
+ * `directory` in `schema.ts`).
+ */
+const toNavNode = (
+  node: MutableNode,
+  display: SidebarDisplay,
+  inheritedDirectory?: DirectoryMode
+): NavNode => {
   if (node.kind === "page") {
     return {
       badge: node.badge,
@@ -643,9 +660,13 @@ const toNavNode = (node: MutableNode, display: SidebarDisplay): NavNode => {
       route: node.route,
     };
   }
+  const directory = node.directory ?? inheritedDirectory;
   return {
-    children: node.children.map((child) => toNavNode(child, display)),
+    children: node.children.map((child) =>
+      toNavNode(child, display, directory)
+    ),
     collapsed: node.collapsed,
+    directory,
     display: node.display ?? display,
     icon: node.icon,
     kind: "group",
@@ -805,7 +826,9 @@ const buildFileSystemSidebar = (
   sortNodes(root.children, diagnostics);
   hoistPages(root.children, display, true);
   hoistTabSections(root.children, tabPaths, display);
-  return root.children.map((child) => toNavNode(child, display));
+  return root.children.map((child) =>
+    toNavNode(child, display, root.directory)
+  );
 };
 
 /**
@@ -932,16 +955,24 @@ const buildConfigSidebar = (
   items: SidebarItemConfig[],
   byRoute: Map<string, PageRecord>,
   display: SidebarDisplay,
-  basePath: string
+  basePath: string,
+  inheritedDirectory?: DirectoryMode
 ): NavNode[] => {
   const nodes: NavNode[] = [];
   for (const item of items) {
     if (!isPageRef(item) && item.items) {
+      const directory = item.directory ?? inheritedDirectory;
       nodes.push({
         badge: item.badge,
-        children: buildConfigSidebar(item.items, byRoute, display, basePath),
+        children: buildConfigSidebar(
+          item.items,
+          byRoute,
+          display,
+          basePath,
+          directory
+        ),
         collapsed: item.collapsed,
-        directory: item.directory,
+        directory,
         display: item.display ?? display,
         icon: item.icon,
         kind: "group",