Overview

docs.json is the central configuration file for your docs site. It defines global settings, navigation, and several UI behaviors.

Use this section when you are configuring docs by editing files directly, either locally with the CLI or in source mode.

Where it lives

Place docs.json at the docs root, which is the folder that contains your docs configuration and pages.

Minimal valid example

title and navigation are required.

{  "title": "My Product Docs",  "navigation": {    "pages": ["welcome"]  }}

Core keys

Required keys

• title: Site title.
• navigation: Site navigation structure.

Optional keys

• home: Page path used as the home route.
• logo: Light/dark logo configuration.
• theme: Visual theme settings, including base Tailwind color palette.
• navbar: Top navigation actions and links.
• footer: Social links and footer links.
• playground: Playground settings such as proxy.

Theme base color

Use theme.baseColor to remap all framework neutral-* colors.

Allowed values: slate, gray, zinc, neutral, stone, taupe, mauve, mist, olive.

{  "theme": {    "baseColor": "slate"  }}

Use an object to set different base colors for light and dark mode:

{  "theme": {    "baseColor": {      "light": "mist",      "dark": "neutral"    }  }}

If you provide only one mode in the object, the missing mode defaults to neutral.

If omitted, the default remains neutral.

How page paths work

Page paths in docs.json:

• Use docs-relative paths, for example getting-started/quickstart.
• Do not include .mdx.
• Must reference an existing file.

{  "page": "getting-started/quickstart",  "title": "Quickstart"}

Navigation top-level modes

navigation should use one top-level container for your docs structure. In practice, teams typically choose one of these:

• pages
• menu
• tabs
• openapi

pages mode

{  "navigation": {    "pages": ["welcome", "getting-started/quickstart"]  }}

menu mode

{  "navigation": {    "menu": {      "type": "dropdown",      "items": [        {          "label": "Documentation",          "pages": ["welcome"]        }      ]    }  }}

Use openapi inside menu items when you want an API reference section.

tabs mode

{  "navigation": {    "tabs": {      "presentation": "topbar",      "items": [        {          "label": "Guides",          "pages": ["welcome"]        },        {          "label": "Reference",          "openapi": "openapi.json"        }      ]    }  }}

Use tabs when the primary sections should appear above the sidebar. A tab can contain pages, menu, or openapi. presentation can be topbar, or sidebar; if omitted, it defaults to topbar.

Defaults and fallbacks

• If home is not set, Radiant Docs uses the first documentation page found in navigation.
• Page heading resolution is: frontmatter title -> page title in docs.json -> filename-derived title.
• Navigation labels come from docs.json page titles, not frontmatter.

For heading title behavior, see Format text.

Common validation rules

• navbar.links supports up to 3 links.
• In a menu item, include exactly one of pages or openapi.
• In a tabs item, include exactly one of pages, menu, or openapi.
• OpenAPI include and exclude are mutually exclusive.
• Footer social keys must be one of the supported platform names.
• Footer link href must be either http(s)://... or an internal path starting with /.

Next pages