MDX basics

MDX lets you write Markdown with interactive or styled components when you need them. Use Markdown for normal prose and components for repeatable content patterns.

Markdown content#

Use Markdown for headings, paragraphs, lists, links, and code examples.

## Configure your workspace

Add the files your team needs, then publish the section.

### Review the output

Check links, images, and metadata before publishing.

Keep source readable#

The MDX file should still be understandable when opened in an editor. If a page is mostly custom components, it becomes harder for writers to maintain.

Components#

Use components for content that needs a reusable treatment.

Component rule#

Most docs should stay readable as plain Markdown. Components should clarify content, not decorate it.

Mixing formats#

A strong MDX page usually combines prose, lists, code, and one or two components. Too much of any single format makes the page harder to scan.

Prose first#

Introduce the idea in normal prose before showing a component. This keeps the MDX source understandable for writers who are editing quickly.

Component second#

Use a component after the reader understands why it exists. Components should support the explanation, not replace it.

Source review#

Open the MDX file as plain text before publishing. If the source is hard to follow, future edits will be slower and riskier.

Keep examples short#

Use short examples for concepts and longer examples only when readers need to copy a complete pattern.