Content model

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

docs.jsongetting-started/  quickstart.mdx  workflows.mdximages/  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:

{  "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:

---title: Quickstartdescription: 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.

Source paths and rendered URLs

Radiant separates source paths from rendered URLs.

Use source paths when you configure or link docs content:

[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:

![Product dashboard](/images/dashboard.png)

For controlled image rendering with captions, dark mode images, or zoom behavior, use the Image component.

Next steps