---
title: Content model
description: Understand how docs.json, MDX pages, and assets work together.
---
Radiant Docs sites are built from a small set of files: one `docs.json`
configuration file, MDX pages, and any assets those files reference.
Use this page to understand where content lives and how Radiant turns source
files into a navigable docs site.
## Docs root
Your docs root is the folder that contains `docs.json`.
In a dedicated docs repository, the docs root is often the repository root. In a
monorepo, it may be a subfolder such as `docs` or `documentation`.
Page paths in Radiant docs configuration are relative to the docs root. Internal
links and asset references also point from the docs root, but start with `/`.
```txt
docs.json
getting-started/
quickstart.mdx
workflows.mdx
images/
logo.png
```
In this example, the page path is `getting-started/quickstart`. Do not include
parent folders above the docs root.
## `docs.json`
`docs.json` controls site-wide structure and presentation. It defines the site
title, navigation, home page, logo, theme, navbar, footer, assistant settings,
and API reference sources.
A minimal docs site needs a `title` and one navigation mode:
```json
{
"title": "Acme Docs",
"navigation": {
"pages": [
{
"page": "getting-started/quickstart",
"title": "Quickstart"
}
]
}
}
```
Page paths in `docs.json` are docs-root-relative. Do not start them with `/`,
and do not include the `.mdx` extension.
## MDX pages
Write documentation pages as `.mdx` files. MDX lets you use standard Markdown
for headings, paragraphs, lists, tables, links, images, and code blocks. You can
also use Radiant components when a page needs richer structure.
Most pages include frontmatter:
```mdx
---
title: Quickstart
description: Make your first documentation change.
---
Use this quickstart to make your first docs change.
```
The `title` controls the page heading. The `description` is used as page
metadata and helps summarize the page in generated surfaces.
## Routable pages
Creating an `.mdx` file is not always enough to make it reachable by readers.
Radiant includes a page in the built site when it is referenced by `docs.json`.
A page is routable when it is:
- Listed in `navigation`
- Set as `home`
- Linked from the `navbar`
- Linked from the `footer`
Pages listed in `navigation` appear in the main docs navigation. Pages linked
from the navbar or footer can be available without appearing in the main
navigation.
When you add a new page, add the `.mdx` file and the matching `docs.json`
reference in the same change.
## Source paths and rendered URLs
Radiant separates source paths from rendered URLs.
Use source paths when you configure or link docs content:
```mdx
[Quickstart](/getting-started/quickstart)
```
Rendered browser URLs may be different because Radiant builds routes from the
site navigation. Do not use generated browser URLs as internal link targets in
MDX.
## Assets
Place images, videos, downloads, and OpenAPI files inside the docs root so
Radiant can publish or read them.
For local assets in MDX, use a docs-root absolute path:
```mdx
```
For controlled image rendering with captions, dark mode images, or zoom
behavior, use the `Image` component.
## Next steps
Publish your first docs change.
Choose how your team edits docs.
Learn what site config controls.
Add media that helps readers.