使用 GatsbyJS 为任何 React 项目生成文档

我最近一直在探索不同的设计系统文档解决方案，通过实验，我创建了一个模板，可以为任何 React 项目创建 Gatsby 文档。

将文档以文档块的形式直接写入组件中，并使用MDX添加更详细的描述和实时示例。点击此处查看演示。

如果你的代码已经有了文档，并且组件都位于指定位置src/components——那就万事俱备了！把这个项目克隆到你的代码库里，然后尽情发挥吧！ 🚀

没有这些设备？别担心！下面我会详细介绍👇

入门

使用 Netlify 安装

使用 Gatsby CLI 安装

1. gatsby new docs https://github.com/whoisryosuke/gatsby-documentation-starter/

从 GitHub 安装

1. git clone https://github.com/whoisryosuke/gatsby-documentation-starter.git
2. 请更新gatsby-config.js组件和 MDX 的位置（参见：“更改源文件夹”）
3. npm install项目内部
4. npm run develop
5. 查看文档：http://localhost:8000

创建文档

文档来源于两个地方：组件源代码和 MDX 文件。

src
└── components
    └── Button
        ├── Button.js
        └── Button.mdx

React-docgen会抓取你为 React 类/函数编写的所有 JS 文档块（Button.js），以及属性类型。这些内容会显示在你的文档页面上，属性会以表格形式组织。

在MDX文件中，您可以编写包含 JSX 示例（例如 React 组件！）的附加文档。您还可以在此处指定页面别名（页面名称和类别）。您的页面将生成为http://yoursite.com/<category>/<pageName>.

为了使组件数据显示出来，您需要一个组件的 MDX 文件，并且文档块中的页面名称和组件名称需要匹配。

如果您不想创建 MDX 文件，而是想直接从组件/JS 文件生成页面，请参阅 GitHub 文档中的“使用 react-docgen 创建页面”部分。我选择 MDX 的首要原因是其 frontmatter 的灵活性，允许您为组件创建不同的“部分”（例如，如果您有元素和排版）。

/**
 * ComponentTitle
**/
class ComponentName extends React.Component {}

---
name: ComponentTitle
menu: CategoryName
---

为位于http://localhost:8000/categoryname/componentname 的组件创建一个页面

它是如何运作的？

如果你从未坐下来真正运行过“Hello World”程序，Gatsby 可能会变得相当复杂——而当构建博客时，它会变得更加复杂。

其基本运作原理如下：

1. Gatsby 从您的项目（JS 和 MDX 文件）中提取数据
2. 数据被转换为 GraphQL 数据层。
3. 在构建过程中，Gatsby 会使用 MDX 文件为每个组件生成页面。这些页面是 React 组件，它们会查询 GraphQL 来获取组件的文档以及解析后的 MDX 文件。

如果您不熟悉 Gatsby 的工作原理，请访问其网站了解更多信息。它本质上是一个静态网站生成器，在开发过程中使用 GraphQL 从动态数据源（API、本地文件等）生成静态页面。

请慢一点

Gatsby 将数据拉取到 GraphQL 中，转换数据（例如解析 Markdown），然后基于 React 组件构建页面。

让我们逐一分析这些部分。

♻️ 数据部分

Gatsby 通过使用“source”插件将数据聚合到 GraphQL 中。本项目已配置好gatsby-source-filesystem，允许您使用项目的本地文件系统（可以获取任何文件，从 TXT 到 JS 再到 MDX）。这将创建一个包含所有导入文件的 GraphQL 端点。每个被查询的文件，或 GraphQL“节点”，都包含一个自动生成的 ID 和一个字符串化的版本文档主体。

✨ 转变部分

然后，Gatsby 使用“转换器”插件为特定数据集创建不同的 GraphQL 端点。如果您查询“源”插件导入的数据，会发现它非常简陋。转换器插件的作用正是如此，它们将数据转换为可用的格式。例如，gatsby-transformer-json它会遍历每个文件，检查它是否为 JSON 格式，然后将请求体字符串解析回对象/数组。

此模板使用了@ChristopherBiscardi开发的gatsby-mdx和Gatsby 团队开发的gatsby-transformer-react-docgen。gatsby -mdx解析所有 MDX 文件，并创建缓存的 HTML+JS 文件，这些文件将被导入到页面中。gatsby -transformer-react-docgen使用react-docgen，这是一个由 Facebook 团队创建的 CLI 工具，用于从 React 组件中提取文档。它会对您导入的任何 JS 文件运行 CLI，并为其创建 GraphQL 端点。

⚙️ 构建部分

Gatsby 在运行构建过程时，会根据我们包含在src/pages/目录中的任何 JS 文件创建页面。

在构建过程中，它还会执行我们添加的其他模块gatsby-node.js。这使我们能够执行诸如向 GraphQL 端点添加新节点或根据 GraphQL 查询创建页面之类的操作。

在这个模板中，我使用 GraphQL 查询所有 MDX 文件，并根据这些文件创建页面。这些页面由一个“模板”生成，该模板是一个能够运行 GraphQL 查询的 React 组件。由于 Gatsby 是一个框架，它为所有这些操作（查询 GraphQL、从 React 组件创建页面、将数据传递给 React 组件等）提供了 API/方法。

🎨 设计流程

为了方便复用，我希望设计和代码都尽可能轻量级。文档采用两栏布局，带有一个标题栏，侧边栏在移动设备上会隐藏（标题栏中会出现一个“切换侧边栏”按钮）。那个炫酷的移动端动画按钮来自 Codepen，作者是@ainalem。

如果我不喜欢 Gatsby/JS/React 等工具怎么办？

如果您正在寻找其他解决方案，市面上有很多文档资料可供选择：

• Docz
• react-styleguidist
• 恐龙纪录片
• Vuepress
• Gitbook
• 文档化

还有更多选择！不要局限于某一种特定的组合或配置。找到一种适合你工作流程的组合。

务必记录一切！

我非常欣赏那些能够将你辛辛苦苦编写的文档块和属性类型，只需点击一下按钮，就能将你的代码库转换为一个功能齐全、设计精良的文档网站的工具。

我设计这个组件时主要考虑的是设计系统，但它实际上也适用于任何使用 React 组件的项目 🙌

我一直致力于为其他开发者和设计师提供能够提升工作流程的工具。如果这篇文章对你的文档编写有所帮助，请在评论区留言或发推文告诉我👍

在 GitHub 上克隆项目|查看演示网站

干杯🍻
Ryo

参考：

• gatsby-documentation-starter
• 演示网站
• GatsbyJS
• gatsby-mdx
• gatsby-transformer-react-docgen
• gatsby-transformer-remark
• 风格指南
• 移动按钮 CSS