Copy page

Configuration

Branding & Layout

We offer you to customize the main aspects of your Dev Portal site's appearance and behavior.

Branding

Title, logo can be configured in under the site property:

Code
const config = {
  site: {
    title: "My API Documentation",
    logo: {
      src: {
        light: "/path/to/light-logo.png",
        dark: "/path/to/dark-logo.png",
      },
      alt: "Company Logo",
      href: "/",
    },
    // Other options...
  },
};

Available Options

Title

Set the title of your site next to the logo in the header:

Code
{
  site: {
    title: "My API Documentation",
  }
}

Logo

Configure the site's logo with different versions for light and dark themes:

Code
{
  site: {
    logo: {
      src: {
        light: "/light-logo.png",
        dark: "/dark-logo.png"
      },
      alt: "Company Logo",
      width: "120px", // optional width
      href: "/", // optional link target (defaults to "/")
      reloadDocument: true, // optional, defaults to true
    }
  }
}

The reloadDocument option controls whether clicking the logo triggers a full page reload (true, the default) or uses client-side SPA navigation (false). A full reload is useful when your landing page is served by a different system (e.g. a CMS) outside of Zudoku.

Direction (RTL/LTR)

Set the text direction for your site. This is useful for right-to-left languages:

Code
{
  site: {
    dir: "rtl", // "ltr" (default) or "rtl"
  }
}

Colors & Theme

We allow you to fully customize all colors, borders, etc - read more about it in Colors & Themes

Custom 404 Page

Replace the default "Page not found" page with your own component using the notFoundPage option:

Code
import { NotFound } from "./src/NotFound";

const config = {
  site: {
    notFoundPage: <NotFound />,
  },
};

Your component will be rendered whenever a user navigates to a route that doesn't exist. This works in both development and production builds.

Here's an example of a custom 404 component:

Code
import { Button, Link } from "zudoku/components";

export const NotFound = () => (
  <section className="flex items-center justify-center py-20">
    <div className="text-center max-w-lg mx-auto">
      <p className="text-6xl font-extrabold text-primary mb-4">404</p>
      <h1 className="text-3xl font-bold mb-4">Page not found</h1>
      <p className="text-muted-foreground mb-8">
        The page you're looking for doesn't exist or has been moved.
      </p>
      <Button asChild>
        <Link to="/">Go back home</Link>
      </Button>
    </div>
  </section>
);

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:

Code
{
  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:

Code
: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:

Code
[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:

Code
{
  site: {
    banner: {
      message: "Welcome to our beta documentation!",
      color: "info", // "note" | "tip" | "info" | "caution" | "danger" or custom
      dismissible: true
    }
  }
}

Footer

The footer configuration has its own dedicated section. See the Footer Configuration for details.

Complete Example

Here's a comprehensive example showing all available page configuration options:

Code
{
  site: {
    title: "My API Documentation",
    logo: {
      src: {
        light: "/images/logo-light.svg",
        dark: "/images/logo-dark.svg"
      },
      alt: "Company Logo",
      width: "100px",
    },
    notFoundPage: <NotFound />,
    banner: {
      message: "Welcome to our documentation!",
      color: "info",
      dismissible: true
    },
  }
}