Docz 开源项目教程

1、项目介绍

Docz 是一个用于快速创建和发布交互式文档的工具。它基于 MDX（Markdown + JSX），允许开发者轻松地编写和展示代码示例，并将其转换为生产就绪的文档站点。Docz 利用 GatsbyJS 和 Gatsby 主题阴影化技术，使得开发者可以自定义文档的外观、感觉和行为。

2、项目快速启动

安装依赖

首先，使用 Yarn 或 npm 将 Docz 添加到你的项目中：

yarn add docz # 或者使用 npm install docz

注意：react 和 react-dom 不会自动安装，你需要手动安装它们。

创建 MDX 文件

在你的项目中创建一个 .mdx 文件，例如 Button.mdx：

---
name: Button
route: /
---

import { Playground, Props } from 'docz'
import Button from './Button'

# Button

<Props of={Button} />

## 基本用法

<Playground>
  <Button type="submit">Click me</Button>
  <Button>No, click me</Button>
</Playground>

创建组件

创建一个 React 组件 Button.jsx：

import React from 'react'
import PropTypes from 'prop-types'

const Button = ({ children, type }) => (
  <button type={type}>{children}</button>
)

Button.propTypes = {
  /**
   * 这是该属性的描述
   * 按钮类型
   */
  type: PropTypes.oneOf(['button', 'submit', 'reset']),
}

Button.defaultProps = {
  type: 'button',
}

export default Button

启动开发服务器

运行以下命令启动本地开发服务器：

yarn docz dev

这将启动一个本地开发服务器，并在浏览器中打开你的文档站点。

构建文档站点

使用以下命令生成静态站点：

yarn docz build

生成的静态文件将位于 docz/dist/ 目录中。你可以使用 yarn docz serve 或任何静态文件服务器（如 npx serve docz/dist）来预览生成的站点。

3、应用案例和最佳实践

应用案例

• Welcome UI: 一个可定制的设计系统，使用 React、styled-components、styled-system 和 reakit。
• React Hooks Testing Library: 一个简单且完整的 React Hooks 测试工具，鼓励良好的测试实践。
• Mobx React: Mobx-react 文档站点。

最佳实践

• 使用 MDX: 利用 MDX 的强大功能，将 Markdown 和 JSX 结合，使文档更具交互性。
• 自定义主题: 通过 Gatsby 主题阴影化技术，自定义文档的外观和行为。
• SEO 优化: Docz 生成的文档站点是 SEO 友好的，确保你的文档在搜索引擎中表现良好。

4、典型生态项目

• GatsbyJS: 一个基于 React 的静态站点生成器，Docz 利用 GatsbyJS 来生成文档站点。
• MDX: 一个将 Markdown 和 JSX 结合的工具，使得文档编写更加灵活和强大。
• React: 一个用于构建用户界面的 JavaScript 库，Docz 基于 React 构建。
• styled-components: 一个用于样式化 React 组件的库，Docz 支持使用 styled-components 进行样式化。

通过这些模块的介绍和实践，你可以快速上手并充分利用 Docz 来创建和发布高质量的文档站点。