Using MDX Without Losing the Simplicity of Markdown

MDX is powerful because it lets documentation use components. That power can become a problem when every page turns into a custom JSX file.

The goal is not to make writers think like component authors. The goal is to give them a few useful building blocks while keeping the writing experience simple.

Default to Markdown#

Most documentation should still be normal Markdown:

• Paragraphs.
• Lists.
• Tables.
• Code blocks.
• Links.
• Images.

These elements are portable, easy to review, and familiar to most contributors.

Use components for meaning#

Reach for components when they express a content pattern.

<Callout title="Migration note">
Move flat docs pages into folder indexes before adding children.
</Callout>

This is better than using a component only to change spacing or color.

Keep the component set small#

A strong MDX system usually needs fewer components than expected. Start with callouts, tabs, cards, and structured examples. Add more only when repeated content patterns appear.

Protect the reading flow#

Components should improve comprehension. If a component interrupts the article or makes the source harder to read, it should earn its place.