---
title: Navigation
description: Configure sidebar navigation with pages, groups, menus, tabs, and OpenAPI sources.
---
Navigation controls how readers move through your docs. It also controls which
MDX pages are included in the built site.
Use this page when you are editing `docs.json` directly. Use dashboard
[Manage navigation](/edit-in-dashboard/manage-navigation) when you want to
organize pages without editing JSON.
## Choose one navigation mode
`navigation` must contain exactly one top-level mode:
| Mode | Use it when |
| --- | --- |
| `pages` | Your docs use one sidebar structure |
| `menu` | Your docs need multiple top-level sections |
| `tabs` | Your docs need primary sections above the sidebar |
| `openapi` | The site is primarily a generated API reference |
Do not combine top-level modes in the same `navigation` object.
## Pages mode
Use `pages` for most documentation sites.
```json
{
"navigation": {
"pages": [
"welcome",
"getting-started/quickstart"
]
}
}
```
Page paths are relative to the docs root. Do not start them with `/`, and do
not include `.mdx`.
## Page objects
Use a page object when a navigation entry needs a custom title, icon, or tag.
```json
{
"page": "getting-started/quickstart",
"title": "Quickstart",
"icon": "lucide:rocket",
"tag": "New"
}
```
`title` changes the navigation label. The rendered page heading can still come
from the page frontmatter.
## Groups
Use groups to organize related pages in the sidebar.
```json
{
"group": "Get started",
"icon": "lucide:book-open",
"expanded": true,
"pages": [
"getting-started/welcome",
"getting-started/quickstart"
]
}
```
Groups must include a `pages` array. Groups can include `icon`, `expanded`, and
`tag`.
## Nested groups
Groups can be nested, but keep the structure shallow. Radiant supports groups up
to two levels deep.
```json
{
"group": "Edit Markdown",
"pages": [
"edit-markdown/format-text",
{
"group": "Components",
"expanded": true,
"pages": [
"edit-markdown/components/card",
"edit-markdown/components/callout"
]
}
]
}
```
Avoid deeper nesting. If a page is hard to place within two group levels, the
section may need clearer names or a separate top-level menu.
## Menus
Use `navigation.menu` when a docs site needs multiple top-level areas, such as
Guides and API Reference.
```json
{
"navigation": {
"menu": {
"type": "segmented",
"label": "Select docs section",
"items": [
{
"label": "Guides",
"icon": "lucide:book-open",
"pages": ["getting-started/quickstart"]
},
{
"label": "API Reference",
"icon": "lucide:file-code-2",
"openapi": "openapi.json"
}
]
}
}
}
```
`menu.type` can be `dropdown` or `segmented`. If omitted, it defaults to
`dropdown`.
Each menu item needs a `label` and exactly one content key: `pages` or
`openapi`.
## Tabs
Use `navigation.tabs` when a site needs primary sections above the sidebar. A
tab can go straight to pages, hold a menu, or generate an OpenAPI reference.
```json
{
"navigation": {
"tabs": {
"presentation": "topbar",
"items": [
{
"label": "Guides",
"root": true,
"icon": "lucide:book-open",
"pages": ["getting-started/quickstart"]
},
{
"label": "Reference",
"slug": "api",
"icon": "lucide:file-code-2",
"menu": {
"type": "segmented",
"items": [
{
"label": "REST API",
"openapi": "openapi.json"
},
{
"label": "SDKs",
"pages": ["sdks/javascript"]
}
]
}
}
]
}
}
}
```
Each tab needs a `label` and exactly one content key: `pages`, `menu`, or
`openapi`. Use `slug` when the URL segment should differ from the label. Set
`root: true` on one tab when its routes should not include a tab URL segment.
For example, a root Guides tab can publish `/getting-started/quickstart` while
the Reference tab publishes below `/api`. A root tab cannot also define
`slug`, and a tabs configuration can contain at most one root tab.
`tabs.presentation` controls where the tab bar appears:
| Presentation | Behavior |
| --- | --- |
| `topbar` | Shows a full-width tab bar below the navbar. This is the default. |
| `sidebar` | Shows the tab bar above the sidebar navigation, constrained to sidebar width on desktop. |
## OpenAPI navigation
Use `openapi` when Radiant should generate API reference pages from an OpenAPI
source.
```json
{
"navigation": {
"openapi": {
"source": "openapi.json",
"include": ["GET /customers", "POST /customers"]
}
}
}
```
OpenAPI sources can also be used inside menu items or as individual endpoint page
items. See [API reference](/configure-with-docs-json/api-reference) for the full
OpenAPI configuration model, including how to link from MDX prose to generated
endpoint pages.
## Tags
Use tags sparingly for status, freshness, or plan labels.
```json
{
"page": "knowledge-assistant/overview",
"title": "Knowledge Assistant",
"tag": {
"text": "Pro",
"color": "#2E90FA"
}
}
```
Tags can be strings or objects with `text` and optional `color`.
## Icons
Navigation icons can use:
- Iconify names, such as `lucide:book-open`.
- HTTP or HTTPS image URLs.
- Local image paths inside the docs root.
Use `lucide` icons for most navigation. Use `simple-icons` only for recognizable
brand or product logos.
OpenAPI endpoint page items cannot have icons. Radiant shows method badges for
those pages automatically.
## Common questions
Creating an `.mdx` file is not enough to include it in the built docs site.
Add the page to `docs.json` navigation, set it as `home`, or link to it
from the navbar or footer.
Use `pages` when one sidebar is enough. Use `menu` when readers need to
switch between distinct sidebar sections. Use `tabs` when the sections
should sit above the sidebar as primary areas.
Yes. Set `title` on the page object in `docs.json` for the navigation label.
Set frontmatter `title` in the MDX file for the rendered page heading.
Yes. Link it from the navbar or footer, or set it as `home`. Those internal
links make the page routable without adding it to the main sidebar.
## Next pages
Add generated endpoints.
Add global links.
Link pages correctly.