--- title: MDX basics description: Use Markdown and components together in the same document. --- 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. ```tsx content.mdx ## Configure your workspace Add the files your team needs, then publish the section. ### Review the output Check links, images, and metadata before publishing. ``` ```tsx callout.mdx Review links, images, and metadata before shipping a new section. ``` ### 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.