字
字节笔记本
2026年2月22日
Docz - 基于 MDX 的 React 文档生成工具
Docz 是一个基于 React 和 MDX 的文档生成工具，让你可以用最优雅的方式编写和发布交互式文档。它支持零配置启动，通过简单的 MDX 文件即可生成专业的文档站点，已被广泛应用于组件库和设计系统的文档建设。
项目简介
Docz 由 Pedro Nauck 创建，是一个开源的文档生成框架。它结合了 Gatsby 的强大构建能力和 MDX 的灵活性，让开发者可以用 Markdown 编写文档，同时嵌入 React 组件进行实时演示。该项目在 GitHub 上已获得 23.6k+ stars，拥有 129 位贡献者。
核心特性
- 零配置启动：无需复杂配置，安装即可使用
- MDX 支持：在 Markdown 中直接编写 JSX，实现文档与代码的完美结合
- 实时重载：开发模式下自动刷新，提升编写效率
- Props 自动生成：自动解析组件 PropTypes 或 TypeScript 类型定义生成属性表格
- Playground 组件：内置交互式代码演示环境
- 主题定制：支持自定义主题和样式
- TypeScript 原生支持：完美支持 TS 项目
技术栈
- React - UI 渲染核心
- Gatsby - 静态站点生成器
- MDX - Markdown + JSX 混合语法
- TypeScript - 类型支持
安装指南
前置要求
- Node.js >= 14
- React >= 16.8
安装步骤
bash
# 使用 yarn
yarn add docz react react-dom
# 或使用 npm
npm install docz react react-dom快速开始
1. 创建 MDX 文档文件
创建一个 Button.mdx 文件：
mdx
---
name: Button
route: /
---
import { Playground, Props } from 'docz'
import Button from './Button'
# Button
<Props of={Button} />
## 基本用法
<Playground>
<Button type="submit">点击我</Button>
<Button>不，点我</Button>
</Playground>2. 创建组件文件
创建 Button.jsx：
jsx
import React from 'react'
import t from 'prop-types'
const Button = ({ children, type }) => (
<button type={type}>{children}</button>
)
Button.propTypes = {
/** 按钮类型 */
type: t.oneOf(['button', 'submit', 'reset']),
}
Button.defaultProps = {
type: 'button',
}
export default Button3. 启动开发服务器
bash
yarn docz dev这将启动本地开发服务器并在浏览器中打开文档站点。
使用示例
场景 1：组件文档
mdx
---
name: Card
menu: Components
---
import { Playground } from 'docz'
import Card from './Card'
# Card 组件
卡片容器组件，用于展示内容块。
<Playground>
<Card title="卡片标题">
这是卡片内容区域
</Card>
</Playground>场景 2：API 文档
mdx
---
name: API Reference
route: /api
---
import { Props } from 'docz'
import MyComponent from './MyComponent'
# API 文档
## MyComponent
<Props of={MyComponent} />构建与部署
构建生产版本
bash
yarn docz build构建输出位于 .docz/dist 目录。
部署到 GitHub Pages
bash
yarn docz build --base=/your-repo-name/项目状态
注意：Docz 项目已于 2025 年 11 月 21 日被归档，目前处于只读状态。虽然项目不再积极维护，但对于现有项目仍然可用。新项目可以考虑使用以下替代方案：
- Docusaurus - Facebook 出品的文档站点生成器
- Storybook - 组件开发和文档平台
- VitePress - 基于 Vite 的静态站点生成器
- Nextra - 基于 Next.js 的文档框架
项目链接
分享: