Configuration
Every key in orbitdocs.config.ts, with its type, default and what it does.
orbitdocs.config.ts sits in the docs app folder. The CLI and the Next plugin both load it and validate it with one schema. This page lists every key.
import { defineConfig } from '@orbitdocs/next/config';
export default defineConfig({
site: { title: 'Acme API' },
apis: [{ id: 'payments', source: { nest: { module: 'dist/app.module.js', build: 'nest build' } } }],
});Loading and validation
- File names, checked in this order in the current folder:
orbitdocs.config.ts,orbitdocs.config.mts,orbitdocs.config.js,orbitdocs.config.mjs. Run the CLI in the docs app folder. defineConfigfrom@orbitdocs/next/config(or@orbitdocs/core) only adds types. It returns the object unchanged.- Validation runs on every CLI command and every Next build. All problems are listed at once, each with its path:
Invalid orbitdocs config:
- apis.0.id: lowercase letters, digits and dashes
- output.basePath: empty or /segment[/segment]Extra checks after the schema:
| Check | Error |
|---|---|
Every group named in access.rules and apis[].access exists in access.groups (or is *) | access: unknown group(s) … |
access has at least one of providers or appSession | access: add at least one sign-in provider, or an appSession |
| API ids are unique | apis: duplicate id … |
Defaults below are applied when a key is left out. "required" means the key has no default.
Top level
Prop
Type
site
Prop
Type
theme
Prop
Type
The plugin writes the resulting CSS to .orbitdocs/theme.css. Change the config, not that file.
apis[]
Prop
Type
source
Prop
Type
source.nest
Prop
Type
navigation
Prop
Type
Link
Prop
Type
HeaderItem
Every header item takes on: 'menu' | 'nav' | 'all' to show it only in the navbar, only in the mobile menu, or in both. Links, icon links and buttons also take active: 'url' | 'nested-url' | 'none': when the item is highlighted, on its exact URL (default), also on pages under it, or never.
Prop
Type
search
Prop
Type
banner
Prop
Type
redirects[]
Prop
Type
Server mode answers with real HTTP redirects. Static builds get an HTML redirect page per rule without *, plus out/_redirects for Netlify and Cloudflare Pages. See Deploy.
layout
Prop
Type
codeBlocks
Prop
Type
Applies to guides and reference/ MDX. Other Shiki options go in lib/source.ts; see Code blocks.
React-only Fumadocs options (slots, custom link items, a search dialog, TOC header and footer) are not config keys; they go in lib/overrides.tsx. See All Fumadocs options.
client
Defaults for the API client. Readers can change their own copy in the client settings.
Prop
Type
access
Private docs. Enforced by the server that serves the docs: mountOrbitDocs, Next server mode or the platform. See Private docs.
Prop
Type
AccessGroup
Prop
Type
SsoProvider
Fields every preset shares (all are OpenID Connect underneath):
Prop
Type
Fields per preset:
type | Extra fields |
|---|---|
google | hostedDomain?: only accept accounts of this Google Workspace domain. |
microsoft | tenantId (required): the Microsoft Entra ID directory (tenant) ID. |
okta | domain (required), such as acme.okta.com. authorizationServer?: a custom authorization server id such as default; omit for the org server. |
auth0 | domain (required), such as acme.us.auth0.com. |
clerk | domain (required): the Clerk Frontend API domain, such as clerk.acme.com. |
keycloak | url (required, URL), such as https://auth.acme.com. realm (required). |
AppSession
Fields every adapter shares:
Prop
Type
type | Extra fields |
|---|---|
supabase | projectUrl (required, URL): https://<ref>.supabase.co or your custom domain. jwtSecretEnv?: for legacy projects with a shared JWT secret, the variable that holds it; otherwise the project's public keys are used. |
clerk | domain (required): the Clerk Frontend API domain. secretKeyEnv?: variable with the Clerk secret key, to look up the email when the session token has none. |
firebase | projectId (required). |
appwrite | endpoint (required, URL), such as https://cloud.appwrite.io/v1. projectId (required). |
ai
Ask AI and the MCP servers. They run on the server that serves the docs. See Ask AI.
Prop
Type
sdks
SDK generation with orbitdocs sdk. TypeScript uses @hey-api/openapi-ts; the other languages use openapi-generator, which needs Java 11 or later. See SDKs.
Prop
Type
Every language takes out: the output folder relative to the docs app, default sdks/<api id>/<language>. {api} in out or a package name is replaced by the API id; without it, several APIs each get <out>/<api id>. See Several APIs.
mock
The mock server of orbitdocs mock. See Mock server.
Prop
Type
lint
Settings for orbitdocs lint. See Linting.
Prop
Type
output
See Deploy for what each mode is for.
Prop
Type
Page frontmatter
Guide pages in content/ accept:
Prop
Type
Operation content pages in reference/<api>/ accept:
Prop
Type