blume 2.0.1 → 2.0.3

package/src/core/navigation.ts

@@ -1,6 +1,7 @@
 import { extname } from "pathe";
 
 import { stripBasePath, withBasePath } from "./base-path.ts";
+import { orderingPrefix, stripOrderingPrefix } from "./ordering-prefix.ts";
 import type {
   FolderMeta,
   SidebarDisplay,
@@ -17,7 +18,6 @@ import type {
   PageRecord,
 } from "./types.ts";
 
-const NUMERIC_PREFIX = /^(?<order>\d+)[-_.]/u;
 const GROUP_FOLDER = /^\((?<label>.+)\)$/u;
 const WORD_SPLIT = /[-_]/u;
 
@@ -94,27 +94,50 @@ const WORD_FORMS = new Map([
   ["yaml", "YAML"],
 ]);
 
+/**
+ * Capitalize one word of a slug-like name for display, spelling the acronyms
+ * and brand casings in {@link WORD_FORMS} their own way (`api` → "API").
+ * Shared with page titles derived from file names, so a page and a folder
+ * named alike read alike.
+ */
+export const titleWord = (word: string): string =>
+  WORD_FORMS.get(word) ?? word.charAt(0).toUpperCase() + word.slice(1);
+
 const humanize = (segment: string): string =>
-  segment
-    .replace(NUMERIC_PREFIX, "")
+  stripOrderingPrefix(segment)
     .split(WORD_SPLIT)
     .filter(Boolean)
-    .map(
-      (word) =>
-        WORD_FORMS.get(word) ?? word.charAt(0).toUpperCase() + word.slice(1)
-    )
+    .map(titleWord)
     .join(" ");
 
 const numericOrder = (segment: string): number => {
-  const value = segment.match(NUMERIC_PREFIX)?.groups?.order;
+  const value = orderingPrefix(segment);
   return value ? Math.trunc(Number(value)) : Number.POSITIVE_INFINITY;
 };
 
+/**
+ * The name inside a group folder's parentheses — `(guides)`, or `01-(guides)`
+ * with its ordering prefix outside them — else undefined. A prefix written
+ * inside (`(01-guides)`) stays in the name, where it sorts and drops like any
+ * folder's.
+ */
+const groupName = (raw: string): string | undefined =>
+  (raw.match(GROUP_FOLDER) ?? stripOrderingPrefix(raw).match(GROUP_FOLDER))
+    ?.groups?.label;
+
+/**
+ * A folder's sidebar order: its ordering prefix, or — for a group folder
+ * without one outside the parentheses — the prefix inside them, so
+ * `01-(guides)` and `(01-guides)` both sort like `01-guides`.
+ */
+const folderOrder = (raw: string): number =>
+  numericOrder(
+    orderingPrefix(raw) === undefined ? (groupName(raw) ?? raw) : raw
+  );
+
 /** The nav key of a raw path segment: group label or numeric-stripped name. */
-const segmentKey = (raw: string): string => {
-  const group = raw.match(GROUP_FOLDER)?.groups?.label;
-  return (group ?? raw).replace(NUMERIC_PREFIX, "");
-};
+const segmentKey = (raw: string): string =>
+  stripOrderingPrefix(groupName(raw) ?? raw);
 
 /**
  * Whether a filename stem is a directory index, ignoring an ordering prefix:
@@ -122,7 +145,7 @@ const segmentKey = (raw: string): string => {
  * exactly like `index` and must be treated as one here too.
  */
 const isIndexStem = (stem: string): boolean =>
-  stem.replace(NUMERIC_PREFIX, "") === "index";
+  stripOrderingPrefix(stem) === "index";
 
 /** A filename's stem: the name with its extension stripped. */
 const stemOf = (filename: string): string =>
@@ -158,6 +181,8 @@ interface MutablePage {
    * so they're excluded from the duplicate-order diagnostic.
    */
   orderIsAuthored: boolean;
+  /** Whether `order` is the node's position in its folder meta `pages` list. */
+  ranked?: boolean;
 }
 
 interface MutableGroup {
@@ -166,6 +191,12 @@ interface MutableGroup {
   path: string;
   /** The group's URL path (folder route prefix); set as pages are inserted. */
   routePath?: string;
+  /**
+   * The group's URL path read off its folder names, from a page whose
+   * frontmatter `slug` moved it off the folder's path. Fills `routePath` only
+   * when no other page under the folder supplies one.
+   */
+  folderPath?: string;
   /** The folder's index page route, when it has one; the group row's link. */
   route?: string;
   label: string;
@@ -173,6 +204,8 @@ interface MutableGroup {
   collapsed?: boolean;
   display?: SidebarDisplay;
   order: number;
+  /** Whether `order` is the node's position in its folder meta `pages` list. */
+  ranked?: boolean;
   children: MutableNode[];
   index: Map<string, MutableGroup>;
 }
@@ -206,8 +239,8 @@ const ensureGroup = (
   const group = createGroup(
     segmentKey(rawSegment),
     path,
-    humanize(rawSegment.match(GROUP_FOLDER)?.groups?.label ?? rawSegment),
-    numericOrder(rawSegment)
+    humanize(groupName(rawSegment) ?? rawSegment),
+    folderOrder(rawSegment)
   );
   parent.index.set(rawSegment, group);
   parent.children.push(group);
@@ -240,7 +273,8 @@ const pageOrder = (page: PageRecord, filename: string): PageOrder => {
     }
   }
   // An undated changelog entry's numeric filename prefix is usually a date
-  // (`2024-01-05-release.md`) rather than a rank, so it is derived too.
+  // (`20240105-release.md`) rather than a rank, so it is derived too. An ISO
+  // date (`2024-01-05-release.md`) is no ordering prefix at all.
   const order = numericOrder(filename);
   return {
     order,
@@ -260,6 +294,17 @@ const metaKey = (path: string, metaPrefix: string): string => {
   return path ? `${metaPrefix}/${path}` : metaPrefix;
 };
 
+/**
+ * What an i18n locale's tree mirrors from the fallback locale for a folder it
+ * has no meta of its own for: the fallback locale's folder meta, and the
+ * `sidebar.display` of a fallback-filled index page. Empty for the fallback
+ * locale itself and for single-locale sites.
+ */
+interface FallbackFolderMeta {
+  indexDisplay: Map<string, SidebarDisplay>;
+  meta: (path: string) => FolderMeta | undefined;
+}
+
 /**
  * Apply folder meta (title/order/icon/collapsed/display and explicit page
  * order), plus the index-frontmatter display sugar collected per folder path.
@@ -271,41 +316,40 @@ const applyFolderMeta = (
   metaPrefix: string,
   sharedMetaPrefix: string,
   indexDisplay: Map<string, SidebarDisplay>,
-  indexRoute: Map<string, string>
+  indexRoute: Map<string, string>,
+  fallback: FallbackFolderMeta
 ): void => {
   // A folder with an index page links its group row to it — the same shape
   // as an explicit-config group's `root`, and the only sidebar link to the
   // section's own page once the index row is hidden. Index-less folders keep
   // no link: their row would 404.
   group.route = indexRoute.get(group.path);
+  group.routePath ??= group.folderPath;
   // Locale-specific meta wins; a shared `meta.$.*` (keyed by the locale-stripped
   // group path — version-prefixed inside a snapshot) applies to every locale
   // otherwise.
-  const meta =
+  const localeMeta =
     folderMeta.get(metaKey(group.path, metaPrefix)) ??
     sharedMeta.get(metaKey(group.path, sharedMetaPrefix));
+  // A locale with neither mirrors the fallback locale's group, the way its
+  // tree mirrors that locale's untranslated pages: the fallback's folder
+  // meta, and — ahead of it, as in the fallback's own tree — the display its
+  // fallback-filled index page sets. A locale's own meta owns its group, so
+  // the fallback's index frontmatter never overrides it.
+  const mirrored = localeMeta === undefined;
+  const meta = localeMeta ?? fallback.meta(group.path);
   // The group's own render mode, resolved index frontmatter first, then folder
   // meta; `toNavNode` falls back to the global mode. Applies to this group
   // only — nested subgroups resolve their own value through the same chain.
-  group.display = indexDisplay.get(group.path) ?? meta?.display;
+  group.display =
+    indexDisplay.get(group.path) ??
+    (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;
-
-    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) {
@@ -317,10 +361,29 @@ const applyFolderMeta = (
         metaPrefix,
         sharedMetaPrefix,
         indexDisplay,
-        indexRoute
+        indexRoute,
+        fallback
       );
     }
   }
+
+  // Ranked after the children resolved their own meta: the `pages` list is
+  // this folder's word on its children's order, so it wins over a listed
+  // subfolder's own `order` just as it wins over a listed page's
+  // `sidebar.order`.
+  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;
+        child.ranked = true;
+        if (child.kind === "page") {
+          child.orderIsAuthored = true;
+        }
+      }
+    }
+  }
 };
 
 /**
@@ -457,22 +520,27 @@ const isAuthoredOrder = (node: MutableNode): boolean =>
  * excluded: that's the common, intentional case of "just sort alphabetically."
  * So is a derived, non-authored order (e.g. two changelog entries published
  * on the same day) — not an authoring mistake.
+ *
+ * A folder meta `pages` rank is a list position, not a number the author
+ * picked, so it only ties with another rank: a listed page at position 1
+ * beside an unlisted `01-setup.md` is not a conflict anyone wrote.
  */
 const duplicateOrderDiagnostics = (nodes: MutableNode[]): Diagnostic[] => {
-  const byOrder = new Map<number, MutableNode[]>();
+  const byOrder = new Map<string, { order: number; tied: MutableNode[] }>();
   for (const node of nodes) {
     if (!Number.isFinite(node.order) || !isAuthoredOrder(node)) {
       continue;
     }
-    const tied = byOrder.get(node.order);
-    if (tied) {
-      tied.push(node);
+    const key = `${node.ranked === true}:${node.order}`;
+    const entry = byOrder.get(key);
+    if (entry) {
+      entry.tied.push(node);
     } else {
-      byOrder.set(node.order, [node]);
+      byOrder.set(key, { order: node.order, tied: [node] });
     }
   }
   const diagnostics: Diagnostic[] = [];
-  for (const [order, tied] of byOrder) {
+  for (const { order, tied } of byOrder.values()) {
     if (tied.length > 1) {
       const names = tied.map((node) => `"${node.label}"`);
       const list =
@@ -596,13 +664,23 @@ const buildFileSystemSidebar = (
   sharedMetaPrefix: string,
   display: SidebarDisplay,
   tabPaths: Set<string>,
-  diagnostics: Diagnostic[] = []
+  diagnostics: Diagnostic[] = [],
+  fallbackMetaPrefix?: string
 ): NavNode[] => {
   const root = createGroup("", "", "", 0);
   // Folder path -> `sidebar.display` from that folder's index page frontmatter.
   // Collected before the hidden filter (like the title check): hiding the index
   // row from the panel shouldn't stop it configuring its group.
   const indexDisplay = new Map<string, SidebarDisplay>();
+  // What a group with no meta of this locale's mirrors from the fallback
+  // locale (see `applyFolderMeta`).
+  const fallback: FallbackFolderMeta = {
+    indexDisplay: new Map(),
+    meta: (path) =>
+      fallbackMetaPrefix === undefined
+        ? undefined
+        : folderMeta.get(metaKey(path, fallbackMetaPrefix)),
+  };
   // Folder path -> that folder's index page route, for the group row's link.
   // Also collected before the hidden filter: hiding the index row is how a
   // site drops the duplicate label under a linked header, so the link must
@@ -631,12 +709,16 @@ const buildFileSystemSidebar = (
       if (diagnostic) {
         diagnostics.push(diagnostic);
       }
-      // Fallback-filled pages are exempt (like the title check above): their
-      // frontmatter belongs to the fallback locale, and letting it through
-      // would override this locale's own authored `meta.ts` display — then
-      // silently flip again the day the index gets translated.
-      if (page.meta.sidebar.display && !page.fallback) {
-        indexDisplay.set(dirs.join("/"), page.meta.sidebar.display);
+      // A fallback-filled index's display is kept apart (like the title check
+      // above exempts it): its frontmatter belongs to the fallback locale, so
+      // it only speaks for a group this locale has no meta for — letting it
+      // override this locale's own authored `meta.ts` display would silently
+      // flip again the day the index gets translated.
+      if (page.meta.sidebar.display) {
+        (page.fallback ? fallback.indexDisplay : indexDisplay).set(
+          dirs.join("/"),
+          page.meta.sidebar.display
+        );
       }
       if (dirs.length > 0) {
         indexRoute.set(dirs.join("/"), page.route);
@@ -658,17 +740,39 @@ const buildFileSystemSidebar = (
     const folderParts = isIndexStem(stem)
       ? routeSegments
       : routeSegments.slice(0, -1);
-    const routeDirCount = dirs.filter((dir) => !GROUP_FOLDER.test(dir)).length;
+    const routeDirCount = dirs.filter(
+      (dir) => groupName(dir) === undefined
+    ).length;
     const offset = Math.max(0, folderParts.length - routeDirCount);
+    // A frontmatter `slug` publishes the page away from its folder, so its
+    // route says nothing about where the folder lives (`guides/a.md` with
+    // `slug: install` is `/install`). Its groups read their path off the folder
+    // names instead, behind the route's leading base/locale/version segments
+    // (whatever precedes the slug's own `versionKey`), and only where no
+    // other page under the folder supplies one.
+    const slugged = page.meta.slug !== undefined;
+    const leading = routeSegments.slice(
+      0,
+      Math.max(
+        0,
+        routeSegments.length - page.versionKey.split("/").filter(Boolean).length
+      )
+    );
 
     let parent = root;
     let consumed = offset;
+    const folders: string[] = [];
     for (const dir of dirs) {
       parent = ensureGroup(parent, dir);
-      if (!GROUP_FOLDER.test(dir)) {
+      if (groupName(dir) === undefined) {
         consumed += 1;
+        folders.push(stripOrderingPrefix(dir));
+      }
+      if (slugged) {
+        parent.folderPath ??= `/${[...leading, ...folders].join("/")}`;
+      } else {
+        parent.routePath ??= `/${folderParts.slice(0, consumed).join("/")}`;
       }
-      parent.routePath ??= `/${folderParts.slice(0, consumed).join("/")}`;
     }
 
     const { order, orderIsAuthored } = pageOrder(page, filename);
@@ -695,7 +799,8 @@ const buildFileSystemSidebar = (
     metaPrefix,
     sharedMetaPrefix,
     indexDisplay,
-    indexRoute
+    indexRoute,
+    fallback
   );
   sortNodes(root.children, diagnostics);
   hoistPages(root.children, display, true);
@@ -703,7 +808,11 @@ const buildFileSystemSidebar = (
   return root.children.map((child) => toNavNode(child, display));
 };
 
-const normalizeRef = (ref: string): string => {
+/**
+ * An explicit-sidebar ref (`"guides/"`, `"/guides/index"`, `"index"`) in the
+ * slashless route form pages are keyed by (`/guides`, `/`).
+ */
+export const normalizeRef = (ref: string): string => {
   if (ref === "index") {
     return "/";
   }
@@ -734,9 +843,36 @@ const routeForRef = (
 };
 
 /** An explicit-config sidebar item written as a bare page-ref string. */
-const isPageRef = (item: SidebarItemConfig): item is string =>
+export const isPageRef = (item: SidebarItemConfig): item is string =>
   typeof item === "string";
 
+/**
+ * Pages keyed the way explicit-sidebar refs look them up: by the
+ * locale-agnostic `translationKey` under i18n (`byLogical`), so one authored
+ * sidebar maps onto every locale's pages, else by route. Refs are authored as
+ * if mounted at root while `page.route` carries the base, so each page is also
+ * aliased under its base-less route (the `translationKey` is base-less
+ * already).
+ */
+export const pagesByRef = (
+  pages: PageRecord[],
+  basePath: string,
+  byLogical: boolean
+): Map<string, PageRecord> => {
+  const byRoute = new Map(
+    pages.map((page) => [byLogical ? page.translationKey : page.route, page])
+  );
+  if (basePath && !byLogical) {
+    for (const page of pages) {
+      const bare = stripBasePath(basePath, page.route);
+      if (!byRoute.has(bare)) {
+        byRoute.set(bare, page);
+      }
+    }
+  }
+  return byRoute;
+};
+
 /**
  * Convert one non-group explicit-config sidebar item (string ref, `root`, or
  * `href`) to a nav node, or null to skip. Group items (`item.items`) are handled
@@ -822,6 +958,35 @@ const buildConfigSidebar = (
   return nodes;
 };
 
+/**
+ * The two roots a tab's target resolves between, both based: `tabs`, the root
+ * of the space tab paths are written in (the current docs' localized root,
+ * `/fr`), and `tree`, the root this tree's pages live under — the same route,
+ * except in an archived version tree (`/fr/v1.0`).
+ */
+interface TabRoots {
+  tabs: string;
+  tree: string;
+}
+
+/**
+ * `path` relative to `root` (`/fr/guides` under `/fr` is `/guides`, the root
+ * itself is `/`), or undefined when it isn't under it.
+ */
+const pathUnder = (path: string, root: string): string | undefined => {
+  if (root === "/") {
+    return path;
+  }
+  if (path === root) {
+    return "/";
+  }
+  return path.startsWith(`${root}/`) ? path.slice(root.length) : undefined;
+};
+
+/** Mount a root-relative remainder (`/guides`, never `/`) under `root`. */
+const joinRoute = (root: string, rest: string): string =>
+  root === "/" ? rest : `${root}${rest}`;
+
 /**
  * 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
@@ -832,30 +997,40 @@ const buildConfigSidebar = (
  *
  * 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.
+ * site) or a locale prefix, while tab paths arrive based and localized
+ * (`/docs/fr/changelog`). So when the tab path is neither an outside route nor
+ * a tree node, its base-less and then its root-relative form (`/changelog`)
+ * are checked against the outside routes before the section's first page
+ * wins.
+ *
+ * In an archived version tree the section is looked up under the versioned
+ * root (`/v1.0/guides`), where that tree's pages live — tab paths stay in
+ * current-docs space, where nothing in the tree could match.
  */
 const resolveTabHref = (
   sidebar: NavNode[],
   path: string,
   extraRoutes: ReadonlySet<string>,
-  basePath: string
+  basePath: string,
+  roots: TabRoots
 ): string => {
   if (extraRoutes.has(path)) {
     return path;
   }
+  const rest = pathUnder(path, roots.tabs);
+  const section =
+    rest === undefined || rest === "/" ? path : joinRoute(roots.tree, rest);
   let first: string | undefined;
   const walk = (nodes: NavNode[]): boolean => {
     for (const node of nodes) {
       const { route } = node;
-      if (route === path) {
+      if (route === section) {
         return true;
       }
       if (
         first === undefined &&
         route !== undefined &&
-        route.startsWith(`${path}/`)
+        route.startsWith(`${section}/`)
       ) {
         first = route;
       }
@@ -866,10 +1041,16 @@ const resolveTabHref = (
     return false;
   };
   if (walk(sidebar)) {
-    return path;
+    return section;
   }
   const bare = stripBasePath(basePath, path);
-  return extraRoutes.has(bare) ? bare : (first ?? path);
+  if (extraRoutes.has(bare)) {
+    return bare;
+  }
+  if (rest !== undefined && extraRoutes.has(rest)) {
+    return rest;
+  }
+  return first ?? path;
 };
 
 /**
@@ -884,11 +1065,13 @@ const withTabHrefs = (
   tabs: NavTab[],
   sidebar: NavNode[],
   extraRoutes: ReadonlySet<string>,
-  basePath: string
+  basePath: string,
+  roots: TabRoots
 ): NavTab[] =>
   tabs.map((tab) => {
     const href =
-      tab.href ?? resolveTabHref(sidebar, tab.path, extraRoutes, basePath);
+      tab.href ??
+      resolveTabHref(sidebar, tab.path, extraRoutes, basePath, roots);
     return href === tab.path ? tab : { ...tab, href };
   });
 
@@ -978,6 +1161,13 @@ export const buildNavigation = (
      * group path, e.g. `fr`, `v1.0`, or `v1.0/fr`.
      */
     metaPrefix?: string;
+    /**
+     * Folder-meta lookup prefix of the i18n fallback locale, whose untranslated
+     * pages pad this tree (`""` for the default locale of the current
+     * version). A group with no meta of this locale's mirrors the fallback
+     * locale's. Unset for the fallback locale itself, and without i18n.
+     */
+    fallbackMetaPrefix?: string;
     /**
      * Prefix for shared `meta.$.*` lookups — the version dir inside a
      * snapshot (`v1.0`), since shared meta is locale-agnostic but still
@@ -999,6 +1189,14 @@ export const buildNavigation = (
      * scoping.
      */
     localizedRoot?: string;
+    /**
+     * The root of the space tab paths are written in, before `basePath`: the
+     * current docs' localized root (`"/"`, `/fr`). Defaults to
+     * `localizedRoot`; an archived version tree passes it because its own
+     * root is versionized (`/fr/v1.0`) while tab paths are not, so a tab's
+     * section can be found under the version.
+     */
+    tabRoot?: string;
     /**
      * Sink for diagnostics produced while building the tree (duplicate sidebar
      * `order` values, index-page title/folder-meta-title mismatches). Pushed
@@ -1027,24 +1225,7 @@ export const buildNavigation = (
     basePath,
     options
   );
-  const byRoute = new Map(
-    pages.map((page) => [
-      options.refByLogical ? page.translationKey : page.route,
-      page,
-    ])
-  );
-  // Explicit-sidebar refs (`"foo/index"`) are authored as if mounted at root,
-  // but `page.route` carries the base — alias each page under its base-less
-  // route so a bare ref still resolves. (The i18n `refByLogical` map is already
-  // keyed by the base-less `translationKey`, so it needs no alias.)
-  if (basePath && !options.refByLogical) {
-    for (const page of pages) {
-      const bare = stripBasePath(basePath, page.route);
-      if (!byRoute.has(bare)) {
-        byRoute.set(bare, page);
-      }
-    }
-  }
+  const byRoute = pagesByRef(pages, basePath, Boolean(options.refByLogical));
 
   // A tab pointing at the tree root spans the whole sidebar rather than one
   // section, so it must not feed tab-section hoisting. `tabs` carries final
@@ -1057,6 +1238,13 @@ export const buildNavigation = (
   // paths stay in current-docs space, so root-tab checks use `isRootTab`
   // containment, not equality.
   const rootTabPath = withBasePath(basePath, options.localizedRoot ?? "/");
+  const tabRoots: TabRoots = {
+    tabs: withBasePath(
+      basePath,
+      options.tabRoot ?? options.localizedRoot ?? "/"
+    ),
+    tree: rootTabPath,
+  };
 
   // Emitted here, before the sidebar-mode branch: an explicit config sidebar
   // ignores a stray `sidebar.display` just like the filesystem sidebar does
@@ -1080,7 +1268,7 @@ export const buildNavigation = (
       root: rootTabPath,
       selectors,
       sidebar,
-      tabs: withTabHrefs(tabs, sidebar, extraRoutes, basePath),
+      tabs: withTabHrefs(tabs, sidebar, extraRoutes, basePath, tabRoots),
     };
   }
 
@@ -1094,7 +1282,8 @@ export const buildNavigation = (
     new Set(
       tabs.flatMap((tab) => (isRootTab(tab, rootTabPath) ? [] : [tab.path]))
     ),
-    diagnostics
+    diagnostics,
+    options.fallbackMetaPrefix
   );
   return {
     actions,
@@ -1103,6 +1292,6 @@ export const buildNavigation = (
     root: rootTabPath,
     selectors,
     sidebar,
-    tabs: withTabHrefs(tabs, sidebar, extraRoutes, basePath),
+    tabs: withTabHrefs(tabs, sidebar, extraRoutes, basePath, tabRoots),
   };
 };

package/src/core/ordering-prefix.ts

@@ -0,0 +1,27 @@
+/**
+ * A file or folder name's ordering prefix: digits, then a `-`, `_`, or `.`
+ * separator (`01-intro`, `2_setup`). It sorts the generated sidebar and is
+ * dropped from the route.
+ */
+const ORDERING_PREFIX = /^(?<order>\d+)[-_.]/u;
+
+/**
+ * Digit-led names that are names, not orders, and stay whole: a version
+ * (`1.2.0`, `2.0`), which a `1.` prefix would split into `2.0`, and an ISO date
+ * (`2024-01-05`, `2024-01-05-first-post`), whose year would sort the sidebar
+ * and leave only `01-05…` of the route.
+ */
+const NOT_AN_ORDER = /^(?:\d+\.\d|\d{4}-\d{2}-\d{2}(?:[-_.]|$))/u;
+
+/** The digits of `name`'s ordering prefix (`01` of `01-intro`), if it has one. */
+export const orderingPrefix = (name: string): string | undefined =>
+  NOT_AN_ORDER.test(name)
+    ? undefined
+    : name.match(ORDERING_PREFIX)?.groups?.order;
+
+/** `name` without its ordering prefix (`01-intro` -> `intro`). */
+export const stripOrderingPrefix = (name: string): string => {
+  const order = orderingPrefix(name);
+  // The prefix is the digits plus their one-character separator.
+  return order === undefined ? name : name.slice(order.length + 1);
+};