--- title: Format text description: Use MDX syntax to write headings, emphasis, links, quotes, and literal component names. --- 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. ```mdx ## Subtitle **Bold**, _italics_, underline, ~~strokethrough~~, `inline code`. Create a [link to another docs page](/getting-started/quickstart) or an [external link](https://mdxjs.com). > This is a blockquote. ``` ## Headers ### Page titles Set the main page title in frontmatter when you want full control over the page heading. ```mdx --- title: Format text with Markdown and MDX --- ``` Radiant Docs resolves the rendered page title in this order: 1. `title` in the page frontmatter 2. `title` on the page entry in `docs.json` 3. A title derived from the MDX file name: `format-text.mdx` -> **Format Text**. You can intentionally set different titles in frontmatter and `docs.json`. This is useful when you want a short label in the navigation and a longer, more descriptive page heading. ```json title="docs.json" { "page": "edit-markdown/format-text", "title": "Format text" } ``` ```mdx title="format-text.mdx" --- title: Format text with Markdown and MDX --- ``` In that setup, the navigation panel displays **Format text**, while the page heading is **Format text with Markdown and MDX**. ### 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`. ```mdx --- title: Deployments description: Understand deployment triggers, status, and rollout behavior. --- ``` 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. ```mdx ## Section heading Use short paragraphs under each heading. ### Subsection heading Add a subsection when the section needs one more level. ``` If you add `#` inside the page body, Radiant Docs automatically demotes it to `##` when the page renders. `#` headings are reserved for the [page title](#page-titles). ## Emphasis Use emphasis to help readers scan, not to decorate every sentence. ```mdx 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. ```mdx ***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. ```mdx [Format text](/edit-markdown/format-text) ``` For example, if the page file is `getting-started/quickstart.mdx` relative to the folder that contains `docs.json`, link to it as: ```mdx [Quickstart](/getting-started/quickstart) ``` Links can appear inline with the rest of your sentence. ```mdx Follow the [Quickstart](/getting-started/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. ```mdx [Quickstart](getting-started/quickstart) [Quickstart](./quickstart) [Quickstart](/getting-started/quickstart.html) ``` ### 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: ```mdx [List customers]() ``` 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: ```mdx [List customers]() ``` 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`: ```mdx Review request and response details. ``` 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](/configure-with-docs-json/api-reference#link-to-generated-endpoints) for the full OpenAPI link rules. ### External links Use external links for resources outside your docs site. ```mdx [MDX documentation](https://mdxjs.com) ``` Prefer link text that names the destination or action. Avoid vague phrases like `click here` or `read more`. ## Blockquotes Use blockquotes for quoted text or a short aside that should stand apart from the main paragraph flow. ```mdx > What I cannot create, I do not understand. ``` Keep blockquotes short. If the content is an instruction or warning, a component such as `` is usually clearer. ## Show JSX or HTML as text MDX treats angle brackets as JSX, so literal HTML or component names need escaping. ```mdx You can write `` with backticks (``) to display as inline code or write **{''}** 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.