Configuration Options

DocsKit is configured through TypeScript files - no YAML, no JSON config formats to learn. Every configuration surface has type definitions, so your editor catches mistakes before the build does.

Sidebar navigation

The sidebar is driven entirely by src/config/nav.ts. The file exports a nav array of NavGroup objects.

NavGroup fields

NavItem fields

The href must match the path of an MDX file in content/docs/. For example, href: "/docs/api/rate-limits" requires a file at content/docs/api/rate-limits.mdx.

import type { NavGroup } from "@/config/nav";
 
export const nav: NavGroup[] = [
  {
    title: "Getting Started",
    items: [
      { title: "Introduction", href: "/docs/getting-started/introduction" },
      { title: "Installation", href: "/docs/getting-started/installation" },
    ],
  },
  {
    title: "API Reference",
    items: [
      { title: "Endpoints", href: "/docs/api/endpoints" },
      { title: "Error codes", href: "/docs/api/errors" },
    ],
  },
];

Theme customization

All visual design tokens are CSS custom properties in src/app/globals.css. You can retheme DocsKit by editing these variables without touching any component code.

CSS variable reference

Example - switching from violet to a teal accent:

:root {
  --primary: #0d9488;
  --primary-hover: #0f766e;
}

Metadata configuration

Update the root metadata in src/app/layout.tsx. This controls the <title> tag, <meta name="description">, and Open Graph tags on every page.

import type { Metadata } from "next";
 
export const metadata: Metadata = {
  title: {
    template: "%s | Acme Docs",
    default: "Acme Docs - Documentation",
  },
  description:
    "Complete documentation for Acme - including quickstart guides, API reference, and integration examples.",
  openGraph: {
    type: "website",
    siteName: "Acme Docs",
  },
};

The template string uses %s as a placeholder for the page title. For a page whose first heading is # Authentication, the full <title> will be Authentication | Acme Docs.

Canonical URL setup

Canonical URLs prevent duplicate content SEO issues when your docs are accessible from multiple domains. DocsKit reads the canonical domain from an environment variable:

NEXT_PUBLIC_SITE_URL=https://docs.acme.dev

The canonical URL is constructed in src/app/docs/[[...slug]]/page.tsx like this:

const siteUrl = process.env.NEXT_PUBLIC_SITE_URL ?? "https://your-domain.com";
 
// In the page metadata:
alternates: {
  canonical: `${siteUrl}/docs/${params.slug?.join("/") ?? ""}`,
}

Set NEXT_PUBLIC_SITE_URL in your deployment platform's environment variable settings. On Vercel, go to Project Settings > Environment Variables and add it for the Production environment.

Next.js configuration

next.config.ts controls the static export and routing behavior. The defaults work well, but here's what each relevant option does:

import type { NextConfig } from "next";
 
const nextConfig: NextConfig = {
  output: "export",         // Generate static HTML in out/
  trailingSlash: true,      // /docs/intro/ emits as /docs/intro/index.html
  images: {
    unoptimized: true,      // Required for static export (no image server)
  },
};
 
export default nextConfig;

trailingSlash: true is important for static hosts. Without it, navigating directly to /docs/getting-started/introduction on a host like S3 or GitHub Pages would return a 404 because there's no file named introduction - only introduction/index.html.

Pagefind configuration

Pagefind is configured in package.json under the postbuild script:

{
  "scripts": {
    "build": "next build",
    "postbuild": "pagefind --site out --output-path out/pagefind"
  }
}

--site out tells Pagefind where to find the HTML to index. --output-path out/pagefind writes the search index into the static output so it's served alongside your pages.

To exclude specific pages from search results, add a data-pagefind-ignore attribute to the page's HTML. For DocsKit, the easiest way is to add it to the wrapping <div> in the page component for pages you don't want indexed.

Syntax highlighting themes

DocsKit uses Shiki for syntax highlighting. The default theme is vesper. To change it, find the codeToHtml call in src/lib/mdx.ts and update the theme option:

const html = await codeToHtml(code, {
  lang,
  theme: "nord",  // Change to any Shiki theme
});

All Shiki built-in themes are available without additional installation. See shiki.style/themes for the full list and previews.