MDX使用：Next.js中Markdown+React组件完整教程

代码对比：Hard Coding vs MDX

export const metadata = {
  title: “文章标题“,
  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}>
  {/ 使用 FAQ 组件 /}
  <FAQ items={[...]} pageUrl="..." />

  {/ 使用 Card 组件 /}
  <Card>
    <CardHeader>
      <CardTitle>标题</CardTitle>
    </CardHeader>
    <CardContent>
      内容
    </CardContent>
  </Card>

  {/ 使用 Button 和 Badge /}
  <Button>点击按钮</Button>
  <Badge>标签</Badge>
</BlogLayout>

基础概念

什么是 Markdown？

Markdown 是一种轻量级标记语言，由 John Gruber 和 Aaron Swartz 在 2004 年创建。它的设计目标是让人们能够使用易读易写的纯文本格式编写文档，然后转换成有效的 HTML。Markdown 使用简单的符号（如 # 表示标题、** 表示加粗）来标记文本格式，无需复杂的 HTML 标签。

Markdown 的语法简洁直观，学习成本低。例如，使用 ## 标题 就能创建一个二级标题，使用 - 列表项 就能创建一个无序列表。这种简洁性使得 Markdown 成为编写文档、博客、README 文件等的首选格式。

Markdown 文件通常以 .md 或 .markdown 为扩展名，可以被各种工具和平台解析和渲染，包括 GitHub、GitLab、Reddit、Stack Overflow 等。

什么是 MDX？

MDX（Markdown + JSX）是 Markdown 的扩展，允许你在 Markdown 文档中直接使用 JSX（JavaScript XML）语法，即可以嵌入 React 组件。MDX 由 [MDX 官方团队](https://mdxjs.com/) 开发，旨在将 Markdown 的简洁性与 React 的强大功能结合起来。

在 MDX 中，你可以像编写普通 Markdown 一样编写内容，同时可以在任何位置插入 React 组件。例如，你可以在 Markdown 段落中嵌入一个交互式的图表组件，或者在列表中使用自定义的卡片组件。这种能力使得 MDX 特别适合创建内容丰富的技术文档、博客文章和营销页面。

MDX 文件以 .mdx 为扩展名，可以被 Next.js、Gatsby、Vite 等现代前端框架支持。在编译时，MDX 会将 Markdown 语法转换为 HTML，将 JSX 转换为 React 组件，最终生成可交互的网页内容。

为什么要使用 Markdown/MDX？

相比传统的 HTML 编写方式或 CMS 系统，Markdown 和 MDX 具有以下优势:

• 简洁易读:Markdown 语法直观明了，即使是非技术人员也能快速上手。代码量相比 HTML 减少约 60-70%，专注于内容本身而非格式标记。
• 版本控制友好:Markdown 文件是纯文本格式，可以轻松使用 Git 进行版本控制，追踪内容变更历史，协作编辑和代码审查都更加方便。
• 跨平台兼容:Markdown 文件可以在任何文本编辑器中打开和编辑，不依赖特定的软件或平台。同时，大多数现代开发工具和平台都原生支持 Markdown。
• 样式统一:通过全局组件映射（如 mdx-components.tsx），可以统一管理所有文章的样式，确保视觉一致性，同时降低维护成本。
• 组件复用:MDX 允许嵌入 React 组件，可以创建可复用的内容组件（如 FAQ、代码示例、交互式图表等），提高内容创作效率。
• 性能优化:MDX 文件在构建时被编译为静态 HTML，可以享受静态站点生成（SSG）的性能优势，加载速度快，SEO 友好。
• 开发体验:使用 Markdown 编写内容时，开发者可以专注于内容创作，而不需要处理复杂的 HTML 标签和 CSS 样式。同时，MDX 提供了类型安全和代码提示，提升开发效率。

在 Alignify 项目中，我们使用 MDX 来编写新文章，既保留了 Markdown 的简洁性，又获得了 React 组件的灵活性。这种方式特别适合需要频繁更新内容、需要统一风格、需要嵌入交互式组件的场景。

MDX 内容编写

MDX 的核心优势在于它同时支持 Markdown 语法和 React 组件，让你可以用简洁的 Markdown 编写内容，同时嵌入强大的 React 组件。根据 [MDX 官方文档](https://mdxjs.com/docs/using-mdx/#components)，MDX 会将 Markdown 语法编译为 JavaScript，并通过组件映射机制将 HTML 元素转换为自定义 React 组件。

Markdown 语法使用

MDX 支持完整的 Markdown 语法，同时允许嵌入 React 组件。下面介绍常用的 Markdown 语法及其在 Alignify 项目中的样式表现。

格式语法

MDX 支持完整的 Markdown 格式语法，包括标题、列表、表格、代码、文本格式、引用块和分割线等。这些语法元素通过 mdx-components.tsx 中的组件映射自动应用统一的样式，无需手动添加 className。

支持的格式语法类型:

• 标题:使用 # 到 ###### 表示不同级别的标题，h2 和 h3 会自动添加到目录导航中
• 列表:无序列表使用 -、 或 +，有序列表使用数字加句点
• 表格:使用管道符 | 分隔列，表头行需要添加 className="header-row"
• 代码:行内代码使用单个反引号，代码块使用三个反引号，可指定语言进行语法高亮
• 文本格式:使用 加粗、斜体、~~删除线~~ 等
• 引用块:使用 > 表示引用内容
• 分割线:使用三个或更多 ---、 或 ___

语法示例

下面展示各种格式语法的实际效果:

标题:使用不同级别的标题来组织内容，h2 和 h3 标题会自动添加到目录导航中。

列表:列表自动应用统一的样式，并带有适当的间距和缩进。

无序列表示例:

• 第一项
• 第二项
• 第三项

有序列表示例:

1. 第一步
2. 第二步
3. 第三步

表格示例:表格自动应用边框样式和响应式布局。表头行需要添加 className="header-row" 来应用背景色。

代码:使用反引号包裹行内代码，使用三个反引号包裹代码块。可以指定语言（如 ```javascript）进行语法高亮。

行内代码示例：使用export const metadata导出元数据。

代码块示例：

文本格式示例：使用 加粗 实现加粗文本，使用 斜体 实现斜体文本，使用 ~~删除线~~ 实现删除线文本。

引用块示例：引用块左侧有主色调边框，用于突出显示重要内容。

这是一段引用内容，通常用于引用他人的观点或重要信息。引用块可以帮助突出显示重要的内容，提升阅读体验。

水平分割线：用于分隔不同章节。

链接和媒体

下面展示链接和媒体的实际效果：

链接使用最佳实践：在 MDX 文件中，强烈推荐使用 Markdown 链接语法[文本](URL)，而不是 JSX 的 <a> 标签。Markdown 链接会自动经过组件映射处理，确保外部链接自动添加 UTM 参数、在新标签页打开，并正确处理内部/外部链接。如果必须使用 JSX，请使用导出的 <A> 组件（大写）而不是 <a>。

内部链接示例：内部链接使用 Next.js Link 组件，支持客户端路由。

如何从0-1搭建博客

外部链接示例：外部链接自动添加 UTM 参数，在新标签页打开。

[Next.js官网](https://nextjs.org)

图片示例：在 MDX 文件中，可以使用 Markdown 语法或 JSX 语法插入图片。Markdown 语法会自动应用样式并启用懒加载。JSX 语法可以通过 className 属性覆盖或扩展默认样式。

YouTube 视频示例：只需添加 YouTube 链接即可自动渲染为视频缩略图。支持 youtube.com 和 youtu.be 格式，链接文本会自动作为视频标题显示，自动添加 UTM 参数，在新标签页打开。