【Dify 前端源码解读系列】MDX 让 API 文档焕发生机

什么是 MDX？

MDX 是一种强大的文档格式，它允许在 Markdown 内容中使用 JSX。这意味着你可以在 Markdown 的简洁语法中嵌入交互式组件，使文档不再局限于静态内容。MDX 完美地将 Markdown 的简单与 JSX 的灵活性结合在一起，特别适合需要丰富交互体验的文档场景。

MDX 的优势：

• 组件化 - 在 Markdown 中使用现有组件，甚至将其他 MDX 文件作为组件导入
• 可定制 - 可以为每个 Markdown 元素指定渲染的组件 ({h1: MyHeading})
• 基于 Markdown - 保留了 Markdown 的简洁性，只在需要时使用 JSX
• 高性能 - MDX 没有运行时，所有编译都在构建阶段完成

Dify 如何使用 MDX 构建 API 文档

通过分析 Dify 的代码库，我们发现 Dify 巧妙地使用 MDX 来构建其 API 文档系统。在app/components/develop/template/template_chat.zh.mdx文件中，我们可以看到 Dify 的 MDX 实现方式。

MDX 组件引入

import { CodeGroup } from "../code.tsx";
import {
  Row,
  Col,
  Properties,
  Property,
  Heading,
  SubProperty,
} from "../md.tsx";

Dify 定义了一系列自定义组件，专门用于构建 API 文档。这些组件包括：

• CodeGroup - 用于展示代码示例，支持多语言切换
• Row/Col - 用于布局，创建响应式的文档结构
• Properties/Property/SubProperty - 用于展示 API 参数和属性的详细信息
• Heading - 用于创建 API 端点的标题，包含方法、URL 等信息

文档结构示例

让我们来看一个 Dify API 文档的结构示例