MDX components

Use shared components to make docs content richer without losing readability.

Shared MDX components let writers add structured blocks without repeating markup.

Callout example

This example shows the smallest useful callout pattern for MDX content.

<Callout title="Before publishing">
Check links, metadata, images, and headings before shipping.
</Callout>

When to use callouts

Use callouts for warnings, important context, and review notes. Do not use them to decorate ordinary paragraphs.

Component guidelines

Use these guidelines to decide whether a repeated content pattern deserves a component.

  • Components should solve recurring content needs.
  • Keep names simple and memorable.
  • Do not use components for ordinary paragraphs.
  • Make sure the content still reads clearly in source form.

Source readability

A content file should still make sense to a writer who does not know the component implementation.

Component examples

Examples should show the component in a realistic publishing context. A component that looks useful in isolation can still be confusing when placed between paragraphs, tables, and code blocks.

Short content blocks

Use compact components for small repeated patterns such as install commands, callouts, image captions, and copyable snippets. These patterns should not dominate the page.

Rich content blocks

Use larger components when the page needs structured comparison, multi-file examples, previews, or interactive states. These should be rare enough that the document still feels readable.

Maintenance notes

Shared MDX components become part of the writing system. Document their intended use so contributors do not invent competing patterns.

Naming consistency

Prefer names that describe the content purpose. A writer should understand when to use Callout, CodeTabs, or InstallCommand without reading implementation code.