Logo
Docs

docs.json overview

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

Where it lives

Place docs.json at the root of your documentation folder.

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 should use one top-level container for your docs structure. In practice, teams typically choose one of these:

  • pages
  • menu

pages mode

{  "navigation": {    "pages": ["welcome", "getting-started/quickstart"]  }}
{  "navigation": {    "menu": {      "type": "dropdown",      "items": [        {          "label": "Documentation",          "submenu": {            "pages": ["welcome"]          }        }      ]    }  }}

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

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, submenu must contain exactly one of pages 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