Write most pages in plain Markdown first. Because Radiant Docs uses MDX, you can keep standard Markdown syntax for text and only reach for components when you need richer UI.
Subtitle
Bold, italics, underline, strokethrough, inline code.
Create a link to another docs page or an external link.
This is a blockquote.
Headers
Page titles
Set the main page title in frontmatter when you want full control over the page heading.
Radiant Docs resolves the rendered page title in this order:
titlein the page frontmattertitleon the page entry indocs.json- A title derived from the MDX file name:
format-text.mdx-> Format Text.
Page descriptions
Add a description in frontmatter when a page needs a specific summary.
Radiant uses it for HTML metadata and AI-readable docs files such as
/llms.txt.
If you omit description, Radiant generates a fallback description from the
page title and docs site title.
Section headings and subheadings
For headings inside the page body, start with ##. Use ### for subsections.
Emphasis
Use emphasis to help readers scan, not to decorate every sentence.
Use bold for strong emphasis.
Use italics for light emphasis.
Use underlined text when you need underline.
Use strikethrough for removed or outdated text.
Use inline code for commands, file names, and identifiers.
Combine emphasis styles
You can combine emphasis styles too.
Bold italics
underlined italics
underlined bold
strikethrough bold
Links
Use standard Markdown links for both internal and external destinations.
Internal links
Use internal links for pages that are part of your docs site navigation,
included by the navbar or footer, or set as home.
For hand-authored MDX pages, use the source path from the docs root, the folder
that contains docs.json. Start the path with / and omit the .mdx
extension unless you need to be explicit.
For example, if the page file is getting-started/quickstart.mdx relative to
the folder that contains docs.json, link to it as:
Links can appear inline with the rest of your sentence.
Follow the Quickstart to publish your first docs change.
Do not use generated browser URLs for internal links. Radiant rewrites source
paths to the correct published URLs when the site builds. Links to MDX files
that exist but are not included in docs.json fail validation.
OpenAPI endpoint links
Use endpoint links to point from MDX prose or component href props to
generated OpenAPI endpoint pages. The endpoint must be rendered by docs.json
navigation, either through an OpenAPI section or an individual OpenAPI page
item.
Use the shorthand form when one rendered OpenAPI source contains the endpoint:
The angle brackets are Markdown syntax for link destinations that contain spaces. They are not part of the rendered URL.
If multiple rendered OpenAPI sources contain the same method and path, add the OpenAPI source before the endpoint:
Use the same source string that appears in docs.json. If the source is a
remote URL, use that URL before #GET /path.
The same target works in components that accept href:
Radiant validates endpoint links against generated pages. If an endpoint is
excluded by exclude, omitted from include, or present only in an OpenAPI
source that is not part of navigation, validation fails. See API
reference
for the full OpenAPI link rules.
External links
Use external links for resources outside your docs site.
Blockquotes
Use blockquotes for quoted text or a short aside that should stand apart from the main paragraph flow.
What I cannot create, I do not understand.
Keep blockquotes short. If the content is an instruction or warning, a component such as <Callout /> is usually clearer.
Show JSX or HTML as text
MDX treats angle brackets as JSX, so literal HTML or component names need escaping.
You can write <Component title="Example"> with backticks (``) to display
as inline code or write <Component title="Example" /> with
{curly brackets} + "quotation marks" to display as regular text.
Use this whenever you are writing about a component or html instead of rendering it.