---
title: Overview
description: Learn what docs.json controls when you configure docs from source files.
---

`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.

<Callout type="info" title="Prefer no-code controls?">
Use dashboard [Settings](/edit-in-dashboard/settings) and
[Manage navigation](/edit-in-dashboard/manage-navigation) when you want to
configure your docs without editing JSON.
</Callout>

## Where it lives

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

<Callout type="tip" title="One source of truth">
The CLI and dashboard both read and write this same `docs.json` file.
</Callout>

## Minimal valid example

`title` and `navigation` are required.

```json
{
  "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`.

```json
{
  "theme": {
    "baseColor": "slate"
  }
}
```

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

```json
{
  "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.

```json
{
  "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

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

### `menu` mode

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

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

### `tabs` mode

```json
{
  "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](/edit-markdown/format-text#page-titles).

## 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

<Columns columns={3}>
  <Column>

  <Card title="Navigation" href="/configure-with-docs-json/navigation" icon="lucide:list-tree">
    Shape sidebars and menus.
  </Card>

  </Column>
  <Column>

  <Card title="Branding" href="/configure-with-docs-json/branding" icon="lucide:palette">
    Set logos and identity.
  </Card>

  </Column>
  <Column>

  <Card title="Navbar and footer" href="/configure-with-docs-json/navbar-and-footer" icon="lucide:panel-top">
    Configure global links.
  </Card>

  </Column>
</Columns>