Cmdocsdocs.json Reference
The single source of truth for your cmdocs site — name, theme, navigation, navbar, and SEO.
docs.json
Every cmdocs project has one docs.json file at its root. It defines what your site is called, how it looks, and how its pages are organized.
Minimal example
The smallest valid docs.json only needs a name and a navigation object:
{
"name": "My Docs",
"navigation": {
"tabs": [
{
"label": "Documentation",
"path": "documentation",
"groups": [
{
"label": "Getting Started",
"pages": [
{ "file": "index" },
{ "file": "quickstart" }
]
}
]
}
]
}
}Top-level fields
Prop
Type
Favicon
Use a single file for every theme, or supply separate light and dark variants. When both are set, the browser tab icon follows the user's system theme via prefers-color-scheme.
{
"favicon": "/favicon.svg"
}{
"favicon": {
"light": "/logo/favicon-light.svg",
"dark": "/logo/favicon-dark.svg"
}
}Paths are resolved against the project root (/favicon.svg reads from public/favicon.svg). dark is optional — if you omit it, the light icon is used in both themes.
Theme
Customize colors and appearance through the theme field. See Theme Configuration for the full reference.
{
"theme": {
"preset": "neutral",
"colors": {
"primary": "#2563EB"
},
"darkMode": true,
"breadcrumb": true,
"lastUpdated": true
}
}Navbar
The navbar holds your title, logo, GitHub link, and any custom links. See Navigation Configuration for navbar link types.
{
"navbar": {
"title": "My Project",
"logo": {
"light": "/logo/light.svg",
"dark": "/logo/dark.svg",
"display": "logo-only"
},
"github": "https://github.com/owner/repo",
"transparent": false,
"homeUrl": "/",
"links": [
{
"text": "Dashboard",
"href": "https://app.example.com",
"icon": "LayoutDashboard",
"external": true
}
]
}
}Prop
Type
Logo
The logo field controls what appears at the top-left of the navbar. There are three ways to use it.
As a string
A simple icon (square, ~24×24) shown next to your site title:
{
"navbar": {
"title": "My Project",
"logo": "/logo/icon.svg"
}
}With light/dark variants (icon + title)
{
"navbar": {
"title": "My Project",
"logo": {
"light": "/logo/light-logo-only.svg",
"dark": "/logo/dark-logo-only.svg"
}
}
}Logo only (recommended when your logo includes your brand name)
{
"navbar": {
"logo": {
"light": "/logo/light.svg",
"dark": "/logo/dark.svg",
"display": "logo-only",
"width": 140,
"height": 36
}
}
}The title field is hidden in logo-only mode — your image should already contain the brand name.
Recommended file structure
| File | Purpose | Shape |
|---|---|---|
light.svg / dark.svg | Full brand logo (icon + text) | Rectangular, ~140×36 |
light-logo-only.svg / dark-logo-only.svg | Icon only | Square, ~24×24 |
Logo props
Prop
Type
Provide either src (single image) or both light and dark (theme variants).
Navigation
The navigation field defines your sidebar. It uses a tabs → groups → pages hierarchy. See Navigation Configuration for the full reference.
{
"navigation": {
"tabMode": "auto",
"tabs": [
{
"label": "Documentation",
"path": "documentation",
"groups": [
{
"label": "Getting Started",
"pages": [
{ "file": "index" },
{ "file": "quickstart" },
{ "file": "installation" }
]
},
{
"label": "Guides",
"pages": [
{ "file": "guides/setup" },
{ "file": "guides/advanced" }
]
}
]
}
]
}
}Footer
{
"footer": {
"text": "Built with cmdocs",
"copyright": "© 2026 My Company",
"links": [
{ "text": "GitHub", "href": "https://github.com/owner/repo" },
{ "text": "Privacy", "href": "/privacy" }
],
"socials": {
"twitter": "https://twitter.com/handle",
"discord": "https://discord.gg/invite"
}
}
}Prop
Type
SEO
{
"seo": {
"title": "My Docs",
"titleTemplate": "%s — My Docs",
"description": "Documentation for my project",
"ogImage": "/og-image.png",
"canonical": true,
"robots": "index, follow"
}
}The titleTemplate uses %s as a placeholder for each page's title — for example, "%s — My Docs" produces "Quickstart — My Docs".
Prop
Type
Search
Search is on by default and uses Orama for client-side full-text indexing.
{
"search": {
"enabled": true,
"provider": "orama"
}
}Prop
Type
Set enabled: false to remove the search box and disable indexing entirely.
AI
Generate machine-readable documentation files for LLMs and AI agents.
{
"ai": {
"llmsTxt": true,
"llmsFullTxt": true
}
}Prop
Type
Both files are produced at the root of your built site (e.g. https://docs.example.com/llms.txt). They follow the llms.txt convention.
OpenAPI
Render OpenAPI specs as API reference pages.
{
"openapi": {
"specs": [
{ "path": "openapi/api.yaml" }
]
}
}Prop
Type
Each spec entry has a single field:
Prop
Type
i18n
Configure internationalization. Locale codes follow the BCP 47 format.
{
"i18n": {
"defaultLocale": "en",
"locales": ["en", "fr", "ja"]
}
}Prop
Type
Validation
cmdocs validates your docs.json against a JSON schema on every build. To get autocomplete and inline errors in your editor, add the $schema field at the top:
{
"$schema": "https://cmdocs.sh/schema/docs.json",
"name": "My Docs"
}Full example
A complete docs.json with every common option:
{
"$schema": "https://cmdocs.sh/schema/docs.json",
"name": "My Project",
"description": "Documentation built with cmdocs",
"favicon": "/logo/icon.svg",
"baseUrl": "https://docs.example.com",
"theme": {
"preset": "neutral",
"colors": { "primary": "#2563EB" },
"darkMode": true,
"breadcrumb": true,
"lastUpdated": true
},
"navbar": {
"title": "My Project",
"logo": {
"light": "/logo/light.svg",
"dark": "/logo/dark.svg",
"display": "logo-only"
},
"github": "https://github.com/owner/repo",
"links": [
{ "text": "Dashboard", "href": "https://app.example.com", "external": true }
]
},
"navigation": {
"tabs": [
{
"label": "Documentation",
"path": "documentation",
"groups": [
{
"label": "Getting Started",
"pages": [
{ "file": "index" },
{ "file": "quickstart" }
]
},
{
"label": "Guides",
"pages": [{ "file": "guides/setup" }]
}
]
}
]
},
"footer": {
"text": "Built with cmdocs",
"copyright": "© 2026 My Company"
},
"seo": {
"title": "My Project Docs",
"titleTemplate": "%s — My Project",
"ogImage": "/og-image.png"
}
}How is this guide?