blume 0.1.3 → 0.1.5

package/src/astro/templates.ts

@@ -1188,6 +1188,54 @@ const canonical = base ? base + "/changelog" : null;
 `;
 };
 
+/**
+ * Generate `.blume/src/pages/404.astro`: the default not-found page. Rendered
+ * through `PageLayout` (header + search, no sidebar) so it stays consistent with
+ * the rest of the site, with copy pulled from the translatable `notFound` UI
+ * strings. Written at Astro's reserved `src/pages/404.astro` path so static
+ * builds emit `dist/404.html` and the dev server serves it for unmatched routes.
+ * Skipped by the generator when a user `pages/404.astro` already occupies the
+ * `/404` route, so projects can fully override it.
+ */
+export const notFoundPageTemplate = (): string => `---
+// Generated by Blume. Do not edit. Override by adding \`pages/404.astro\`.
+import PageLayout from "blume/components/layout/PageLayout.astro";
+import data from "../generated/data.json";
+
+export const prerender = true;
+
+const nf = data.ui.notFound;
+---
+
+<PageLayout
+  site={{ title: data.config.title, description: data.config.description }}
+  logo={data.config.logo}
+  favicon={data.config.favicon}
+  appleIcon={data.config.appleIcon}
+  banner={data.config.banner}
+  analytics={data.config.analytics}
+  navigation={data.navigation}
+  page={{ title: nf.title, route: "/404" }}
+  themeMode={data.config.theme.mode}
+  fontCssVars={data.fontCssVars}
+  searchEnabled={data.config.search.enabled}
+  ui={data.ui}
+  noindex={true}
+>
+  <div
+    class="mx-auto flex min-h-[60vh] max-w-2xl flex-col items-center justify-center gap-4 px-6 py-24 text-center"
+  >
+    <p class="text-6xl font-bold text-muted-foreground">404</p>
+    <h1 class="text-2xl font-semibold text-foreground">{nf.title}</h1>
+    <p class="text-muted-foreground">{nf.description}</p>
+    <a
+      class="mt-2 rounded-md bg-accent px-4 py-2 text-sm font-medium text-accent-foreground"
+      href="/">{nf.home}</a
+    >
+  </div>
+</PageLayout>
+`;
+
 /**
  * Generate `.blume/src/generated/components.ts`, which re-exports the user's
  * component overrides (or empty maps when no `components.ts` exists). Importing

package/src/components/content/Component.astro

@@ -46,7 +46,11 @@ const paneStyle = `height:${paneHeight}px`;
     // CodeGroup, switching one Component must not switch the others.
     <Tabs hash={false} sync={false}>
       <Tab
-        class="flex items-center justify-center overflow-auto"
+        // `not-prose`: the preview lives inside the page's `.prose` wrapper, so
+        // without this the typography styles bleed into the live component
+        // (headings, links, lists, spacing). The Code pane below keeps prose on
+        // purpose — that's what styles the highlighted source.
+        class="not-prose flex items-center justify-center overflow-auto"
         style={paneStyle}
         title="Preview"
       >

package/src/components/layout/RootLayout.astro

@@ -16,7 +16,12 @@ import Favicon from "./Favicon.astro";
 import Fonts from "./Fonts.astro";
 import { bannerInitScript, themeInitScript } from "./head-scripts.ts";
 import Header from "./Header.astro";
-import { findBreadcrumbs, flattenPages, getPagination } from "./nav-utils.ts";
+import {
+  findBreadcrumbs,
+  flattenPages,
+  getPagination,
+  sidebarForRoute,
+} from "./nav-utils.ts";
 import NavTree from "./NavTree.astro";
 import { resolveSlot } from "./overrides.ts";
 import PageActions from "./PageActions.astro";
@@ -179,11 +184,12 @@ const formattedLastModified =
 // Needs a configured site to be useful, so the menu is hidden without one.
 const mcpUrl = mcp && siteUrl ? new URL(mcp.route, siteUrl).href : null;
 
-const crumbs = findBreadcrumbs(navigation.sidebar, page.route);
-const { prev, next } = getPagination(
-  flattenPages(navigation.sidebar),
-  page.route
-);
+// Scope the sidebar (and the breadcrumbs/pagination derived from it) to the
+// active tab's section, so a multi-section site drills each tab into its own
+// pages. Without tabs — or on a route under none — this is the full sidebar.
+const sidebar = sidebarForRoute(navigation.sidebar, navigation.tabs, page.route);
+const crumbs = findBreadcrumbs(sidebar, page.route);
+const { prev, next } = getPagination(flattenPages(sidebar), page.route);
 
 // Structured data is skipped when disabled or for pages we ask crawlers not to
 // index. Escape `<` so a title/description containing `</script>` can't break
@@ -294,7 +300,7 @@ const bannerScript = banner?.dismissible
         class="fixed top-16 start-0 z-[35] h-[calc(100dvh-4rem)] w-64 max-w-[80vw] -translate-x-[105%] overflow-y-auto border-border border-e bg-background px-5 pt-4 pb-6 transition-transform rtl:translate-x-[105%] [:where([data-blume-nav-open])_&]:translate-x-0! lg:sticky lg:z-auto lg:w-auto lg:max-w-none lg:translate-x-0! lg:border-e-0 lg:bg-transparent lg:px-4"
       >
         <nav>
-          <SidebarSlot currentRoute={page.route} items={navigation.sidebar} />
+          <SidebarSlot currentRoute={page.route} items={sidebar} />
         </nav>
       </aside>
       <main class="min-w-0 px-6 pt-6 pb-10 lg:px-8 xl:px-10" id="blume-content">

package/src/components/layout/nav-utils.ts

@@ -1,4 +1,4 @@
-import type { NavNode } from "../../core/types.ts";
+import type { NavNode, NavTab } from "../../core/types.ts";
 
 /** A flat, ordered page reference used for previous/next pagination. */
 export interface FlatPage {
@@ -71,6 +71,113 @@ export const findBreadcrumbs = (nodes: NavNode[], route: string): Crumb[] => {
   return search(nodes, []) ?? [];
 };
 
+/** Whether `route` is the section root `base` or nested beneath it. */
+const isUnderPath = (route: string, base: string): boolean =>
+  route === base || route.startsWith(`${base}/`);
+
+/**
+ * The tab whose `path` is the longest prefix of `route`, mirroring the header's
+ * active-tab highlight. The root tab (`/`) is skipped — it spans everything and
+ * so never scopes the sidebar.
+ */
+const activeTab = (tabs: NavTab[], route: string): NavTab | null => {
+  let match: NavTab | null = null;
+  for (const tab of tabs) {
+    if (tab.path === "/" || !isUnderPath(route, tab.path)) {
+      continue;
+    }
+    if (!match || tab.path.length > match.path.length) {
+      match = tab;
+    }
+  }
+  return match;
+};
+
+/**
+ * The children of the group whose path is `base`, searched at any depth — so a
+ * content tree wrapped in a top-level container group still resolves to the
+ * right section. Returns null when no group sits exactly at `base`.
+ */
+const sectionChildren = (nodes: NavNode[], base: string): NavNode[] | null => {
+  for (const node of nodes) {
+    if (node.kind !== "group") {
+      continue;
+    }
+    if (node.path === base || node.route === base) {
+      return node.children;
+    }
+    const deeper = sectionChildren(node.children, base);
+    if (deeper) {
+      return deeper;
+    }
+  }
+  return null;
+};
+
+/** Whether a group maps to a header tab (matched on its path or link route). */
+const isTabSection = (node: NavNode, tabPaths: Set<string>): boolean =>
+  node.kind === "group" &&
+  ((node.path !== undefined && tabPaths.has(node.path)) ||
+    (node.route !== undefined && tabPaths.has(node.route)));
+
+/**
+ * Drop the groups that already own a header tab from the tree, at any depth —
+ * so a root/un-tabbed route lists only the pages outside every tab's section
+ * instead of duplicating each tab as a sidebar group. A container left empty by
+ * this pruning is dropped too, so no bare heading is stranded. The root tab
+ * (`/`) spans everything, so it never removes anything.
+ */
+const withoutTabSections = (nodes: NavNode[], tabs: NavTab[]): NavNode[] => {
+  const tabPaths = new Set(
+    tabs.filter((tab) => tab.path !== "/").map((tab) => tab.path)
+  );
+  if (tabPaths.size === 0) {
+    return nodes;
+  }
+  const prune = (items: NavNode[]): NavNode[] => {
+    const kept: NavNode[] = [];
+    for (const item of items) {
+      if (isTabSection(item, tabPaths)) {
+        continue;
+      }
+      if (item.kind === "group") {
+        const children = prune(item.children);
+        if (children.length === 0) {
+          continue;
+        }
+        kept.push({ ...item, children });
+      } else {
+        kept.push(item);
+      }
+    }
+    return kept;
+  };
+  return prune(nodes);
+};
+
+/**
+ * Scope the sidebar to the active tab's section. With tabs configured, a route
+ * under one tab shows only that tab's group — so a multi-section site (e.g.
+ * Adapters / API / AI tabs) drills each tab into its own pages instead of one
+ * global tree, the way Fumadocs' root folders do. On a route under no tab (or
+ * the root `/` tab), the tab-owned groups are hidden so the root sidebar shows
+ * only pages that don't belong to a tab. Falls back to the full sidebar when a
+ * matched tab maps to no group, or when hiding the tab sections would blank the
+ * sidebar, so a route is never left empty.
+ */
+export const sidebarForRoute = (
+  sidebar: NavNode[],
+  tabs: NavTab[],
+  route: string
+): NavNode[] => {
+  const tab = activeTab(tabs, route);
+  if (tab) {
+    return sectionChildren(sidebar, tab.path) ?? sidebar;
+  }
+  const scoped = withoutTabSections(sidebar, tabs);
+  return scoped.length > 0 ? scoped : sidebar;
+};
+
 /** Resolve previous/next pages around the current route. */
 export const getPagination = (
   flat: FlatPage[],

package/src/core/i18n-ui.ts

@@ -50,6 +50,15 @@ const uiStringsObject = z.object({
       untranslated: z.string().default("Not translated"),
     })
     .default({}),
+  notFound: z
+    .object({
+      description: z
+        .string()
+        .default("We couldn't find the page you're looking for."),
+      home: z.string().default("Back to home"),
+      title: z.string().default("Page not found"),
+    })
+    .default({}),
   page: z
     .object({
       lastUpdated: z.string().default("Last updated on"),

package/src/core/navigation.ts

@@ -55,6 +55,8 @@ interface MutableGroup {
   kind: "group";
   key: string;
   path: string;
+  /** The group's URL path (folder route prefix); set as pages are inserted. */
+  routePath?: string;
   label: string;
   icon?: string;
   collapsed?: boolean;
@@ -194,6 +196,7 @@ const toNavNode = (node: MutableNode): NavNode => {
     icon: node.icon,
     kind: "group",
     label: node.label,
+    path: node.routePath,
   };
 };
 
@@ -215,9 +218,18 @@ const buildFileSystemSidebar = (
     const filename = parts.at(-1) ?? page.navPath;
     const dirs = parts.slice(0, -1);
 
+    // Each group's URL path is the matching prefix of the page's route. navPath
+    // is locale-stripped while the route may carry a locale/base prefix, so
+    // align the folder segments from the right (the extra leading segments are
+    // that prefix). Under such a prefix the path won't match a logical tab path,
+    // so tab-scoping simply no-ops — same as the header's active-tab logic.
+    const folderParts = page.route.split("/").filter(Boolean).slice(0, -1);
+    const offset = Math.max(0, folderParts.length - dirs.length);
+
     let parent = root;
-    for (const dir of dirs) {
+    for (const [index, dir] of dirs.entries()) {
       parent = ensureGroup(parent, dir);
+      parent.routePath ??= `/${folderParts.slice(0, offset + index + 1).join("/")}`;
     }
 
     parent.children.push({

package/src/core/types.ts

@@ -137,6 +137,12 @@ export type NavNode =
       display?: SidebarDisplay;
       icon?: string;
       route?: string;
+      /**
+       * The group's URL path (its folder route prefix), even when the folder
+       * has no index page to link. Used to scope the sidebar to a tab's section;
+       * not a clickable link (that's `route`).
+       */
+      path?: string;
       collapsed?: boolean;
       children: NavNode[];
     };

package/src/registry/eject.ts

@@ -12,7 +12,7 @@ import {
   detectNeedsReact,
 } from "../astro/generate.ts";
 import { discoverIslands } from "../astro/islands.ts";
-import { customOgRoutes, discoverPages } from "../astro/pages.ts";
+import { customOgRoutes, discoverPages, routeIsTaken } from "../astro/pages.ts";
 import {
   askEndpointTemplate,
   astroConfigTemplate,
@@ -25,6 +25,7 @@ import {
   islandMapTemplate,
   islandWrapperTemplate,
   mixedbreadSearchEndpointTemplate,
+  notFoundPageTemplate,
   ogEndpointTemplate,
   rawMarkdownEndpointTemplate,
   rssEndpointTemplate,
@@ -206,6 +207,16 @@ export const eject = async (root: string): Promise<string[]> => {
     });
   }
 
+  // Default 404 page, unless the project already owns `/404` (a custom
+  // `pages/404.astro` or a `404.md` content page). The ejected project owns the
+  // file afterwards and can edit or remove it.
+  if (!routeIsTaken(pages, project.graph.pages, "/404")) {
+    files.push({
+      content: notFoundPageTemplate(),
+      path: join(srcDir, "pages", "404.astro"),
+    });
+  }
+
   // The provider-specific client loader behind the `blume:search-client` alias.
   files.push({
     content: searchClientTemplate(config),