Writing Better MDX for Next.js

MDX is a powerful format that blends Markdown and JSX. These tips help you write clear, maintainable posts that integrate well with a Next.js site.

1. Use concise frontmatter

Keep title, date, excerpt, and author in the frontmatter. This keeps metadata consistent and easy to consume from your site code.

2. Prefer small, reusable components

If you need special UI (callouts, notes, demos), create small React components in src/components and import them into your MDX. This keeps content focused on writing, not layout.

3. Use fenced code blocks for examples

Wrap code in fenced blocks and include the language for syntax highlighting:

npm run dev

export default function Example() {
  return <div className="p-4 rounded bg-gray-50">Example</div>;
}

4. Optimize images

Use the Next.js Image component for better performance and correct sizing.

5. Keep paragraphs short

Short paragraphs improve readability on the web — aim for 2–4 sentences per paragraph.

6. Link to related posts

Cross-link to other posts to improve discovery and provide additional context.

Final thoughts

MDX lets you combine the clarity of Markdown with the power of React. Structure your posts for readability and reuse, and your site will scale gracefully.