Skip to main content

MDX Basics

This page shows examples of the simplest high-value additions MDX gives us over plain Markdown. These are useful when we want content to stay author-friendly while still allowing richer presentation.

Why this matters

These patterns are valuable because they stay close to writer-friendly Markdown while allowing cleaner layouts and more purposeful interaction.

Collapsible Content​

Click to expand a quick explanation

Collapsible sections are useful for optional guidance, troubleshooting notes, release-specific caveats, or long explanatory sidebars that should not dominate the page by default.

Tabs​

Writers can keep one page and present multiple variants without duplicating the whole topic.

Admonitions​

Example note
Use notes for low-risk contextual guidance.
Example warning

Use warnings when a user could make a mistake or misunderstand a process.

Example critical warning

Use danger callouts only when the consequence is meaningful enough to justify the visual weight.

Code and Inline Markup​

You can mix prose with technical notation such as component props, API names, routes, or commands. This is useful when a help topic needs to refer to exact UI labels, component names, or implementation examples without losing readability.

<ShowcaseVideo
  title="Prototype Video Embed"
  description="Reusable media block inside an MDX page."
  src="https://example.com/video.mp4"
/>

Where this helps most​

  • FAQ-heavy pages
  • role-based instructions
  • browser vs mobile variations
  • admin vs end-user differences
  • optional advanced guidance