create-zudo-doc 0.2.0 → 0.2.1

package/templates/base/pages/lib/_sidebar-with-defaults.tsx

@@ -35,14 +35,13 @@ import type { JSX } from "preact";
 // reaches the rendered tree).
 import { Island } from "@takazudo/zfb";
 import SidebarTree from "@/components/sidebar-tree";
-import { settings } from "@/config/settings";
 import { defaultLocale, locales, t, type Locale } from "@/config/i18n";
-import { buildLocaleLinks, navHref, versionedDocsUrl } from "@/utils/base";
 import {
-  type NavNode,
-} from "@/utils/docs";
-import { buildSidebarForSection } from "@/utils/sidebar";
-import { loadNavSourceDocs } from "./_nav-source-docs";
+  buildRootMenuItems,
+  buildLocaleLinksForNav,
+  buildSidebarNodes,
+  getThemeDefaultMode,
+} from "./_nav-data-prep";
 
 export interface SidebarWithDefaultsProps {
   /** Slug of the active doc page, used to highlight the current entry. */
@@ -61,34 +60,6 @@ export interface SidebarWithDefaultsProps {
   currentPath?: string;
 }
 
-/**
- * Walk the nav tree and rewrite each node's `href` to its versioned form.
- *
- * `buildNavTree` always emits hrefs via `docsUrl()`; when the active route
- * lives under `/v/{version}/...` we need the same nodes pointing at the
- * versioned URL so internal nav clicks stay inside the version. Skips
- * nodes without an href (link-only or category placeholders).
- */
-function remapVersionedHrefs(
-  nodes: NavNode[],
-  version: string,
-  nodeLang: Locale,
-): NavNode[] {
-  return nodes.map((node) => {
-    const children =
-      node.children.length > 0
-        ? remapVersionedHrefs(node.children, version, nodeLang)
-        : node.children;
-
-    if (!node.href || node.slug.startsWith("__link__")) {
-      return children !== node.children ? { ...node, children } : node;
-    }
-
-    const newHref = versionedDocsUrl(node.slug, version, nodeLang);
-    return { ...node, href: newHref, children };
-  });
-}
-
 /**
  * Default-bearing host wrapper that performs sidebar data prep, then wraps
  * the project's `<SidebarTree>`
@@ -117,35 +88,21 @@ export function SidebarWithDefaults(
     currentPath = "",
   } = props;
 
-  // Root-menu items derived from headerNav (mobile back-to-menu list).
-  // The Astro template fed labelKey through `t(...)` and computed hrefs
-  // with `navHref()`; mirror that exactly so the rendered list stays
-  // identical between the A and B sites.
-  const rootMenuItems = settings.headerNav.map((item) => ({
-    label: item.labelKey
-      ? t(item.labelKey as Parameters<typeof t>[0], lang)
-      : item.label,
-    href: navHref(item.path, lang, currentVersion),
-    children: item.children?.map((child) => ({
-      label: child.labelKey
-        ? t(child.labelKey as Parameters<typeof t>[0], lang)
-        : child.label,
-      href: navHref(child.path, lang, currentVersion),
-    })),
-  }));
+  // Root-menu items, sidebar nodes, locale links, and theme mode — all
+  // delegated to the shared _nav-data-prep helpers so header and sidebar
+  // wrappers stay in sync without duplicating the logic.
+  const rootMenuItems = buildRootMenuItems(lang, currentVersion);
 
   const backToMenuLabel = navSection ? t("nav.backToMenu", lang) : undefined;
 
-  const { navDocs, categoryMeta } = loadNavSourceDocs(lang, currentVersion);
-  const rawNodes = buildSidebarForSection(navDocs, lang, navSection, categoryMeta);
-  const nodes = currentVersion
-    ? remapVersionedHrefs(rawNodes, currentVersion, lang)
-    : rawNodes;
+  // emptyWhenUnsectioned=false: the desktop sidebar falls back to the FULL
+  // tree for pages whose slug matches no headerNav categoryMatch (legacy
+  // behavior) — only the header's mobile drawer collapses to root menu.
+  const nodes = buildSidebarNodes(lang, navSection, currentVersion, false);
 
   // Locale-switcher links are only meaningful when more than one locale is
   // configured — matches the Astro template's guard.
-  const localeLinks =
-    locales.length > 1 ? buildLocaleLinks(currentPath, lang) : undefined;
+  const localeLinks = buildLocaleLinksForNav(currentPath, lang, locales.length);
 
   // Wrap <SidebarTree> directly in <Island when="load">. SSR emits the
   // `data-zfb-island="SidebarTree"` marker around the rendered tree, with
@@ -164,9 +121,7 @@ export function SidebarWithDefaults(
         rootMenuItems={rootMenuItems}
         backToMenuLabel={backToMenuLabel}
         localeLinks={localeLinks}
-        themeDefaultMode={
-          settings.colorMode ? settings.colorMode.defaultMode : undefined
-        }
+        themeDefaultMode={getThemeDefaultMode()}
       />
     ),
   }) as unknown as JSX.Element;

package/templates/base/pages/lib/locale-merge.ts

@@ -94,7 +94,7 @@ export interface MergeLocaleDocsResult<T extends DocsEntry = DocsEntry> {
    * Useful for callers that need to determine whether a page is a fallback
    * (i.e. `isFallback = !localeSlugSet.has(slug)`).
    */
-  localeSlugSet: Set<string>;
+  localeSlugSet: ReadonlySet<string>;
 }
 
 /**

package/templates/base/pages/lib/route-enumerators.ts

@@ -71,10 +71,10 @@ export function enumerateDocsRoutes(locale: string): string[] {
     // safety re-application of the same rule (idempotent on the already-
     // stripped id); kept so this enumerator's slug derivation reads as a
     // single explicit call to the canonical helper.
-    urls.push(docsUrl(doc.data.slug ?? toRouteSlug(doc.id), locale as string));
+    urls.push(docsUrl(doc.data.slug ?? toRouteSlug(doc.id), locale as Locale));
   }
   for (const node of collectAutoIndexNodes(tree)) {
-    urls.push(docsUrl(node.slug, locale as string));
+    urls.push(docsUrl(node.slug, locale as Locale));
   }
 
   return [...new Set(urls)];
@@ -127,10 +127,14 @@ export function enumerateTagsRoutes(locale: string): string[] {
   const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
 
   for (const tag of tagMap.keys()) {
+    // Tag segment URL-encoded — these URLs feed the sitemap, which must
+    // carry well-formed encoded URLs (e.g. "type:guide" → "type%3Aguide").
+    // Route params (the page paths() functions) stay raw.
+    const encoded = encodeURIComponent(tag);
     const tagPath =
       locale === defaultLocale
-        ? `/docs/tags/${tag}`
-        : `/${locale}/docs/tags/${tag}`;
+        ? `/docs/tags/${encoded}`
+        : `/${locale}/docs/tags/${encoded}`;
     urls.push(withBase(tagPath));
   }
 
@@ -194,10 +198,10 @@ export function enumerateVersionedRoutes(
       // category_no_page index.mdx → no route, no sitemap URL (see paths()).
       if (doc.data.category_no_page === true) continue;
       const slug = doc.data.slug ?? toRouteSlug(doc.id);
-      urls.push(versionedDocsUrl(slug, version.slug, locale as string));
+      urls.push(versionedDocsUrl(slug, version.slug, locale as Locale));
     }
     for (const node of collectAutoIndexNodes(tree)) {
-      urls.push(versionedDocsUrl(node.slug, version.slug, locale as string));
+      urls.push(versionedDocsUrl(node.slug, version.slug, locale as Locale));
     }
   }
 
@@ -222,7 +226,7 @@ export function enumerateVersionedRoutes(
  * slash). The sitemap renderer prefixes each with settings.siteUrl.
  */
 export function enumerateAllRoutes(): Map<string, string> {
-  const today = new Date().toISOString().split("T")[0];
+  const today = new Date().toISOString().split("T")[0] ?? "";
   const routes = new Map<string, string>();
 
   function add(url: string): void {

package/templates/base/plugins/connect-adapter.mjs

@@ -1,3 +1,4 @@
+// @ts-check
 // Adapter from Connect-style middleware (`(req, res, next) => void`) to
 // the request-response shape zfb's `devMiddleware` lifecycle hook
 // expects (`(req: ZfbDevMiddlewareRequest) => Promise<ZfbDevMiddlewareResponse | undefined>`).
@@ -16,8 +17,19 @@
 // the v2 integration package keeps its Connect-style API surface so
 // non-zfb embedders (Astro, plain Vite, a unit test) continue to work.
 
+/** @import { ZfbDevMiddlewareRequest, ZfbDevMiddlewareResponse } from "@takazudo/zfb/plugins" */
+
 import { Buffer } from "node:buffer";
 
+/**
+ * Connect-style middleware: `(req, res, next) => void`.
+ * The req/res parameters are typed as `any` here because this adapter
+ * intentionally passes a plain-object shim that structurally satisfies the
+ * subset of `IncomingMessage` / `ServerResponse` that the v2 integration
+ * middlewares actually access — not the full Node.js types.
+ * @typedef {(req: any, res: any, next: (err?: unknown) => void) => void} ConnectMiddleware
+ */
+
 /**
  * Convert a Connect-style middleware to a zfb devMiddleware handler.
  * The returned async function takes a `ZfbDevMiddlewareRequest` and
@@ -37,6 +49,9 @@ import { Buffer } from "node:buffer";
  *   - Binary bodies (Buffer / Uint8Array) → encoded as base64 and
  *     flagged `bodyEncoding: "base64"` so the JSON envelope round-trip
  *     stays loss-less.
+ *
+ * @param {ConnectMiddleware} middleware
+ * @returns {(zfbReq: ZfbDevMiddlewareRequest) => Promise<ZfbDevMiddlewareResponse | undefined>}
  */
 export function connectToZfbHandler(middleware) {
   return (zfbReq) => {
@@ -57,9 +72,14 @@ export function connectToZfbHandler(middleware) {
       // today (`statusCode`, `setHeader`, `getHeader`, `end`) — extend
       // here if a future middleware needs more.
       let statusCode = 200;
+      /** @type {Record<string, string>} */
       const headers = {};
       let settled = false;
 
+      /**
+       * @param {string | Buffer | Uint8Array | null | undefined} body
+       * @returns {void}
+       */
       const finish = (body) => {
         if (settled) return;
         settled = true;
@@ -67,6 +87,7 @@ export function connectToZfbHandler(middleware) {
         // axum's expectation (`Record<string, string>` of arbitrary
         // case). Last-wins on collision; with `setHeader` callers this
         // shouldn't happen.
+        /** @type {Record<string, string>} */
         const normalisedHeaders = {};
         for (const [k, v] of Object.entries(headers)) {
           normalisedHeaders[k.toLowerCase()] = String(v);
@@ -93,12 +114,18 @@ export function connectToZfbHandler(middleware) {
         get statusCode() {
           return statusCode;
         },
+        /** @param {number} v */
         set statusCode(v) {
           statusCode = v;
         },
+        /**
+         * @param {string} name
+         * @param {string | number | readonly string[]} value
+         */
         setHeader(name, value) {
-          headers[name] = value;
+          headers[name] = String(value);
         },
+        /** @param {string} name */
         getHeader(name) {
           // Header lookup is case-insensitive in Node's real
           // ServerResponse — mirror that so middlewares that probe an
@@ -113,11 +140,13 @@ export function connectToZfbHandler(middleware) {
         get headersSent() {
           return settled;
         },
+        /** @param {string | Buffer | Uint8Array | null | undefined} [body] */
         end(body) {
           finish(body);
         },
       };
 
+      /** @param {unknown} [err] */
       const next = (err) => {
         if (settled) return;
         if (err) {

package/templates/base/plugins/copy-public-plugin.mjs

@@ -1,3 +1,4 @@
+// @ts-check
 // zfb plugin module: copy-public.
 //
 // Workaround for upstream zfb gap — `zfb build` does not copy `public/`
@@ -21,15 +22,22 @@
 // `zfb.config.ts`. The `base` option is intentionally unused — see
 // rationale above.
 
+/** @import { ZfbBuildHookContext, ZfbPlugin } from "@takazudo/zfb/plugins" */
+
 import { cp } from "node:fs/promises";
 import { resolve } from "node:path";
 
+/** @type {ZfbPlugin} */
 export default {
   name: "copy-public",
 
+  /** @param {ZfbBuildHookContext} ctx */
   async postBuild(ctx) {
     const { publicDir: publicDirOption } = ctx.options;
-    const publicDir = resolve(ctx.projectRoot, publicDirOption ?? "public");
+    const publicDir = resolve(
+      ctx.projectRoot,
+      typeof publicDirOption === "string" ? publicDirOption : "public",
+    );
     const dest = ctx.outDir;
 
     ctx.logger.info(`copying ${publicDir} → ${dest}`);
@@ -38,7 +46,7 @@ export default {
       recursive: true,
       force: true,
       errorOnExist: false,
-    }).catch((err) => {
+    }).catch((/** @type {NodeJS.ErrnoException} */ err) => {
       if (err.code === "ENOENT") {
         // publicDir does not exist or is empty — treat as no-op.
         ctx.logger.info("public/ not found — skipping copy");

package/templates/base/plugins/search-index-plugin.mjs

@@ -1,3 +1,4 @@
+// @ts-check
 // zfb plugin module: search-index.
 //
 // Wires two lifecycle hooks for the search-index integration:
@@ -16,25 +17,30 @@
 // Inline functions are not supported by zfb's plugin runtime; see the
 // sibling `doc-history-plugin.mjs` for the rationale.
 
+/** @import { ZfbBuildHookContext, ZfbDevMiddlewareContext, ZfbPlugin } from "@takazudo/zfb/plugins" */
+/** @import { SearchIndexBuildOptions, SearchIndexConfig } from "@takazudo/zudo-doc/integrations/search-index" */
+
 import { emitSearchIndex, createSearchIndexDevMiddleware } from "@takazudo/zudo-doc/integrations/search-index";
 import { connectToZfbHandler } from "./connect-adapter.mjs";
 
+/** @type {ZfbPlugin} */
 export default {
   name: "search-index",
 
+  /** @param {ZfbBuildHookContext} ctx */
   postBuild(ctx) {
-    const { docsDir, locales, base } = ctx.options;
-    emitSearchIndex({
+    emitSearchIndex(/** @type {SearchIndexBuildOptions} */ (/** @type {unknown} */ ({
+      ...ctx.options,
       outDir: ctx.outDir,
-      docsDir,
-      locales,
-      base,
       logger: ctx.logger,
-    });
+    })));
   },
 
+  /** @param {ZfbDevMiddlewareContext} ctx */
   devMiddleware(ctx) {
-    const middleware = createSearchIndexDevMiddleware(ctx.options);
+    const middleware = createSearchIndexDevMiddleware(
+      /** @type {SearchIndexConfig} */ (/** @type {unknown} */ (ctx.options)),
+    );
     // zfb's `register(path, handler)` matches against the FULL request
     // URL (no base-stripping). For a non-root base (e.g. "/my-docs/"),
     // requests arrive as `/my-docs/search-index.json`, so we register
@@ -43,11 +49,17 @@ export default {
     // middleware itself is base-tolerant (matches via
     // `endsWith("/search-index.json")`), so it does not need a
     // separate base-stripping pass.
-    const basePrefix = stripTrailingSlash(ctx.options.base ?? "");
+    const basePrefix = stripTrailingSlash(
+      typeof ctx.options["base"] === "string" ? ctx.options["base"] : "",
+    );
     ctx.register(`${basePrefix}/search-index.json`, connectToZfbHandler(middleware));
   },
 };
 
+/**
+ * @param {string} s
+ * @returns {string}
+ */
 function stripTrailingSlash(s) {
   if (typeof s !== "string" || s.length === 0) return "";
   return s.endsWith("/") ? s.slice(0, -1) : s;

package/templates/base/src/components/sidebar-toggle.tsx

@@ -3,7 +3,7 @@
 // Use preact hook entrypoints directly — the "react" → "preact/compat" alias
 // lets us consume React-typed components in this Preact app (configured
 // project-wide). Same pattern as src/components/sidebar-tree.tsx and
-// packages/zudo-doc/src/theme/theme-toggle.tsx. Type references via
+// packages/zudo-doc/src/theme-toggle/index.tsx. Type references via
 // the global React namespace still resolve via @types/react.
 import { useState, useEffect } from "preact/hooks";
 import clsx from "clsx";

package/templates/base/src/components/sidebar-tree.tsx

@@ -7,7 +7,9 @@ import { useState, useCallback, useEffect, useMemo, useRef } from "preact/hooks"
 import type { NavNode } from "@/utils/docs";
 import type { LocaleLink } from "@/types/locale";
 import { INDENT, BASE_PAD, connectorLeft, ConnectorLines, CategoryLinkIcon } from "./tree-nav-shared";
-import ThemeToggle from "@/components/theme-toggle";
+// BARE ThemeToggle (#2012 E2) — this footer toggle renders inside the
+// SidebarToggle island, so it must NOT bring its own island wrapper.
+import { ThemeToggle } from "@takazudo/zudo-doc/theme-toggle";
 import { smartBreakToHtml } from "@/utils/smart-break";
 
 function ToggleChevron({ isExpanded, className }: { isExpanded: boolean; className?: string }) {
@@ -61,7 +63,9 @@ function findActiveSlug(nodes: NavNode[], pathname: string): string | undefined
   for (const node of nodes) {
     if (node.href && normalizePath(node.href) === pathname) return node.slug;
     const found = findActiveSlug(node.children, pathname);
-    if (found) return found;
+    // "" is the canonical root-index slug (#1891) — a truthiness check
+    // would discard a legitimate root match.
+    if (found !== undefined) return found;
   }
   return undefined;
 }
@@ -246,8 +250,10 @@ export default function SidebarTree({ nodes, currentSlug, rootMenuItems, backToM
   }
 
   // Top page: show only header nav links, no doc tree or filter.
-  // Derived from activeSlug (runtime-synced) so it stays correct across View Transitions.
-  if (!activeSlug && rootMenuItems) {
+  // Derived from activeSlug (runtime-synced) so it stays correct across View
+  // Transitions. Must be an undefined check, not truthiness: "" is the
+  // canonical root-index doc slug (#1891) and gets the full tree.
+  if (activeSlug === undefined && rootMenuItems) {
     return (
       <nav>
         {rootMenuItems.map((item) => (

package/templates/base/src/config/color-schemes.ts

@@ -11,6 +11,10 @@ export interface ColorScheme {
     string, string, string, string, string, string, string, string,
     string, string, string, string, string, string, string, string,
   ];
+  /** Optional Shiki theme for the zdtp panel's client-side code-block preview.
+   *  Falls back to the panel config's DEFAULT_SHIKI_THEME when omitted.
+   *  Static highlighting (syntect via zfb's Rust pipeline) is unaffected. */
+  shikiTheme?: string;
   /** Optional semantic overrides — when omitted, defaults are used:
    *  surface=p0, muted=p8, accent=p5, accentHover=p14
    *  codeBg=p10, codeFg=p11, success=p2, danger=p1, warning=p3, info=p4

package/templates/base/src/config/docs-schema.ts

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import { settings } from "./settings";
+import { tagVocabulary } from "./tag-vocabulary";
+
+// ---------------------------------------------------------------------------
+// Tags schema builder — governance-aware.
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the `tags` schema based on governance mode. `"strict"` tightens to a
+ * `z.enum` of every canonical id plus every alias (content still uses
+ * aliases verbatim — resolution happens at the aggregation layer, after
+ * parsing).
+ */
+function buildTagsSchema() {
+  const vocabularyActive =
+    settings.tagVocabulary && settings.tagGovernance === "strict";
+  if (!vocabularyActive) return z.array(z.string()).optional();
+  const allowed = new Set<string>();
+  for (const entry of tagVocabulary) {
+    allowed.add(entry.id);
+    for (const alias of entry.aliases ?? []) allowed.add(alias);
+  }
+  const allowedList = [...allowed];
+  if (allowedList.length === 0) return z.array(z.string()).optional();
+  const [first, ...rest] = allowedList;
+  return z
+    .array(z.enum([first, ...rest] as [string, ...string[]]))
+    .optional();
+}
+
+// ---------------------------------------------------------------------------
+// Schema builder — single source of truth for the docs frontmatter shape.
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the docs frontmatter zod schema.
+ *
+ * Returns a single `z.object(...).passthrough()` that is reused for every
+ * docs collection (default + per-locale + per-version + per-version-per-locale).
+ * The `tags` field is governance-aware: `buildTagsSchema()` returns a plain
+ * `z.array(z.string())` when governance is off, or a restricted `z.enum`
+ * when `tagGovernance: "strict"` + `tagVocabulary` is configured.
+ *
+ * `.passthrough()` keeps custom frontmatter keys (e.g. `author`, `status`)
+ * available downstream — the frontmatter-preview UI relies on this to
+ * surface arbitrary keys without declaring each one here.
+ */
+export function buildDocsSchema() {
+  return z
+    .object({
+      title: z.string(),
+      description: z.string().optional(),
+      category: z.string().optional(),
+      sidebar_position: z.number().optional(),
+      sidebar_label: z.string().optional(),
+      tags: buildTagsSchema(),
+      search_exclude: z.boolean().optional(),
+      pagination_next: z.string().nullable().optional(),
+      pagination_prev: z.string().nullable().optional(),
+      draft: z.boolean().optional(),
+      unlisted: z.boolean().optional(),
+      hide_sidebar: z.boolean().optional(),
+      hide_toc: z.boolean().optional(),
+      doc_history: z.boolean().optional(),
+      standalone: z.boolean().optional(),
+      slug: z.string().optional(),
+      generated: z.boolean().optional(),
+      // Category metadata expressed as a directory index.mdx's frontmatter — the
+      // frontmatter form of `_category_.json`. `category_no_page` makes the index
+      // a non-linked sidebar header excluded from routes/sitemap/search;
+      // `category_sort_order` sets the child sort direction. Frontmatter wins
+      // over the sidecar.
+      category_no_page: z.boolean().optional(),
+      category_sort_order: z.enum(["asc", "desc"]).optional(),
+    })
+    .passthrough();
+}
+
+// ---------------------------------------------------------------------------
+// Inferred type — single source of truth for the docs data shape.
+// ---------------------------------------------------------------------------
+
+/**
+ * TypeScript type inferred from the docs frontmatter zod schema.
+ *
+ * Import this type instead of hand-writing the field list in `pages/_data.ts`
+ * (`ZfbDocsData`) or `src/types/docs-entry.ts` (`DocsEntry.data`).
+ *
+ * The `[key: string]: unknown` index signature from `.passthrough()` is
+ * naturally present via `z.infer` — custom frontmatter keys remain accessible
+ * downstream (e.g. frontmatter-preview) without extra casting.
+ */
+export type DocsData = z.infer<ReturnType<typeof buildDocsSchema>>;

package/templates/base/src/config/i18n.ts

@@ -1,4 +1,5 @@
 import { settings } from "./settings";
+import type { LocaleConfig } from "./settings-types";
 
 // Collection name string used by zfb's content engine (`getCollection(...)`).
 // Kept as a structural string-literal alias so callers don't have to redeclare
@@ -15,9 +16,9 @@ export const locales = [
 ] as const;
 export type Locale = (typeof locales)[number];
 
-/** Safely look up a locale in settings.locales. */
-function getLocaleConfig(locale: string) {
-  return settings.locales[locale];
+/** Safely look up a locale in settings.locales by string key. */
+export function getLocaleConfig(locale: string): LocaleConfig | undefined {
+  return (settings.locales as Record<string, LocaleConfig | undefined>)[locale];
 }
 
 /** Get the content directory for a locale. */
@@ -70,6 +71,8 @@ const translations: Record<string, Record<string, string>> = {
     "toc.title": "On this page",
     "docs.browseAll": "Browse all documentation sections.",
     "search.label": "Search",
+    "search.placeholder": "Type to search...",
+    "search.shortcutHint": "to open search from anywhere",
     "search.resultCount": "{count} results",
     "code.copy": "Copy code",
     "code.copied": "Copied!",
@@ -128,6 +131,8 @@ const translations: Record<string, Record<string, string>> = {
     "toc.title": "目次",
     "docs.browseAll": "すべてのドキュメントセクションを閲覧",
     "search.label": "検索",
+    "search.placeholder": "検索したい単語を入力",
+    "search.shortcutHint": "いつでも検索バーを開ける",
     "search.resultCount": "{count} 件",
     "code.copy": "コードをコピー",
     "code.copied": "コピーしました！",
@@ -186,6 +191,8 @@ const translations: Record<string, Record<string, string>> = {
     "toc.title": "Auf dieser Seite",
     "docs.browseAll": "Alle Dokumentationsabschnitte durchsuchen.",
     "search.label": "Suche",
+    "search.placeholder": "Suchbegriff eingeben...",
+    "search.shortcutHint": "Suche von überall öffnen",
     "search.resultCount": "{count} Ergebnisse",
     "code.copy": "Code kopieren",
     "code.copied": "Kopiert!",

package/templates/base/src/styles/global.css

@@ -1002,6 +1002,20 @@ pre[class^="syntect-"] .line .highlighted-word {
   html[data-sidebar-hidden] .zd-sidebar-content-wrapper {
     margin-left: 0;
   }
+
+  /* When hidden via the toggle, narrow the content band to the
+   * hide_sidebar frontmatter width so it centers (the flex parent already
+   * applies justify-content: center) instead of leaving a dead gap where
+   * the sidebar was. 80rem must match the `max-w-[80rem]` hide_sidebar
+   * branch in doc-layout.tsx. These rules are unlayered, so they win over
+   * the Tailwind `max-w-[clamp(...)]` utility (utilities layer). (#2002) */
+  .zd-doc-content-band {
+    transition: max-width 200ms ease-in-out;
+  }
+
+  html[data-sidebar-hidden] .zd-doc-content-band {
+    max-width: 80rem;
+  }
 }
 
 /* Sidebar toggle button — left position uses CSS variable, needs global rule */

package/templates/base/src/types/docs-entry.ts

@@ -1,3 +1,5 @@
+import type { DocsData } from "@/config/docs-schema";
+
 /**
  * Concrete entry type for docs collections.
  *
@@ -6,6 +8,9 @@
  * but is defined locally now that the project runs on the zfb content
  * engine — collection-name-specific generics are not exposed by zfb, so
  * pages cast collection entries to this shape via `pages/_data.ts`.
+ *
+ * `data` is typed as `DocsData` — the `z.infer`-derived type from
+ * `src/config/docs-schema.ts` — so the field set is maintained in one place.
  */
 // Structural shape of zfb's optional rendered-content payload for a doc
 // entry (kept loose to stay engine-agnostic — pages do not rely on the
@@ -13,34 +18,11 @@
 type RenderedContent = unknown;
 export interface DocsEntry {
   id: string;
+  /** zfb content engine slug (filename without `.md`/`.mdx`; used by toRouteSlug). */
+  slug: string;
   body?: string;
   collection: string;
-  data: {
-    title: string;
-    description?: string;
-    category?: string;
-    sidebar_position?: number;
-    sidebar_label?: string;
-    tags?: string[];
-    search_exclude?: boolean;
-    pagination_next?: string | null;
-    pagination_prev?: string | null;
-    draft?: boolean;
-    unlisted?: boolean;
-    hide_sidebar?: boolean;
-    hide_toc?: boolean;
-    doc_history?: boolean;
-    standalone?: boolean;
-    slug?: string;
-    generated?: boolean;
-    /** Category metadata on a directory's index.mdx (frontmatter form of
-     *  `_category_.json` `noPage`): non-linked sidebar header + excluded from
-     *  routes/sitemap/search. Frontmatter wins over the sidecar. */
-    category_no_page?: boolean;
-    /** Frontmatter form of `_category_.json` `sortOrder` — child sort
-     *  direction. Frontmatter wins over the sidecar. */
-    category_sort_order?: "asc" | "desc";
-  };
+  data: DocsData;
   rendered?: RenderedContent;
   filePath?: string;
 }

package/templates/base/src/utils/base.ts

@@ -37,8 +37,10 @@ export function withBase(path: string): string {
 /** Strip the base prefix from a URL pathname. */
 export function stripBase(path: string): string {
   if (normalizedBase === "") return path;
-  return path.startsWith(normalizedBase)
-    ? path.slice(normalizedBase.length) || "/"
+  // Require a segment boundary so base "/app" doesn't strip "/application/...".
+  if (path === normalizedBase) return "/";
+  return path.startsWith(`${normalizedBase}/`)
+    ? path.slice(normalizedBase.length)
     : path;
 }
 
@@ -55,7 +57,7 @@ export function absoluteUrl(pageUrl: string): string | undefined {
 }
 
 /** Build a docs URL for the given slug and lang. */
-export function docsUrl(slug: string, lang: Locale = defaultLocale): string {
+export function docsUrl(slug: string, lang: Locale | string = defaultLocale): string {
   const path = lang === defaultLocale ? `/docs/${slug}` : `/${lang}/docs/${slug}`;
   return withBase(path);
 }