Custom themes

Use a custom theme when the default documentation layout is not enough for your project. A custom theme is a local TypeScript module that implements the docs theme contract.

Configure the theme path

Point theme.path at the local theme directory or entrypoint in the project's docs.config.ts:

// docs.config.ts
export default {
  theme: {
    path: "./src/themes/custom",
  },
};

The theme path is resolved from the project root. Keep the theme in the consumer project so its layout and styling remain fully owned by that project.

Theme contract

A custom theme is defined in the consumer project, not inside the package. Create src/themes/custom/index.tsx next to the project's docs.config.ts. That module must export a default DocsThemeContract object with the required name and Layout fields. Other components are optional and can replace the default navbar, sidebar, table of contents, breadcrumbs, pager, or search dialog.

// src/themes/custom/index.tsx
import type { DocsThemeContract } from "@nikala-ui/folio/theme";
import { CustomLayout } from "./layout";

const customTheme: DocsThemeContract = {
  name: "custom",
  Layout: CustomLayout,
};

export default customTheme;

The Layout component itself can live in the same directory:

// src/themes/custom/layout.tsx
import type { Component } from "solid-js";
import type { DocsLayoutProps } from "@nikala-ui/folio/theme";

export const CustomLayout: Component<DocsLayoutProps> = (props) => (
  <main>
    <h1>{props.currentPage?.title}</h1>
    {props.children}
  </main>
);

The layout receives the resolved site configuration, navigation tree, current page, table-of-contents data, and previous/next page links through DocsLayoutProps. Use those values instead of coupling the theme to a specific documentation site's content.

Keep runtime behavior separate

Use docs.config.ts for site configuration such as title, navigation, and the default color mode. Use the theme module for layout and component composition. Keep colors and design tokens in the project's CSS entrypoint.