Config
Full reference for defineConfig, DocsConfig, and ResolvedDocsConfig.
import { defineConfig, normalizeBaseUrl, defaultMarkdownPath } from "pzzadocs";
import type { DocsConfig, ResolvedDocsConfig, UiLabels, LocaleStrategy, LocalePrefix } from "pzzadocs";defineConfig#
function defineConfig(config: DocsConfig): ResolvedDocsConfig;Validates the shape of your config at compile time and applies defaults to every optional section. Export its result as the default export of docs.config.ts and import that module wherever a config is needed: createSource, RootProvider, and DocsLayout.
DocsConfig#
interface DocsConfig {
title: string;
description?: string;
logo?: ReactNode | ImageLogo;
homeUrl?: string;
contentDir?: string;
baseUrl?: string;
siteUrl?: string;
nav?: NavConfig;
editUrl?: (page: PageData) => string;
search?: SearchConfig;
theme?: ThemeConfig;
toc?: TocConfig;
llm?: LlmConfig;
math?: MathConfig;
sidebar?: SidebarConfig;
header?: HeaderConfig;
lastModified?: "git" | "fs" | false;
defaultLocale?: string;
locales?: string[];
localeStrategy?: LocaleStrategy;
localePrefix?: LocalePrefix;
translations?: Record<string, Partial<UiLabels>>;
}Top level#
| Name | Type | Default | Description |
|---|---|---|---|
title* | string | - | Site name. Rendered as the header wordmark. |
description | string | - | Short description of the site. |
logo | ReactNode | ImageLogo | - | Rendered left of the wordmark. An ImageLogo is { src, alt?, width?, height? }. |
homeUrl | string | "/" | Where the logo links. Localized sites pass the locale's home, for example /de. |
contentDir | string | "content/docs" | Content folder, relative to process.cwd() or absolute. |
baseUrl | string | "/docs" | Route prefix where the docs are mounted. Normalized to a leading slash and no trailing slash. |
siteUrl | string | - | Public origin of the site, for example https://docs.pzza.works (trailing slash stripped). When set, llms.txt, llms-full.txt and the assistant prompts in the page actions menu use absolute URLs. |
editUrl | (page: PageData) => string | - | Builds the Edit on GitHub link. When set, the footer also shows the last updated time and the page actions menu gets an Open in GitHub entry. |
lastModified | "git" | "fs" | false | "git" | Where lastModified comes from: the last git commit touching the file (falling back to mtime), the filesystem mtime, or nothing. |
Locales#
See the Localization guide for the content strategies, URL prefixes, and route wiring.
| Name | Type | Default | Description |
|---|---|---|---|
defaultLocale | string | - | Locale of the source content. With the suffix strategy, files without a suffix belong to it; with the directory strategy it names the source directory and is required. |
locales | string[] | [] | Translated locales. Each may appear as a file suffix (page.de.mdx, meta.de.json) or as a directory under contentDir. |
localeStrategy | LocaleStrategy | "suffix" | "suffix" keeps translations next to the source file; "directory" lays contentDir/<locale> over contentDir/<defaultLocale>, falling back file by file. |
localePrefix | LocalePrefix | "never" | Locale segment before baseUrl in page URLs: never, only for non-default locales ("as-needed"), or always. |
translations | Record<string, Partial<UiLabels>> | - | UI string overrides keyed by locale, merged over the English defaults by resolveLabels. |
type LocaleStrategy = "suffix" | "directory";
type LocalePrefix = "never" | "as-needed" | "always";UiLabels lists every string the framework renders; the full key reference with defaults is in the Localization guide. DEFAULT_LABELS, resolveLabels(config, locale), and fillLabel(template, values) are exported from the root entry.
nav#
| Name | Type | Default | Description |
|---|---|---|---|
links | NavLink[] | [] | Horizontal tabs in the header. |
links[].text* | string | - | Tab label. |
links[].href* | string | - | Destination. |
links[].activePrefix | string | - | Route prefix that marks the tab active, for example /docs/components for a tab linking to the first component page. Defaults to the href. |
links[].external | boolean | - | Opens in a new tab with an external icon. Inferred from the href when omitted. |
github | string | - | Repository URL rendered as an icon link. |
cta | { text: string; href: string } | - | Outline button at the far right of the header. |
search#
| Name | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Shows the trigger, registers the shortcut, and renders the dialog. |
indexUrl | string | "/api/search" | Endpoint returning SearchRecord[] as JSON. |
hotKey | string | "k" | Key combined with Meta or Ctrl that opens the dialog. |
theme#
| Name | Type | Default | Description |
|---|---|---|---|
defaultTheme | "light" | "dark" | "system" | "system" | Theme before the visitor picks one. |
hotKey | boolean | true | Pressing D outside inputs toggles light and dark. |
toc#
| Name | Type | Default | Description |
|---|---|---|---|
minDepth | number | 2 | Smallest heading level collected into the TOC. |
maxDepth | number | 3 | Largest heading level collected into the TOC. |
llm#
| Name | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Enables the Markdown and llms.txt outputs and the page actions menu. |
markdownPath | (url: string) => string | defaultMarkdownPath | Maps a page URL to the route serving its raw Markdown. The default appends .mdx (the root index becomes /index.mdx when baseUrl is /). |
math#
| Name | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Parses TeX math and renders it with KaTeX at compile time. Import pzzadocs/math.css once for the fonts and layout. |
singleDollar | boolean | false | Also treats single-dollar spans like $x$ as inline math. Off by default so prices in prose stay plain text. |
sidebar#
| Name | Type | Default | Description |
|---|---|---|---|
defaultOpenLevel | number | 0 | Folders at this depth or shallower start open unless they set defaultOpen themselves. |
prefetch | boolean | true | Prefetch sidebar links with next/link. |
header#
| Name | Type | Default | Description |
|---|---|---|---|
transparentMode | "none" | "top" | "always" | "none" | top makes the header transparent until the page scrolls; always keeps it transparent. |
ResolvedDocsConfig#
The return type of defineConfig: DocsConfig with every default applied. This is what createSource, RootProvider, and DocsLayout accept, and it is why config.llm.markdownPath can be called without a null check in route files.
interface ResolvedDocsConfig extends DocsConfig {
contentDir: string;
baseUrl: string;
siteUrl?: string;
search: Required<SearchConfig>;
theme: Required<ThemeConfig>;
toc: Required<TocConfig>;
llm: Required<LlmConfig>;
math: Required<MathConfig>;
sidebar: Required<SidebarConfig>;
header: Required<HeaderConfig>;
lastModified: "git" | "fs" | false;
locales: string[];
localeStrategy: LocaleStrategy;
localePrefix: LocalePrefix;
}Helpers#
function normalizeBaseUrl(baseUrl: string): string;
function defaultMarkdownPath(url: string): string;normalizeBaseUrl trims whitespace, strips trailing slashes, ensures a leading slash, and maps an empty string to "/". defaultMarkdownPath is the default llm.markdownPath: it appends .mdx to the URL and maps / to /index.mdx. Both are exported so custom routing code can stay consistent with the framework.
Example#
This site's config:
import { defineConfig } from "pzzadocs";
export default defineConfig({
title: "PzzaDocs",
description: "A customizable MDX docs framework for Next.js.",
contentDir: "content/docs",
baseUrl: "/docs",
nav: {
links: [
{ text: "Overview", href: "/docs" },
{ text: "Components", href: "/docs/components/callout", activePrefix: "/docs/components" },
{ text: "API", href: "/docs/api/config", activePrefix: "/docs/api" },
],
github: "https://github.com/pzzaworks/pzza-docs",
},
editUrl: (page) => `https://github.com/pzzaworks/pzza-docs-web/edit/main/content/docs/${page.file}`,
search: { enabled: true },
theme: { defaultTheme: "system" },
});