zudoku 0.80.1 → 0.81.0

package/dist/cli/cli.js

@@ -3023,6 +3023,7 @@ var init_ZudokuConfig = __esm({
       showVersionSelect: z7.enum(["always", "if-available", "hide"]),
       expandAllTags: z7.boolean(),
       showInfoPage: z7.boolean(),
+      disableSecurity: z7.boolean(),
       schemaDownload: z7.object({
         enabled: z7.boolean(),
         fileName: z7.string().regex(/^[A-Za-z0-9_-]+$/).optional()
@@ -3184,6 +3185,7 @@ var init_ZudokuConfig = __esm({
         disablePager: z7.boolean(),
         showLastModified: z7.boolean(),
         fullWidth: z7.boolean().optional(),
+        centered: z7.boolean().optional(),
         suggestEdit: z7.object({
           url: z7.string(),
           text: z7.string().optional()
@@ -3204,7 +3206,10 @@ var init_ZudokuConfig = __esm({
         integrationId: z7.string(),
         organizationId: z7.string(),
         primaryBrandColor: z7.string(),
-        organizationDisplayName: z7.string()
+        organizationDisplayName: z7.string(),
+        searchSettings: z7.custom().optional(),
+        aiChatSettings: z7.custom().optional(),
+        modalSettings: z7.custom().optional()
       }),
       z7.object({
         type: z7.literal("pagefind"),
@@ -3389,6 +3394,11 @@ var init_ZudokuConfig = __esm({
     );
     ThemeConfigSchema = z7.object({
       registryUrl: z7.string().url().optional(),
+      /**
+       * @deprecated Import a `.css` file from your `zudoku.config.ts` instead.
+       * Inline CSS via this option still works but requires a dev server restart
+       * on every change and provides no editor tooling.
+       */
       customCss: z7.union([z7.string(), CssObject]).optional(),
       light: ThemeSchema.optional(),
       dark: ThemeSchema.optional(),
@@ -3401,6 +3411,11 @@ var init_ZudokuConfig = __esm({
       dir: z7.enum(["ltr", "rtl"]).optional(),
       logo: LogoSchema,
       showPoweredBy: z7.boolean().optional(),
+      sidebar: z7.object({
+        collapsible: z7.boolean().optional(),
+        toggleVisibility: z7.enum(["always", "hover"]).optional(),
+        togglePosition: z7.enum(["top", "center", "bottom"]).optional()
+      }).optional(),
       notFoundPage: z7.custom(),
       banner: z7.object({
         message: z7.custom(),
@@ -6670,6 +6685,7 @@ var plugin_docs_default = viteDocsPlugin;
 // src/vite/plugin-markdown-export.ts
 init_loader();
 init_ProtectedRoutesSchema();
+init_ZudokuConfig();
 init_joinUrl();
 import { mkdir as mkdir2, writeFile as writeFile2 } from "node:fs/promises";
 import path13 from "node:path";
@@ -6711,8 +6727,9 @@ var viteMarkdownExportPlugin = () => {
     },
     async buildStart() {
       const config = getCurrentConfig();
-      const llmsConfig = config.docs?.llms;
-      const needsMdFiles = config.docs?.publishMarkdown || llmsConfig?.llmsTxt || llmsConfig?.llmsTxtFull;
+      const docsConfig = DocsConfigSchema.parse(config.docs ?? {});
+      const llmsConfig = docsConfig.llms ?? {};
+      const needsMdFiles = docsConfig.publishMarkdown || llmsConfig.llmsTxt || llmsConfig.llmsTxtFull;
       if (config.__meta.mode === "standalone" || !needsMdFiles) {
         return;
       }
@@ -6736,8 +6753,9 @@ var viteMarkdownExportPlugin = () => {
     },
     async configureServer(server) {
       const config = getCurrentConfig();
-      const llmsConfig = config.docs?.llms;
-      const needsMdFiles = config.docs?.publishMarkdown || llmsConfig?.llmsTxt || llmsConfig?.llmsTxtFull;
+      const docsConfig = DocsConfigSchema.parse(config.docs ?? {});
+      const llmsConfig = docsConfig.llms ?? {};
+      const needsMdFiles = docsConfig.publishMarkdown || llmsConfig.llmsTxt || llmsConfig.llmsTxtFull;
       if (!needsMdFiles) return;
       markdownFiles = await resolveCustomNavigationPaths(
         config,
@@ -6763,8 +6781,9 @@ var viteMarkdownExportPlugin = () => {
     },
     async closeBundle() {
       const config = getCurrentConfig();
-      const llmsConfig = config.docs?.llms;
-      const needsMdFiles = config.docs?.publishMarkdown || llmsConfig?.llmsTxt || llmsConfig?.llmsTxtFull;
+      const docsConfig = DocsConfigSchema.parse(config.docs ?? {});
+      const llmsConfig = docsConfig.llms ?? {};
+      const needsMdFiles = docsConfig.publishMarkdown || llmsConfig.llmsTxt || llmsConfig.llmsTxtFull;
       if (process.env.NODE_ENV !== "production" || Object.keys(markdownFiles).length === 0 || !needsMdFiles) {
         return;
       }
@@ -6795,7 +6814,7 @@ var viteMarkdownExportPlugin = () => {
           console.warn(`Failed to export markdown for ${routePath}:`, error);
         }
       }
-      if (config.docs?.llms?.llmsTxt || config.docs?.llms?.llmsTxtFull) {
+      if (llmsConfig.llmsTxt || llmsConfig.llmsTxtFull) {
         const markdownInfoPath = path13.join(
           config.__meta.rootDir,
           "node_modules/.zudoku/markdown-info.json"
@@ -7039,11 +7058,27 @@ var remarkLastModified = () => {
 // src/vite/mdx/remark-link-rewrite.ts
 import path15 from "node:path";
 import { visit as visit5 } from "unist-util-visit";
-var remarkLinkRewrite = (basePath = "") => (tree) => {
+var markdownExtension = /\.mdx?$/;
+var resolveToRoute = (url, filePath, routesByFile) => {
+  const [, pathname = "", suffix = ""] = url.match(/^([^#?]*)(.*)$/) ?? [];
+  if (!markdownExtension.test(pathname) || pathname.startsWith("/")) {
+    return void 0;
+  }
+  const targetFile = path15.resolve(path15.dirname(filePath), pathname).replace(markdownExtension, "");
+  const route = routesByFile.get(targetFile);
+  if (route === void 0) return void 0;
+  return `${route}${suffix}`;
+};
+var remarkLinkRewrite = (basePath = "", routesByFile = /* @__PURE__ */ new Map()) => (tree, vfile) => {
   visit5(tree, "link", (node) => {
     if (!node.url) return;
     if (node.url.startsWith("http") || node.url.startsWith("mailto:")) return;
     node.url = node.url.replace(/\\/g, "/");
+    const resolved = resolveToRoute(node.url, vfile.path, routesByFile);
+    if (resolved !== void 0) {
+      node.url = resolved;
+      return;
+    }
     const base = path15.posix.join(basePath);
     if (basePath && node.url.startsWith(base)) {
       node.url = node.url.slice(base.length);
@@ -7218,6 +7253,14 @@ var viteMdxPlugin = async () => {
   const config = getCurrentConfig();
   const buildConfig = await getBuildConfig();
   const highlighter = await highlighterPromise;
+  const routesByFile = /* @__PURE__ */ new Map();
+  const fileMapping = await resolveCustomNavigationPaths(
+    config,
+    await globMarkdownFiles(config, { absolute: true })
+  );
+  for (const [route, filePath] of Object.entries(fileMapping)) {
+    routesByFile.set(filePath.replace(/\.mdx?$/, ""), route);
+  }
   const defaultRemarkPlugins = [
     remarkStaticGeneration,
     [remarkInjectFilepath, config.__meta.rootDir],
@@ -7232,7 +7275,7 @@ var viteMdxPlugin = async () => {
     remarkDirective,
     remarkDirectiveRehype,
     remarkCodeTabs,
-    [remarkLinkRewrite, config.basePath],
+    [remarkLinkRewrite, config.basePath, routesByFile],
     [remarkNormalizeImageUrl, config.basePath],
     ...config.build?.remarkPlugins ?? []
   ];

package/dist/declarations/config/validators/ZudokuConfig.d.ts

@@ -57,6 +57,7 @@ declare const ApiOptionsSchema: z.ZodObject<{
     }>>;
     expandAllTags: z.ZodOptional<z.ZodBoolean>;
     showInfoPage: z.ZodOptional<z.ZodBoolean>;
+    disableSecurity: z.ZodOptional<z.ZodBoolean>;
     schemaDownload: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
         fileName: z.ZodOptional<z.ZodOptional<z.ZodString>>;
@@ -92,6 +93,7 @@ declare const ApiSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         }>>;
         expandAllTags: z.ZodOptional<z.ZodBoolean>;
         showInfoPage: z.ZodOptional<z.ZodBoolean>;
+        disableSecurity: z.ZodOptional<z.ZodBoolean>;
         schemaDownload: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodOptional<z.ZodBoolean>;
             fileName: z.ZodOptional<z.ZodOptional<z.ZodString>>;
@@ -127,6 +129,7 @@ declare const ApiSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         }>>;
         expandAllTags: z.ZodOptional<z.ZodBoolean>;
         showInfoPage: z.ZodOptional<z.ZodBoolean>;
+        disableSecurity: z.ZodOptional<z.ZodBoolean>;
         schemaDownload: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodOptional<z.ZodBoolean>;
             fileName: z.ZodOptional<z.ZodOptional<z.ZodString>>;
@@ -162,6 +165,7 @@ declare const ApiSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         }>>;
         expandAllTags: z.ZodOptional<z.ZodBoolean>;
         showInfoPage: z.ZodOptional<z.ZodBoolean>;
+        disableSecurity: z.ZodOptional<z.ZodBoolean>;
         schemaDownload: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodOptional<z.ZodBoolean>;
             fileName: z.ZodOptional<z.ZodOptional<z.ZodString>>;
@@ -302,6 +306,7 @@ export declare const DocsConfigSchema: z.ZodObject<{
         disablePager: z.ZodOptional<z.ZodBoolean>;
         showLastModified: z.ZodOptional<z.ZodBoolean>;
         fullWidth: z.ZodOptional<z.ZodOptional<z.ZodBoolean>>;
+        centered: z.ZodOptional<z.ZodOptional<z.ZodBoolean>>;
         suggestEdit: z.ZodOptional<z.ZodOptional<z.ZodObject<{
             url: z.ZodString;
             text: z.ZodOptional<z.ZodString>;
@@ -524,6 +529,18 @@ export declare const ZudokuConfig: z.ZodObject<{
             reloadDocument: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>;
         showPoweredBy: z.ZodOptional<z.ZodOptional<z.ZodBoolean>>;
+        sidebar: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+            collapsible: z.ZodOptional<z.ZodBoolean>;
+            toggleVisibility: z.ZodOptional<z.ZodEnum<{
+                always: "always";
+                hover: "hover";
+            }>>;
+            togglePosition: z.ZodOptional<z.ZodEnum<{
+                center: "center";
+                top: "top";
+                bottom: "bottom";
+            }>>;
+        }, z.core.$strip>>>;
         notFoundPage: z.ZodOptional<z.ZodCustom<NonNullable<ReactNode>, NonNullable<ReactNode>>>;
         banner: z.ZodOptional<z.ZodObject<{
             message: z.ZodCustom<NonNullable<ReactNode>, NonNullable<ReactNode>>;
@@ -6861,6 +6878,9 @@ export declare const ZudokuConfig: z.ZodObject<{
         organizationId: z.ZodString;
         primaryBrandColor: z.ZodString;
         organizationDisplayName: z.ZodString;
+        searchSettings: z.ZodOptional<z.ZodCustom<import("@inkeep/cxkit-types").InkeepSearchSettings & Record<string, unknown>, import("@inkeep/cxkit-types").InkeepSearchSettings & Record<string, unknown>>>;
+        aiChatSettings: z.ZodOptional<z.ZodCustom<import("@inkeep/cxkit-types").InkeepAIChatSettings & Record<string, unknown>, import("@inkeep/cxkit-types").InkeepAIChatSettings & Record<string, unknown>>>;
+        modalSettings: z.ZodOptional<z.ZodCustom<import("@inkeep/cxkit-types").InkeepModalSettings & Record<string, unknown>, import("@inkeep/cxkit-types").InkeepModalSettings & Record<string, unknown>>>;
     }, z.core.$loose>, z.ZodObject<{
         type: z.ZodLiteral<"pagefind">;
         ranking: z.ZodOptional<z.ZodObject<{
@@ -6890,6 +6910,7 @@ export declare const ZudokuConfig: z.ZodObject<{
             disablePager: z.ZodOptional<z.ZodBoolean>;
             showLastModified: z.ZodOptional<z.ZodBoolean>;
             fullWidth: z.ZodOptional<z.ZodOptional<z.ZodBoolean>>;
+            centered: z.ZodOptional<z.ZodOptional<z.ZodBoolean>>;
             suggestEdit: z.ZodOptional<z.ZodOptional<z.ZodObject<{
                 url: z.ZodString;
                 text: z.ZodOptional<z.ZodString>;
@@ -6923,6 +6944,7 @@ export declare const ZudokuConfig: z.ZodObject<{
             }>>;
             expandAllTags: z.ZodOptional<z.ZodBoolean>;
             showInfoPage: z.ZodOptional<z.ZodBoolean>;
+            disableSecurity: z.ZodOptional<z.ZodBoolean>;
             schemaDownload: z.ZodOptional<z.ZodObject<{
                 enabled: z.ZodOptional<z.ZodBoolean>;
                 fileName: z.ZodOptional<z.ZodOptional<z.ZodString>>;
@@ -6958,6 +6980,7 @@ export declare const ZudokuConfig: z.ZodObject<{
             }>>;
             expandAllTags: z.ZodOptional<z.ZodBoolean>;
             showInfoPage: z.ZodOptional<z.ZodBoolean>;
+            disableSecurity: z.ZodOptional<z.ZodBoolean>;
             schemaDownload: z.ZodOptional<z.ZodObject<{
                 enabled: z.ZodOptional<z.ZodBoolean>;
                 fileName: z.ZodOptional<z.ZodOptional<z.ZodString>>;
@@ -6993,6 +7016,7 @@ export declare const ZudokuConfig: z.ZodObject<{
             }>>;
             expandAllTags: z.ZodOptional<z.ZodBoolean>;
             showInfoPage: z.ZodOptional<z.ZodBoolean>;
+            disableSecurity: z.ZodOptional<z.ZodBoolean>;
             schemaDownload: z.ZodOptional<z.ZodObject<{
                 enabled: z.ZodOptional<z.ZodBoolean>;
                 fileName: z.ZodOptional<z.ZodOptional<z.ZodString>>;
@@ -7024,6 +7048,7 @@ export declare const ZudokuConfig: z.ZodObject<{
             }>>;
             expandAllTags: z.ZodOptional<z.ZodBoolean>;
             showInfoPage: z.ZodOptional<z.ZodBoolean>;
+            disableSecurity: z.ZodOptional<z.ZodBoolean>;
             schemaDownload: z.ZodOptional<z.ZodObject<{
                 enabled: z.ZodOptional<z.ZodBoolean>;
                 fileName: z.ZodOptional<z.ZodOptional<z.ZodString>>;
@@ -7059,6 +7084,7 @@ export declare const ZudokuConfig: z.ZodObject<{
             }>>;
             expandAllTags: z.ZodOptional<z.ZodBoolean>;
             showInfoPage: z.ZodOptional<z.ZodBoolean>;
+            disableSecurity: z.ZodOptional<z.ZodBoolean>;
             schemaDownload: z.ZodOptional<z.ZodObject<{
                 enabled: z.ZodOptional<z.ZodBoolean>;
                 fileName: z.ZodOptional<z.ZodOptional<z.ZodString>>;
@@ -7094,6 +7120,7 @@ export declare const ZudokuConfig: z.ZodObject<{
             }>>;
             expandAllTags: z.ZodOptional<z.ZodBoolean>;
             showInfoPage: z.ZodOptional<z.ZodBoolean>;
+            disableSecurity: z.ZodOptional<z.ZodBoolean>;
             schemaDownload: z.ZodOptional<z.ZodObject<{
                 enabled: z.ZodOptional<z.ZodBoolean>;
                 fileName: z.ZodOptional<z.ZodOptional<z.ZodString>>;
@@ -7194,6 +7221,7 @@ export declare const ZudokuConfig: z.ZodObject<{
             }>>;
             expandAllTags: z.ZodOptional<z.ZodBoolean>;
             showInfoPage: z.ZodOptional<z.ZodBoolean>;
+            disableSecurity: z.ZodOptional<z.ZodBoolean>;
             schemaDownload: z.ZodOptional<z.ZodObject<{
                 enabled: z.ZodOptional<z.ZodBoolean>;
                 fileName: z.ZodOptional<z.ZodOptional<z.ZodString>>;

package/dist/declarations/lib/components/context/ZudokuContext.d.ts

@@ -1,6 +1,6 @@
 import type { NavigationItem } from "../../../config/validators/NavigationSchema.js";
 export declare const useZudoku: () => import("../../core/ZudokuContext.js").ZudokuContext;
-export declare const useApiIdentities: () => import("@tanstack/react-query").UseQueryResult<import("../../core/ZudokuContext.js").ApiIdentity[], Error>;
+export declare const useApiIdentities: () => import("@tanstack/react-query").UseQueryResult<NoInfer<import("../../core/ZudokuContext.js").ApiIdentity[]>, Error>;
 export declare const useCurrentNavigation: () => {
     navigation: NavigationItem[];
     topNavItem: import("../../../config/validators/NavigationSchema.js").NavigationDoc | import("../../../config/validators/NavigationSchema.js").NavigationLink | import("../../../config/validators/NavigationSchema.js").NavigationCategory | import("../../../config/validators/NavigationSchema.js").NavigationCustomPage | import("../../../config/validators/NavigationSchema.js").NavigationSeparator | {

package/dist/declarations/lib/components/navigation/SidebarToggle.d.ts

@@ -0,0 +1 @@
+export declare const SidebarToggle: () => import("react/jsx-runtime").JSX.Element;

package/dist/declarations/lib/components/navigation/sidebarStore.d.ts

@@ -0,0 +1,6 @@
+type SidebarState = {
+    isCollapsed: boolean;
+    toggle: () => void;
+};
+export declare const useSidebar: import("zustand").UseBoundStore<import("zustand").StoreApi<SidebarState>>;
+export {};

package/dist/declarations/lib/core/ZudokuContext.d.ts

@@ -51,6 +51,11 @@ type Metadata = Partial<{
 type Site = Partial<{
     dir?: "ltr" | "rtl";
     showPoweredBy?: boolean;
+    sidebar?: {
+        collapsible?: boolean;
+        toggleVisibility?: "always" | "hover";
+        togglePosition?: "top" | "center" | "bottom";
+    };
     title?: string;
     logo?: {
         src: {

package/dist/declarations/lib/hooks/index.d.ts

@@ -5,4 +5,5 @@ export { CACHE_KEYS, useCache } from "../components/cache.js";
 export { useZudoku } from "../components/context/ZudokuContext.js";
 export { useExposedProps } from "../util/useExposedProps.js";
 export { useEvent } from "./useEvent.js";
+export { useSidebar } from "../components/navigation/sidebarStore.js";
 export { useCopyToClipboard } from "../util/useCopyToClipboard.js";

package/dist/declarations/lib/plugins/markdown/index.d.ts

@@ -7,7 +7,7 @@ export interface MarkdownPluginOptions extends ZudokuDocsConfig {
     basePath: string;
     fileImports: Record<string, () => Promise<MDXImport>>;
 }
-export type MarkdownPluginDefaultOptions = Pick<Frontmatter, "toc" | "disablePager" | "showLastModified" | "suggestEdit" | "copyPage" | "fullWidth">;
+export type MarkdownPluginDefaultOptions = Pick<Frontmatter, "toc" | "disablePager" | "showLastModified" | "suggestEdit" | "copyPage" | "fullWidth" | "centered">;
 export type Frontmatter = {
     title?: string;
     description?: string;
@@ -24,6 +24,7 @@ export type Frontmatter = {
     } | false;
     copyPage?: boolean;
     fullWidth?: boolean;
+    centered?: boolean;
 };
 export type MDXImport = {
     tableOfContents: Toc;

package/dist/declarations/lib/plugins/search-inkeep/index.d.ts

@@ -1,8 +1,14 @@
-import type { InkeepBaseSettings, InkeepJS } from "@inkeep/cxkit-types";
+import type { InkeepAIChatSettings, InkeepBaseSettings, InkeepJS, InkeepModalSettings, InkeepSearchSettings } from "@inkeep/cxkit-types";
 import type { ZudokuPlugin } from "../../core/plugins.js";
 declare global {
     interface Window {
         Inkeep: InkeepJS | undefined;
     }
 }
-export declare const inkeepSearchPlugin: (settings: InkeepBaseSettings) => ZudokuPlugin;
+export type InkeepSearchPluginOptions = InkeepBaseSettings & Record<string, unknown> & {
+    type?: "inkeep";
+    searchSettings?: InkeepSearchSettings & Record<string, unknown>;
+    aiChatSettings?: InkeepAIChatSettings & Record<string, unknown>;
+    modalSettings?: InkeepModalSettings & Record<string, unknown>;
+};
+export declare const inkeepSearchPlugin: (settings: InkeepSearchPluginOptions) => ZudokuPlugin;

package/dist/flat-config.d.ts

@@ -136,6 +136,11 @@ export interface FlatZudokuConfig {
     dir?: ("ltr" | "rtl")
     logo?: _Schema0
     showPoweredBy?: boolean
+    sidebar?: {
+      collapsible?: boolean
+      toggleVisibility?: ("always" | "hover")
+      togglePosition?: ("top" | "center" | "bottom")
+    }
     notFoundPage?: unknown
     banner?: {
       message: unknown
@@ -351,6 +356,9 @@ export interface FlatZudokuConfig {
     organizationId: string
     primaryBrandColor: string
     organizationDisplayName: string
+    searchSettings?: unknown
+    aiChatSettings?: unknown
+    modalSettings?: unknown
     [k: string]: unknown
   } | {
     type: "pagefind"
@@ -376,6 +384,7 @@ export interface FlatZudokuConfig {
       disablePager?: boolean
       showLastModified?: boolean
       fullWidth?: boolean
+      centered?: boolean
       suggestEdit?: {
         url: string
         text?: string
@@ -494,6 +503,7 @@ export interface _Schema22 {
   showVersionSelect?: ("always" | "if-available" | "hide")
   expandAllTags?: boolean
   showInfoPage?: boolean
+  disableSecurity?: boolean
   schemaDownload?: {
     enabled?: boolean
     fileName?: string

package/docs/components/callout.mdx

@@ -193,24 +193,17 @@ Or pass any React node as the `icon` to override the default for the chosen `typ
 ## Customize colors
 
 Each callout type is driven by a single CSS variable that determines the icon, border tint, and
-background tint via `color-mix`. Override any of them in your theme's `customCss` to recolor a type
-globally:
-
-```ts title="zudoku.config.ts"
-export default {
-  theme: {
-    customCss: `
-      :root {
-        --callout-tip: oklch(0.65 0.18 160);
-        --callout-sparkles: oklch(0.6 0.22 320);
-      }
-      .dark {
-        --callout-tip: oklch(0.78 0.18 160);
-        --callout-sparkles: oklch(0.75 0.2 320);
-      }
-    `,
-  },
-};
+background tint via `color-mix`. Override any of them in your stylesheet to recolor a type globally:
+
+```css title=styles.css
+:root {
+  --callout-tip: oklch(0.65 0.18 160);
+  --callout-sparkles: oklch(0.6 0.22 320);
+}
+.dark {
+  --callout-tip: oklch(0.78 0.18 160);
+  --callout-sparkles: oklch(0.75 0.2 320);
+}
 ```
 
 All available variables:

package/docs/configuration/search.md

@@ -168,3 +168,39 @@ your [Zudoku Configuration](./overview.md):
   // ...
 }
 ```
+
+### Customizing Inkeep
+
+Any other [base settings](https://docs.inkeep.com/cloud/ui-components/common-settings/base) can be
+set alongside the required fields, for example `filters` to scope results or `transformSource` to
+customize how sources are displayed.
+
+You can also pass
+[`searchSettings`](https://docs.inkeep.com/cloud/ui-components/common-settings/search),
+[`aiChatSettings`](https://docs.inkeep.com/cloud/ui-components/common-settings/ai-chat), and
+`modalSettings` to customize the respective parts of the search experience. They are merged with
+Zudoku's defaults and passed through to Inkeep as-is, so any option Inkeep supports can be used —
+including ones added after this Zudoku version was released.
+
+For example, to categorize results into tabs based on their URL:
+
+```typescript
+{
+  // ...
+  search: {
+    type: "inkeep",
+    // ...required fields from above
+    transformSource: (source) => {
+      if (!source.url.includes("/blog/")) return source;
+      return { ...source, tabs: [...(source.tabs ?? []), "Blog"] };
+    },
+    searchSettings: {
+      tabs: [["All", { isAlwaysVisible: true }], "Blog"],
+    },
+    aiChatSettings: {
+      aiAssistantName: "My Assistant",
+    },
+  },
+  // ...
+}
+```

package/docs/configuration/site.md

@@ -127,6 +127,44 @@ export const NotFound = () => (
 
 ## Layout
 
+### Collapsible Sidebar
+
+The navigation sidebar is collapsible by default. A small toggle button on the sidebar's right
+border lets users hide and reveal it. Configure the behavior under `site.sidebar`:
+
+```tsx title=zudoku.config.tsx
+{
+  site: {
+    sidebar: {
+      collapsible: true, // default: true. Set to false to disable the toggle entirely.
+      toggleVisibility: "always", // "always" (default) or "hover" — show button only when hovering the sidebar's right edge
+      togglePosition: "bottom", // "top", "center", or "bottom" (default)
+    },
+  }
+}
+```
+
+For finer vertical placement, override the `--sidebar-toggle-y` CSS variable in your stylesheet:
+
+```css
+:root {
+  --sidebar-toggle-y: 30%;
+}
+```
+
+The toggle button carries `aria-expanded="true"` when the sidebar is open and `"false"` when
+collapsed. Combine it with the `[data-sidebar-toggle]` selector to position the button differently
+per state:
+
+```css
+[data-sidebar-toggle][aria-expanded="true"] {
+  --sidebar-toggle-y: 20%;
+}
+[data-sidebar-toggle][aria-expanded="false"] {
+  --sidebar-toggle-y: 80%;
+}
+```
+
 ### Banner
 
 Add a banner message to the top of the page:

package/docs/customization/colors-theme.mdx

@@ -164,29 +164,55 @@ const config = {
 };
 ```
 
-Alternatively, you can copy the CSS code and paste it into your `customCss` configuration:
+Alternatively, paste the copied CSS into a stylesheet and import it from your config:
+
+```css title=styles.css
+/* Copied CSS code */
+```
 
 ```ts title=zudoku.config.ts
-const config = {
-  theme: {
-    customCss: `
-      /* Copied CSS code */
-    `,
-  },
-};
+import "./styles.css";
 ```
 
 ## Custom CSS
 
-For advanced styling, you can add custom CSS either as a string or structured object:
+The recommended way to add custom styles is to write a `.css` file alongside your config and import
+it. This gives you HMR during development, syntax highlighting, autocompletion, and lets you split
+styles across files as your site grows.
 
-:::note
+```css title=styles.css
+.custom {
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+}
+```
 
-Changes to `customCss` require restarting the development server to take effect.
+```ts title=zudoku.config.ts
+import "./styles.css";
 
-:::
+const config = {
+  // ...
+};
+```
+
+If TypeScript reports `Cannot find module './styles.css'`, add `zudoku/client` to your tsconfig
+types so CSS side-effect imports are recognized:
+
+```json title=tsconfig.json
+{
+  "compilerOptions": {
+    "types": ["zudoku/client"]
+  }
+}
+```
+
+Projects created with `create-zudoku` include this by default.
+
+### Inline alternatives (deprecated)
 
-### CSS String
+The `theme.customCss` option is deprecated and will be removed in a future release. It still accepts
+a CSS string or object for backwards compatibility, but every change requires restarting the dev
+server and you lose syntax highlighting, autocompletion, and HMR. Migrate to an imported `.css`
+file.
 
 ```ts title=zudoku.config.ts
 const config = {
@@ -200,37 +226,22 @@ const config = {
 };
 ```
 
-### CSS Object
-
-```ts title=zudoku.config.ts
-const config = {
-  theme: {
-    customCss: {
-      ".custom": {
-        background: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
-      },
-    },
-  },
-};
-```
-
 ### Enabling Code Ligatures
 
 Zudoku disables ligatures in code blocks by default to avoid unwanted glyph joining in fonts like
 Geist Mono (e.g. `---`, `###`, `|--|`). If you're using a coding font designed around ligatures
-(Fira Code, JetBrains Mono, etc.), re-enable them via `customCss`:
-
-```ts title=zudoku.config.ts
-const config = {
-  theme: {
-    customCss: `
-      code, pre, kbd, samp, .shiki, .shiki span {
-        font-variant-ligatures: normal;
-        font-feature-settings: normal;
-      }
-    `,
-  },
-};
+(Fira Code, JetBrains Mono, etc.), re-enable them in your CSS file:
+
+```css title=styles.css
+code,
+pre,
+kbd,
+samp,
+.shiki,
+.shiki span {
+  font-variant-ligatures: normal;
+  font-feature-settings: normal;
+}
 ```
 
 ## Default Theme

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zudoku",
-  "version": "0.80.1",
+  "version": "0.81.0",
   "type": "module",
   "sideEffects": [
     "**/*.css",
@@ -213,12 +213,12 @@
     "@tailwindcss/typography": "0.5.19",
     "@tailwindcss/vite": "4.3.0",
     "@tanem/react-nprogress": "6.0.3",
-    "@tanstack/react-query": "5.97.0",
+    "@tanstack/react-query": "5.101.0",
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
-    "@vitejs/plugin-react": "6.0.1",
+    "@vitejs/plugin-react": "6.0.2",
     "@x0k/json-schema-merge": "1.0.3",
-    "@unhead/react": "3.1.0",
+    "@unhead/react": "3.1.3",
     "@zuplo/mcp": "0.0.32",
     "bs58": "6.0.0",
     "class-variance-authority": "0.7.1",