@takazudo/zudo-doc 5.28.2 → 6.0.1

package/dist/doc-page-renderer/index.d.ts

@@ -1,6 +1,6 @@
 /** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-import type { JSX, VNode } from "preact";
+import type { Child, Description } from "@takazudo/zfb/zudo-react";
+import type { JSX } from "@takazudo/zfb/zudo-react/jsx-runtime";
 import type { DocPageBaseProps, DocNavNode, DocPageEntry } from "../doc-page-props/index.js";
 import type { VersionBannerLabels } from "../i18n-version/index.js";
 import type { ChromeContext } from "../factory-context/index.js";
@@ -70,6 +70,12 @@ export interface DocPageRendererDeps {
         title: string;
         description?: string;
         canonical?: string;
+        alternateLinks?: ReadonlyArray<{
+            rel: string;
+            href: string;
+            type?: string;
+            title?: string;
+        }>;
         breadcrumbs: Array<{
             label: string;
             href?: string;
@@ -102,10 +108,10 @@ export interface DocPageRendererDeps {
         versionBannerLabels?: VersionBannerLabels;
         autoIndexLabel?: string;
         autoIndexChildren?: DocNavNode[];
-        metainfoSlot?: VNode | null;
-        contentHeaderSlot?: VNode;
-        contentSlot?: VNode;
-        docHistorySlot?: VNode | null;
+        metainfoSlot?: Child;
+        contentHeaderSlot?: Child;
+        contentSlot?: Child;
+        docHistorySlot?: Child;
     }) => JSX.Element;
     /**
      * The `DocContentHeader` component (host-side factory result).
@@ -135,7 +141,7 @@ export interface DocPageRendererDeps {
         sourceFileExt?: ".mdx" | ".md";
         contentDir?: string;
         isFallback?: boolean;
-    }) => VNode | null;
+    }) => Description | null;
 }
 /**
  * Create a `renderDocPage` function from the unified {@link ChromeContext}

package/dist/doc-page-renderer/index.js

@@ -1,4 +1,5 @@
-import { jsx } from "preact/jsx-runtime";
+import { jsx } from "@takazudo/zfb/zudo-react/jsx-runtime";
+import { agentPageKey } from "../agent-docs/identity.js";
 import { createDocPageShell } from "../doc-page-shell/index.js";
 import { createDocContentHeader } from "../doc-content-header/index.js";
 import { createDocMetainfoArea } from "../doc-metainfo-area/index.js";
@@ -55,6 +56,13 @@ function createRenderDocPage(ctx) {
     const hideToc = entryData ? entryData.hide_toc || standalone : void 0;
     const contentWide = entryData ? entryData.wide : void 0;
     const sidebarPersistKey = hideSidebar ? void 0 : `sidebar-${locale}-${navSection ?? "default"}`;
+    const agentMarkdownAlternates = ctx.settings.agentExport === true && !version && !isFallback && props.kind === "entry" && !Boolean(
+      entryData?.draft || entryData?.unlisted || entryData?.search_exclude || entryData?.category_no_page
+    ) ? [{
+      rel: "alternate",
+      type: "text/markdown",
+      href: ctx.withBase(`/agent/v1/pages/${agentPageKey(locale, slug)}.md`)
+    }] : void 0;
     const ContentComponent = props.kind === "entry" ? props.entry.Content : null;
     return /* @__PURE__ */ jsx(
       DocPageShell,
@@ -65,6 +73,7 @@ function createRenderDocPage(ctx) {
         title,
         description,
         canonical,
+        alternateLinks: agentMarkdownAlternates,
         breadcrumbs,
         prev,
         next,

package/dist/doc-page-shell/index.d.ts

@@ -1,6 +1,6 @@
 /** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-import type { ComponentChildren, JSX, VNode } from "preact";
+import type { Child } from "@takazudo/zfb/zudo-react";
+import type { JSX } from "@takazudo/zfb/zudo-react/jsx-runtime";
 import type { VersionBannerLabels } from "../i18n-version/index.js";
 import type { ChromeContext } from "../factory-context/index.js";
 import type { Settings } from "../settings.js";
@@ -43,6 +43,13 @@ export interface DocPageShellProps {
     description?: string;
     /** Absolute canonical URL, or undefined when siteUrl is unset. */
     canonical?: string;
+    /** Additional per-page alternate links passed through to the head defaults. */
+    alternateLinks?: ReadonlyArray<{
+        rel: string;
+        href: string;
+        type?: string;
+        title?: string;
+    }>;
     /** Pre-resolved breadcrumb trail (hrefs already remapped per route). */
     breadcrumbs: DocPageBreadcrumbItem[];
     /** Pre-resolved prev/next nav nodes (hrefs already remapped per route). */
@@ -65,7 +72,7 @@ export interface DocPageShellProps {
     /** Version slug for Header/Sidebar active-state, or undefined on latest routes. */
     currentVersion?: string;
     /** Inline version switcher VNode for the breadcrumb right-slot. */
-    versionSwitcher: ComponentChildren;
+    versionSwitcher: Child;
     /**
      * This page's unavailable-version slugs, straight from
      * `getUnavailableVersions(slug, locale)` (`../version-availability`) —
@@ -93,19 +100,19 @@ export interface DocPageShellProps {
      * Auto-index branch slot: the build-time date block (DocMetainfoArea), or
      * null to omit it.
      */
-    metainfoSlot?: VNode | null;
+    metainfoSlot?: Child;
     /**
      * Entry branch slot: the content header (h1 + meta + tags + description +
      * frontmatter preview), built per route (carries isFallback).
      */
-    contentHeaderSlot?: VNode;
+    contentHeaderSlot?: Child;
     /** Entry branch slot: the rendered MDX `<Content />`. */
-    contentSlot?: VNode;
+    contentSlot?: Child;
     /**
      * Entry branch slot: the document-utilities area (DocHistoryArea), or null
      * to omit it.
      */
-    docHistorySlot?: VNode | null;
+    docHistorySlot?: Child;
 }
 /** Settings subset read by {@link createDocPageShell}. */
 export interface DocPageShellSettings {
@@ -124,6 +131,12 @@ export interface DocPageShellDeps {
         title: string;
         description?: string;
         canonical?: string;
+        alternateLinks?: ReadonlyArray<{
+            rel: string;
+            href: string;
+            type?: string;
+            title?: string;
+        }>;
     }) => JSX.Element;
     SidebarWithDefaults: (props: {
         currentSlug?: string;

package/dist/doc-page-shell/index.js

@@ -1,7 +1,7 @@
-import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
+import { Fragment, jsx, jsxs } from "@takazudo/zfb/zudo-react/jsx-runtime";
 import { Island } from "@takazudo/zfb";
 import { DocLayoutWithDefaults } from "../doclayout/index.js";
-import { MobileToc, getTocTitle } from "../toc/index.js";
+import { Toc as DefaultToc, MobileToc, getTocTitle } from "../toc/index.js";
 import { NavCardGrid } from "../nav-indexing/index.js";
 import {
   createSidebarPrepaint,
@@ -16,6 +16,7 @@ import { createHeadWithDefaults } from "../head-with-defaults/index.js";
 import { resolveThemePackSsrSlug } from "../theme/theme-pack-provider.js";
 import { createDocBodyEnd } from "../doc-body-end/index.js";
 import { deriveComposeMetaTitle } from "../chrome/derive.js";
+import { normalizeIslandData } from "../chrome/island-data.js";
 import { derivePrimaryChromeSlots } from "../chrome/primary-slots.js";
 import { assertChromeContext } from "../chrome/assert-chrome-context.js";
 function createDocPageShell(ctx) {
@@ -60,6 +61,7 @@ function createDocPageShell(ctx) {
       title,
       description,
       canonical,
+      alternateLinks,
       breadcrumbs,
       prev,
       next,
@@ -84,9 +86,10 @@ function createDocPageShell(ctx) {
       docHistorySlot
     } = props;
     const tocTitle = getTocTitle(locale);
+    const transportHeadings = normalizeIslandData(headings);
     const shouldRenderToc = !hideToc && headings.length > 0;
     const shouldRenderDefaultToc = shouldRenderToc && !customTocIsPresent;
-    const tocOverride = shouldRenderToc ? customTocIsPresent ? /* @__PURE__ */ jsx(Toc, { headings, title: tocTitle }) : (
+    const tocOverride = shouldRenderToc ? customTocIsPresent ? /* @__PURE__ */ jsx(Toc, { headings: transportHeadings, title: tocTitle }) : (
       // The zfb <Island> wrapper renders a bare <div> with no class, so
       // below xl (where <Toc> itself is `hidden xl:flex`) it would remain
       // an in-flow, zero-width flex child of the content band and reserve a
@@ -111,12 +114,12 @@ function createDocPageShell(ctx) {
       // bare and unaffected by the toggle feature.
       /* @__PURE__ */ jsx("div", { class: "zd-toc-col hidden xl:flex", children: Island({
         when: "load",
-        children: /* @__PURE__ */ jsx(Toc, { headings, title: tocTitle })
+        children: /* @__PURE__ */ jsx(DefaultToc, { headings: transportHeadings, title: tocTitle })
       }) })
     ) : void 0;
     const mobileTocOverride = shouldRenderToc ? Island({
       when: "load",
-      children: /* @__PURE__ */ jsx(MobileToc, { headings, title: tocTitle })
+      children: /* @__PURE__ */ jsx(MobileToc, { headings: transportHeadings, title: tocTitle })
     }) : void 0;
     return /* @__PURE__ */ jsx(
       DocLayoutWithDefaults,
@@ -124,7 +127,15 @@ function createDocPageShell(ctx) {
         title: composeMetaTitle(title),
         description: settings.metaTags.description ? description : void 0,
         head: /* @__PURE__ */ jsxs(Fragment, { children: [
-          /* @__PURE__ */ jsx(HeadWithDefaults, { title, description, canonical }),
+          /* @__PURE__ */ jsx(
+            HeadWithDefaults,
+            {
+              title,
+              description,
+              canonical,
+              alternateLinks
+            }
+          ),
           /* @__PURE__ */ jsx(SidebarVisibilityPrepaint, { hideSidebar }),
           /* @__PURE__ */ jsx(TocVisibilityPrepaint, { shouldRenderDefaultToc })
         ] }),

package/dist/doc-pager/index.d.ts

@@ -1,6 +1,5 @@
 /** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-import type { JSX } from "preact";
+import type { JSX } from "@takazudo/zfb/zudo-react/jsx-runtime";
 import type { ChromeContext } from "../factory-context/index.js";
 import type { Settings } from "../settings.js";
 interface PagerNode {

package/dist/doc-pager/index.js

@@ -1,4 +1,4 @@
-import { jsx, jsxs } from "preact/jsx-runtime";
+import { jsx, jsxs } from "@takazudo/zfb/zudo-react/jsx-runtime";
 import { ChevronLeft, ChevronRight } from "../icons/index.js";
 import { assertChromeContext } from "../chrome/assert-chrome-context.js";
 import { deriveDateFormats } from "../chrome/derive.js";
@@ -16,7 +16,7 @@ function createDocPager(ctx) {
           class: "group border border-muted rounded-lg p-hsp-lg hover:border-accent",
           children: [
             /* @__PURE__ */ jsxs("div", { class: "flex items-center gap-hsp-xs text-caption text-muted mb-vsp-2xs group-hover:text-accent group-focus-visible:text-accent", children: [
-              /* @__PURE__ */ jsx(ChevronLeft, { className: "h-[1.125rem] w-[1.125rem]" }),
+              /* @__PURE__ */ jsx(ChevronLeft, { class: "h-[1.125rem] w-[1.125rem]" }),
               /* @__PURE__ */ jsx("span", { class: "no-underline", children: t("nav.previous", locale) })
             ] }),
             /* @__PURE__ */ jsx("p", { class: "text-small font-semibold text-fg group-hover:text-accent group-hover:underline group-focus-visible:text-accent group-focus-visible:underline", children: prev.label }),
@@ -32,7 +32,7 @@ function createDocPager(ctx) {
           children: [
             /* @__PURE__ */ jsxs("div", { class: "flex items-center justify-end gap-hsp-xs text-caption text-muted mb-vsp-2xs group-hover:text-accent group-focus-visible:text-accent", children: [
               /* @__PURE__ */ jsx("span", { class: "no-underline", children: t("nav.next", locale) }),
-              /* @__PURE__ */ jsx(ChevronRight, { className: "h-[1.125rem] w-[1.125rem]" })
+              /* @__PURE__ */ jsx(ChevronRight, { class: "h-[1.125rem] w-[1.125rem]" })
             ] }),
             /* @__PURE__ */ jsx("p", { class: "text-small font-semibold text-fg group-hover:text-accent group-hover:underline group-focus-visible:text-accent group-focus-visible:underline", children: next.label }),
             next.date && /* @__PURE__ */ jsx("p", { class: "text-caption text-muted", children: formatDate(next.date, locale, dateFormatsFor(locale).full) })

package/dist/doc-tags-area/index.d.ts

@@ -1,6 +1,5 @@
 /** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-import type { VNode } from "preact";
+import type { Child } from "@takazudo/zfb/zudo-react";
 import type { TagVocabularyEntry, TagGovernanceMode, Settings } from "../settings.js";
 import type { ChromeContext } from "../factory-context/index.js";
 /** Settings subset read by the DocTagsArea factory. */
@@ -25,4 +24,4 @@ export interface DocTagsAreaProps {
  * vocabulary is a HOST-bound slot (`ctx.hostBindings.tagVocabulary`, default
  * `[]`); `tagHref` is reconstructed inline (identical to the pre-collapse wiring).
  */
-export declare function createDocTagsArea<S extends Settings = Settings>(ctx: ChromeContext<S>): (props: DocTagsAreaProps) => VNode | null;
+export declare function createDocTagsArea<S extends Settings = Settings>(ctx: ChromeContext<S>): (props: DocTagsAreaProps) => Child;

package/dist/doc-tags-area/index.js

@@ -1,4 +1,4 @@
-import { jsx } from "preact/jsx-runtime";
+import { jsx } from "@takazudo/zfb/zudo-react/jsx-runtime";
 import { DocTags } from "../metainfo/index.js";
 import { resolvePageTags } from "../tag-helpers/index.js";
 import { assertChromeContext } from "../chrome/assert-chrome-context.js";

package/dist/doclayout/doc-layout-with-defaults.d.ts

@@ -1,5 +1,5 @@
-/** @jsxImportSource preact */
-import type { ComponentChildren, JSX } from "preact";
+import type { Child } from "@takazudo/zfb/zudo-react";
+import type { JSX } from "@takazudo/zfb/zudo-react/jsx-runtime";
 import { type DocLayoutProps } from "./doc-layout.js";
 import type { HeadingItem } from "../toc/types.js";
 import { type VersionBannerLabels } from "../i18n-version/version-banner.js";
@@ -15,19 +15,19 @@ import { type VersionBannerLabels } from "../i18n-version/version-banner.js";
  */
 export interface DocLayoutWithDefaultsProps extends Omit<DocLayoutProps, "header" | "sidebar" | "toc" | "mobileToc" | "breadcrumb" | "footer" | "main"> {
     /** The page's article body. Required. */
-    children: ComponentChildren;
+    children: Child;
     /** Replace the default site header. */
-    headerOverride?: ComponentChildren;
+    headerOverride?: Child;
     /** Replace the default sidebar contents; pass `false` to omit its landmark entirely. */
-    sidebarOverride?: ComponentChildren;
+    sidebarOverride?: Child;
     /** Replace the default desktop TOC. */
-    tocOverride?: ComponentChildren;
+    tocOverride?: Child;
     /** Replace the default mobile TOC. */
-    mobileTocOverride?: ComponentChildren;
+    mobileTocOverride?: Child;
     /** Replace the default breadcrumb. */
-    breadcrumbOverride?: ComponentChildren;
+    breadcrumbOverride?: Child;
     /** Replace the default footer. */
-    footerOverride?: ComponentChildren;
+    footerOverride?: Child;
     /**
      * Heading items extracted from the page's MDX body. When provided, the
      * default Toc and MobileToc instances render the full item list in SSG

package/dist/doclayout/doc-layout-with-defaults.js

@@ -1,4 +1,4 @@
-import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
+import { Fragment, jsx, jsxs } from "@takazudo/zfb/zudo-react/jsx-runtime";
 import { Island } from "@takazudo/zfb";
 import { DocLayout } from "./doc-layout.js";
 import { Sidebar } from "../sidebar/sidebar.js";
@@ -97,19 +97,9 @@ function DocLayoutWithDefaults(props) {
         }
       ),
       sidebar: (
-        // Empty-data Sidebar emits the SSG marker via an explicit
-        // `<Island when="load">` wrap at this call site (not inside
-        // `<Sidebar>` itself) so the bundle's hydrate pass targets
-        // the bare component and Preact doesn't append a duplicate
-        // wrapper-div alongside the SSR'd tree. See `../sidebar/sidebar.tsx`
-        // for the full diagnosis. Hosts that have a real nav tree
-        // pass it through `sidebarOverride` and apply their own
-        // `<Island>` wrap (see `pages/lib/_sidebar-with-defaults.tsx`
-        // in the host project).
-        sidebarOverride === false ? void 0 : sidebarOverride ?? Island({
-          when: "load",
-          children: /* @__PURE__ */ jsx(Sidebar, { nodes: [] })
-        })
+        // The empty Sidebar keeps the complementary landmark without
+        // registering an island that has no navigation data.
+        sidebarOverride === false ? void 0 : sidebarOverride ?? /* @__PURE__ */ jsx(Sidebar, { nodes: [] })
       ),
       toc: tocOverride ?? defaultToc,
       mobileToc: mobileTocOverride ?? defaultMobileToc,
@@ -144,7 +134,7 @@ function DocLayoutWithDefaults(props) {
         /* @__PURE__ */ jsx(CodeBlockEnhancer, {}),
         /* @__PURE__ */ jsx(TabsInit, {}),
         /* @__PURE__ */ jsx(MermaidInit, {}),
-        /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: VERSION_SWITCHER_INIT_SCRIPT } })
+        /* @__PURE__ */ jsx("script", { rawHtml: VERSION_SWITCHER_INIT_SCRIPT })
       ] }),
       main: children
     }

package/dist/doclayout/doc-layout.d.ts

@@ -1,5 +1,5 @@
-/** @jsxImportSource preact */
-import type { ComponentChildren, JSX } from "preact";
+import type { Child } from "@takazudo/zfb/zudo-react";
+import type { JSX } from "@takazudo/zfb/zudo-react/jsx-runtime";
 /**
  * Direction-and-mode metadata for the root `<html>` element. Keeps the
  * shell from depending on a project's i18n module.
@@ -27,10 +27,9 @@ export interface DocLayoutHtmlAttrs {
     htmlStyle?: string;
 }
 /**
- * Full prop surface for the composable layout. Every "slot" is a
- * `ComponentChildren` so consumers can pass arbitrary JSX (Preact, zfb
- * Island wrappers, server-rendered output projected through the
- * boundary, etc.).
+ * Full prop surface for the composable layout. Every content slot uses
+ * zudo-react's `Child` type so consumers can pass intrinsic descriptions,
+ * package components and zfb island descriptions.
  */
 export interface DocLayoutProps extends DocLayoutHtmlAttrs {
     /** Page title — rendered as the `<title>` value. */
@@ -40,21 +39,20 @@ export interface DocLayoutProps extends DocLayoutHtmlAttrs {
     /** Optional `<meta name="robots" content="noindex">` toggle. */
     noindex?: boolean;
     /**
-     * Free-form children injected at the top of `<head>`, after the
-     * baseline `<title>` / charset / viewport meta. Use this for OG/
-     * Twitter meta, preload hints, color-scheme provider scripts, RSS
-     * links, the `<ClientRouter />` (Astro) or its zfb-equivalent — the
-     * shell stays out of the way.
+     * Pure head descriptions appended after the baseline tags and ClientRouter
+     * metadata. Use this for OG/Twitter metadata, preload hints, color-scheme
+     * providers, prepaint scripts and configured links. The shell serializes
+     * the complete sequence as native head children.
      */
-    head?: ComponentChildren;
+    head?: Child;
     /** Required. The site header. Consumer ships its own `<header>`. */
-    header: ComponentChildren;
+    header: Child;
     /**
      * Optional sidebar content. When omitted (or when `hideSidebar` is
      * true) the desktop-sidebar `<aside>` is not rendered and the
      * content-margin wrapper collapses to full width.
      */
-    sidebar?: ComponentChildren;
+    sidebar?: Child;
     /**
      * Hide the sidebar even if the slot is provided. Mirrors the
      * `hide_sidebar` page frontmatter flag.
@@ -62,9 +60,10 @@ export interface DocLayoutProps extends DocLayoutHtmlAttrs {
     hideSidebar?: boolean;
     /**
      * When present, sets `data-zfb-transition-persist` on the desktop
-     * sidebar `<aside>`. Keyed as `sidebar-{lang}-{navSection}` so zfb's
-     * Strategy B persist swaps reuse the same DOM node across same-locale +
-     * same-section navigations. Omit for back-compat (no attribute). Must
+     * sidebar `<aside>`. Keyed as `sidebar-{lang}-{navSection}` so native zfb
+     * 3.1 persist reconciliation reuses the same DOM node across same-locale +
+     * same-section navigations and retains unchanged descendant island handles.
+     * Omit for back-compat (no attribute). Must
      * NOT be passed when `hideSidebar` is true — the sr-only aside contains
      * no real sidebar content and persisting it conflicts with the new
      * page's tree on cross-type navigations. Resolves #1546.
@@ -74,21 +73,21 @@ export interface DocLayoutProps extends DocLayoutHtmlAttrs {
      * Slot rendered between the desktop sidebar and the content-margin
      * wrapper. Used by the sidebar-toggle feature in `create-zudo-doc`.
      */
-    afterSidebar?: ComponentChildren;
+    afterSidebar?: Child;
     /** Optional breadcrumb shown above the article. */
-    breadcrumb?: ComponentChildren;
+    breadcrumb?: Child;
     /** Optional content slot rendered between breadcrumb and article. */
-    afterBreadcrumb?: ComponentChildren;
+    afterBreadcrumb?: Child;
     /** Optional mobile-only TOC, rendered above the article. */
-    mobileToc?: ComponentChildren;
+    mobileToc?: Child;
     /** Required. The page's article body. */
-    main: ComponentChildren;
+    main: Child;
     /**
      * Optional content slot rendered immediately after `<article>` but
      * still inside `<main>`. Used by the body-foot util area and the
      * doc-history feature.
      */
-    afterContent?: ComponentChildren;
+    afterContent?: Child;
     /**
      * Raw `data-*` attributes spread onto the `<article>` element. This shell
      * stays version/i18n-agnostic on purpose (see the module header), so it
@@ -104,7 +103,7 @@ export interface DocLayoutProps extends DocLayoutHtmlAttrs {
      */
     articleAttrs?: Record<string, string>;
     /** Optional desktop TOC rendered alongside `<main>` on wide screens. */
-    toc?: ComponentChildren;
+    toc?: Child;
     /** Hide the TOC (both desktop and mobile) regardless of slot value. */
     hideToc?: boolean;
     /**
@@ -132,20 +131,20 @@ export interface DocLayoutProps extends DocLayoutHtmlAttrs {
      */
     navSection?: string;
     /** Optional footer rendered below the content. */
-    footer?: ComponentChildren;
+    footer?: Child;
     /**
      * Components rendered just before `</body>`. Use for modals,
      * design-token panels, code-block enhancers, mock initializers, and
      * other globally-mounted islands.
      */
-    bodyEndComponents?: ComponentChildren;
+    bodyEndComponents?: Child;
     /**
      * Scripts / inline `<script>` islands rendered last in `</body>`.
      * Kept distinct from `bodyEndComponents` because the original Astro
      * layout had two separate anchors here, and downstream features (e.g.
      * the sidebar resizer) inject into the scripts slot specifically.
      */
-    bodyEndScripts?: ComponentChildren;
+    bodyEndScripts?: Child;
     /**
      * When `false`, the zfb SPA soft-swap router (`ClientRouter`) is not
      * mounted — the page uses plain full-page navigation instead. This

package/dist/doclayout/doc-layout.js

@@ -1,4 +1,4 @@
-import { jsx, jsxs } from "preact/jsx-runtime";
+import { jsx, jsxs } from "@takazudo/zfb/zudo-react/jsx-runtime";
 import { ClientRouter } from "@takazudo/zfb-runtime";
 const DESKTOP_SIDEBAR_ID = "desktop-sidebar";
 function DocLayout(props) {
@@ -44,14 +44,20 @@ function DocLayout(props) {
   if (htmlStyle !== void 0) {
     htmlAttrs.style = htmlStyle;
   }
-  return /* @__PURE__ */ jsxs("html", { ...htmlAttrs, children: [
-    /* @__PURE__ */ jsxs("head", { children: [
-      /* @__PURE__ */ jsx("meta", { charSet: "utf-8" }),
-      /* @__PURE__ */ jsx("meta", { name: "viewport", content: "width=device-width, initial-scale=1" }),
-      /* @__PURE__ */ jsx("title", { children: title }),
-      description !== void 0 && /* @__PURE__ */ jsx("meta", { name: "description", content: description }),
-      noindex && /* @__PURE__ */ jsx("meta", { name: "robots", content: "noindex, nofollow" }),
-      enableClientRouter !== false ? ClientRouter({
+  const headChildren = [
+    /* @__PURE__ */ jsx("meta", { charset: "utf-8" }),
+    /* @__PURE__ */ jsx("meta", { name: "viewport", content: "width=device-width, initial-scale=1" }),
+    /* @__PURE__ */ jsx("title", { children: title })
+  ];
+  if (description !== void 0) {
+    headChildren.push(/* @__PURE__ */ jsx("meta", { name: "description", content: description }));
+  }
+  if (noindex) {
+    headChildren.push(/* @__PURE__ */ jsx("meta", { name: "robots", content: "noindex, nofollow" }));
+  }
+  if (enableClientRouter !== false) {
+    headChildren.push(
+      ClientRouter({
         preserveHtmlAttrs: [
           "data-sidebar-hidden",
           "data-theme",
@@ -60,9 +66,12 @@ function DocLayout(props) {
           "data-toc-hidden",
           "data-asset-details-hidden"
         ]
-      }) : null,
-      head
-    ] }),
+      })
+    );
+  }
+  if (head !== void 0) headChildren.push(head);
+  return /* @__PURE__ */ jsxs("html", { ...htmlAttrs, children: [
+    /* @__PURE__ */ jsx("head", { children: headChildren }),
     /* @__PURE__ */ jsxs("body", { class: "min-h-screen antialiased", children: [
       header,
       hasSidebar && /* @__PURE__ */ jsx(
@@ -70,7 +79,7 @@ function DocLayout(props) {
         {
           id: DESKTOP_SIDEBAR_ID,
           "aria-label": "Documentation sidebar",
-          class: showSidebar ? "hidden lg:block fixed top-[3.5rem] left-0 z-sidebar w-[var(--zd-sidebar-w)] h-[calc(100vh-3.5rem)] overflow-y-auto bg-bg border-r border-muted pb-vsp-xl" : "sr-only",
+          class: showSidebar ? "hidden lg:block fixed top-[3.5rem] left-0 z-sidebar w-[var(--zd-sidebar-w)] h-[calc(100vh_-_3.5rem)] overflow-y-auto bg-bg border-r border-muted pb-vsp-xl" : "sr-only",
           ...sidebarPersistKey !== void 0 ? { "data-zfb-transition-persist": sidebarPersistKey } : {},
           children: sidebar
         }
@@ -81,7 +90,7 @@ function DocLayout(props) {
         {
           class: `zd-sidebar-content-wrapper${showSidebar ? " lg:ml-[var(--zd-sidebar-w)]" : ""}`,
           children: [
-            /* @__PURE__ */ jsx("div", { class: "flex min-h-[calc(100vh-3.5rem)] justify-center", children: /* @__PURE__ */ jsxs(
+            /* @__PURE__ */ jsx("div", { class: "flex min-h-[calc(100vh_-_3.5rem)] justify-center", children: /* @__PURE__ */ jsxs(
               "div",
               {
                 class: "zd-doc-content-band flex w-full gap-[clamp(1.5rem,3vw,4rem)]",

package/dist/docs-schema/index.d.ts

@@ -38,6 +38,10 @@ export declare function buildDocsSchema(opts?: BuildDocsSchemaOptions): z.ZodObj
     category: z.ZodOptional<z.ZodString>;
     sidebar_position: z.ZodOptional<z.ZodNumber>;
     sidebar_label: z.ZodOptional<z.ZodString>;
+    sidebar_initial_expansion: z.ZodOptional<z.ZodEnum<{
+        collapsed: "collapsed";
+        expanded: "expanded";
+    }>>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>> | z.ZodOptional<z.ZodArray<z.ZodEnum<{
         [x: string]: string;
     }>>>;

package/dist/docs-schema/index.js

@@ -16,6 +16,7 @@ function buildDocsSchema(opts) {
     category: z.string().optional(),
     sidebar_position: z.number().optional(),
     sidebar_label: z.string().optional(),
+    sidebar_initial_expansion: z.enum(["collapsed", "expanded"]).optional(),
     tags: buildTagsSchema(opts),
     search_exclude: z.boolean().optional(),
     pagination_next: z.string().nullable().optional(),