blume 1.1.1 → 1.1.2

package/src/core/navigation.ts

@@ -707,6 +707,15 @@ export const buildNavigation = (
     }
   }
 
+  // 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
+  // paths (localized, then based), so the root is compared in the same space —
+  // a root-level `(group)` folder's routePath is exactly the based/localized
+  // prefix (`/docs`, `/fr`) and a bare `"/"` check would miss the match (or,
+  // under a base, falsely scope a group named like the prefix). Carried on the
+  // returned navigation so render-time scoping compares in the same space too.
+  const rootTabPath = withBasePath(basePath, options.localizedRoot ?? "/");
+
   if (options.sidebar) {
     const sidebar = buildConfigSidebar(
       options.sidebar,
@@ -716,19 +725,13 @@ export const buildNavigation = (
     );
     return {
       featured,
+      root: rootTabPath,
       selectors,
       sidebar,
       tabs: withTabHrefs(tabs, sidebar),
     };
   }
 
-  // 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
-  // paths (localized, then based), so the root is compared in the same space —
-  // a root-level `(group)` folder's routePath is exactly the based/localized
-  // prefix (`/docs`, `/fr`) and a bare `"/"` check would miss the match (or,
-  // under a base, falsely scope a group named like the prefix).
-  const rootTabPath = withBasePath(basePath, options.localizedRoot ?? "/");
   const sidebar = buildFileSystemSidebar(
     pages,
     options.folderMeta,
@@ -742,6 +745,7 @@ export const buildNavigation = (
   );
   return {
     featured,
+    root: rootTabPath,
     selectors,
     sidebar,
     tabs: withTabHrefs(tabs, sidebar),

package/src/core/schema.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 
 import type { ComponentMarkdown } from "../ai/component-markdown.ts";
+import type { CodeTheme } from "../markdown/themes.ts";
 import { normalizeRoute } from "../openapi/references.ts";
 import { normalizeXHandle } from "../seo/x-handle.ts";
 import { FONT_SLUGS, isFontSlug } from "../theme/fonts.ts";
@@ -950,9 +951,38 @@ const githubConfigSchema = z.strictObject({
   repo: z.string(),
 });
 
+const codeThemeSchema = z.custom<CodeTheme>((value) => {
+  if (typeof value === "string") {
+    return true;
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  // Token rules live in `settings` (Shiki's canonical field, also the TextMate
+  // form themes like createCssVariablesTheme() produce) or `tokenColors` (the
+  // VS Code spelling Shiki falls back to). A colors-only theme (editor fg/bg,
+  // no token rules) is also valid — Shiki renders it from `colors` alone. Each
+  // field present must have the right shape, and at least one must be present.
+  const theme = value as Record<string, unknown>;
+  const settingsValid =
+    theme.settings === undefined || Array.isArray(theme.settings);
+  const tokenColorsValid =
+    theme.tokenColors === undefined || Array.isArray(theme.tokenColors);
+  const colorsValid =
+    theme.colors === undefined ||
+    (typeof theme.colors === "object" &&
+      theme.colors !== null &&
+      !Array.isArray(theme.colors));
+  const hasContent =
+    theme.settings !== undefined ||
+    theme.tokenColors !== undefined ||
+    theme.colors !== undefined;
+  return settingsValid && tokenColorsValid && colorsValid && hasContent;
+}, "Expected a Shiki theme name or custom theme object");
+
 const codeBlockThemeSchema = z.strictObject({
-  dark: z.string().default("github-dark"),
-  light: z.string().default("github-light"),
+  dark: codeThemeSchema.default("github-dark"),
+  light: codeThemeSchema.default("github-light"),
 });
 
 const codeBlocksConfigSchema = z.strictObject({

package/src/core/types.ts

@@ -227,6 +227,13 @@ export interface Navigation {
   tabs: NavTab[];
   selectors: NavSelector[];
   sidebar: NavNode[];
+  /**
+   * The tree root in final path space — localized and based (`/`, `/en`,
+   * `/docs`). Tab paths arrive in the same space, so the tab sitting at this
+   * path spans the whole tree and must be scoped as the root tab, not as a
+   * section tab. Absent on older serialized graphs; treat as `/`.
+   */
+  root?: string;
   /** Pinned links shown above the sidebar sections, unscoped by tab. */
   featured: FeaturedLink[];
   /** Repo URL for the header link, or null when hidden (`navigation.repo`). */

package/src/markdown/index.ts

@@ -21,6 +21,8 @@ import { tableWrapPlugin } from "./table-wrap.ts";
 import { DEFAULT_CODE_THEMES } from "./themes.ts";
 import type { CodeThemes } from "./themes.ts";
 
+export type { CodeTheme, CodeThemes } from "./themes.ts";
+
 /** A Shiki transformer, derived from the upstream factories' return type. */
 type ShikiTransformer = ReturnType<typeof transformerNotationDiff>;
 

package/src/markdown/inline-code.ts

@@ -64,7 +64,7 @@ type InlineHighlighter = (
     defaultColor: false;
     lang: string;
     structure: "inline";
-    themes: { dark: string; light: string };
+    themes: CodeThemes;
   }
 ) => Promise<{ children: HastNode[] }>;
 

package/src/markdown/themes.ts

@@ -6,6 +6,11 @@
  * single home for the github fallback used when nothing is configured.
  */
 
+import type { ThemeRegistrationAny } from "shiki";
+
+/** A bundled Shiki theme name or an inline custom Shiki theme definition. */
+export type CodeTheme = string | ThemeRegistrationAny;
+
 /**
  * A light/dark Shiki theme pair (`markdown.codeBlocks.theme`). A `type` (not an
  * `interface`) so it keeps the implicit index signature Shiki's `themes`
@@ -13,8 +18,8 @@
  */
 // oxlint-disable-next-line typescript/consistent-type-definitions -- interface loses the implicit index signature Shiki's `themes` param needs
 export type CodeThemes = {
-  dark: string;
-  light: string;
+  dark: CodeTheme;
+  light: CodeTheme;
 };
 
 /** The default pair, used when `markdown.codeBlocks.theme` is unset. */