MDX: Complete Tutorial for Markdown+React Components in Next.js

Code Comparison: Hard Coding vs MDX

export const metadata = {
  title: "Article Title",
  description: "Article Description",
};

import BlogLayout from '@/components/BlogLayout';
import FAQ from '@/components/FAQ';
import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui/card';
import { Button } from '@/components/ui/button';
import { Badge } from '@/components/ui/badge';
import { addUtmToExternalLink, getExternalLinkRel } from "@/lib/utils";

<BlogLayout {...props}>
  {/ Using FAQ component /}
  <FAQ items={[...]} pageUrl="..." />

  {/ Using Card component /}
  <Card>
    <CardHeader>
      <CardTitle>Title</CardTitle>
    </CardHeader>
    <CardContent>
      Content
    </CardContent>
  </Card>

  {/ Using Button and Badge /}
  <Button>Click Button</Button>
  <Badge>Label</Badge>
</BlogLayout>

Fundamentals

What is Markdown?

Markdown is a lightweight markup language created by John Gruber and Aaron Swartz in 2004. Its design goal is to enable people to write documents in an easy-to-read and easy-to-write plain text format, then convert it into valid HTML. Markdown uses simple symbols (such as # for headings, ** for bold) to mark text formatting without complex HTML tags.

Markdown syntax is concise and intuitive with a low learning curve. For example, using ## Heading creates a level 2 heading, and using - List item creates an unordered list. This simplicity makes Markdown the preferred format for writing documentation, blogs, README files, etc.

Markdown files typically use .md or .markdown as extensions and can be parsed and rendered by various tools and platforms, including GitHub, GitLab, Reddit, Stack Overflow, etc.

What is MDX?

MDX (Markdown + JSX) is an extension of Markdown that allows you to use JSX (JavaScript XML) syntax directly in Markdown documents, meaning you can embed React components. MDX is developed by the [MDX official team](https://mdxjs.com/), aiming to combine the simplicity of Markdown with the power of React.

In MDX, you can write content just like regular Markdown while inserting React components anywhere. For example, you can embed an interactive chart component in a Markdown paragraph or use custom card components in lists. This capability makes MDX particularly suitable for creating content-rich technical documentation, blog articles, and marketing pages.

MDX files use .mdx as the extension and are supported by modern frontend frameworks like Next.js, Gatsby, and Vite. During compilation, MDX converts Markdown syntax to HTML and JSX to React components, ultimately generating interactive web content.

Why Use Markdown/MDX?

Compared to traditional HTML writing or CMS systems, Markdown and MDX have the following advantages:

• Concise and Readable: Markdown syntax is intuitive and clear, even non-technical people can quickly get started. Code volume is reduced by approximately 60-70% compared to HTML, focusing on content itself rather than formatting markup.
• Version Control Friendly: Markdown files are plain text format, making it easy to use Git for version control, track content change history, and facilitate collaborative editing and code reviews.
• Cross-platform Compatible: Markdown files can be opened and edited in any text editor, not dependent on specific software or platforms. At the same time, most modern development tools and platforms natively support Markdown.
• Unified Styles: Through global component mapping (such as mdx-components.tsx), you can uniformly manage styles for all articles, ensuring visual consistency while reducing maintenance costs.
• Component Reusability: MDX allows embedding React components, enabling creation of reusable content components (such as FAQ, code examples, interactive charts, etc.), improving content creation efficiency.
• Performance Optimization: MDX files are compiled to static HTML at build time, enjoying the performance advantages of Static Site Generation (SSG), fast loading speeds, and SEO-friendly.
• Developer Experience: When writing content with Markdown, developers can focus on content creation without dealing with complex HTML tags and CSS styles. At the same time, MDX provides type safety and code hints, improving development efficiency.

In the Alignify project, we use MDX to write new articles, preserving both the simplicity of Markdown and the flexibility of React components. This approach is particularly suitable for scenarios requiring frequent content updates, unified styles, and embedded interactive components.

MDX Content Writing

The core advantage of MDX is that it supports both Markdown syntax and React components simultaneously, allowing you to write content with concise Markdown while embedding powerful React components. According to the [MDX official documentation](https://mdxjs.com/docs/using-mdx/#components), MDX compiles Markdown syntax to JavaScript and converts HTML elements to custom React components through component mapping mechanisms.

Markdown Syntax Usage

MDX supports full Markdown syntax while allowing React component embedding. Below introduces common Markdown syntax and its style performance in the Alignify project.

Format Syntax

MDX supports complete Markdown format syntax, including headings, lists, tables, code, text formatting, blockquotes, and horizontal rules. These syntax elements automatically apply unified styles through component mapping in mdx-components.tsx, without needing to manually add className.

Supported Format Syntax Types:

• Headings: Use # to ###### to represent different heading levels, h2 and h3 are automatically added to the table of contents navigation
• Lists: Unordered lists use -, , or +, ordered lists use numbers with periods
• Tables: Use pipe | to separate columns, header rows need to add className="header-row"
• Code: Inline code uses single backticks, code blocks use triple backticks, can specify language for syntax highlighting
• Text Formatting: Use bold, italic, ~~strikethrough~~, etc.
• Blockquotes: Use > to represent quoted content
• Horizontal Rules: Use three or more ---, , or ___

Syntax Examples

Below shows the actual effects of various format syntax:

Headings: Use different heading levels to organize content, h2 and h3 headings are automatically added to the table of contents navigation.

Lists: Lists automatically apply unified styles with appropriate spacing and indentation.

Unordered list example:

• First item
• Second item
• Third item

Ordered list example:

1. First step
2. Second step
3. Third step

Table Example: Tables automatically apply border styles and responsive layout. Header rows need to add className="header-row" to apply background color.

Code: Use backticks to wrap inline code, use triple backticks to wrap code blocks. Can specify language (such as ```javascript) for syntax highlighting.

Inline code example: Use export const metadata to export metadata.

Code block example:

Text Formatting Example: Use bold to achieve bold text, use italic to achieve italic text, use ~~strikethrough~~ to achieve strikethrough text.

Blockquote Example: Blockquotes have a primary color border on the left, used to highlight important content.

This is a blockquote, typically used to quote others' viewpoints or important information. Blockquotes can help highlight important content and improve reading experience.

Horizontal Rule Example: Used to separate different sections.

Links and Media

Below shows the actual effects of links and media:

Link Usage Best Practices: In MDX files, strongly recommend using Markdown link syntax[text](URL) instead of JSX <a> tags. Markdown links automatically go through component mapping processing, ensuring external links automatically add UTM parameters, open in new tabs, and correctly handle internal/external links. If you must use JSX, use the exported <A> component (uppercase) instead of <a>.

Internal Link Example: Internal links use Next.js Link component, supporting client-side routing.

How to Build a Blog from 0-1

External Link Example: External links automatically add UTM parameters and open in a new tab.

[Next.js Official Website](https://nextjs.org)

Image Example: In MDX files, you can insert images using Markdown syntax or JSX syntax. Markdown syntax automatically applies styles and enables lazy loading. JSX syntax can override or extend default styles through className property.

YouTube Video Example: Simply add a YouTube link to automatically render as a video thumbnail. Supports youtube.com and youtu.be formats, link text automatically displays as video title, automatically adds UTM parameters, opens in a new tab.