简易建构组件库文档网站：Markdown+React.lazy成搭档

2024-02-10 23:19:22

Markdown 的魅力无穷，它以简洁的语法、易于阅读的排版，成为技术文档撰写的首选工具。然而，当需要构建一个完整的组件库文档网站时，纯 Markdown 显得力不从心。为了满足这个需求，我们需要更加强大的技术组合。

本指南将使用 unified、react-markdown、React.lazy 等技术，为你搭建一个 React 组件库文档网站，让你能够像写 markdown 一样轻松创建组件库文档。准备好开启这段技术之旅了吗？

1. 前期准备

首先，你需要安装一些必要的工具：

Node.js
npm 或 yarn
create-react-app

然后，新建一个 React 项目：

npx create-react-app my-component-library-docs

进入项目目录：

cd my-component-library-docs

2. 安装所需依赖项

接下来，你需要安装必要的依赖项：

npm install unified remark-parse remark-rehype rehype-raw rehype-react react-markdown react-lazyload

3. 搭建文档网站骨架

创建一个 src/components/DocPage.js 文件，作为文档页面的骨架：

import React, { useState, lazy } from "react";
import remark from "remark";
import unified from "unified";
import parse from "remark-parse";
import rehype from "rehype";
import raw from "rehype-raw";
import react from "rehype-react";
import Markdown from "react-markdown";
import { Suspense } from "react";

const DocPage = ({ markdown }) => {
  const [html, setHtml] = useState("");

  unified()
    .use(parse)
    .use(rehype)
    .use(raw)
    .use(react, { createElement: React.createElement })
    .process(markdown, (err, file) => {
      if (err) {
        console.error(err);
        return;
      }
      setHtml(file.toString());
    });

  return (
    <Suspense fallback={<div>Loading...</div>}>
      <Markdown source={html} />
    </Suspense>
  );
};

export default DocPage;

然后，创建一个 src/pages/Home.js 文件，作为网站的首页：

import React from "react";
import DocPage from "../components/DocPage";

const Home = () => {
  const markdown = `
    # 组件库文档网站

    欢迎来到组件库文档网站！

    在本网站中，您将找到有关组件库的所有信息，包括组件库的使用方法、组件库的安装方法等。

    ## 开始使用

    要开始使用组件库，您需要先安装它。

    ```
    npm install my-component-library
    ```

    安装完成后，您就可以在您的项目中使用组件库了。

    ```javascript
    import { ComponentA } from "my-component-library";

    const App = () => {
      return <ComponentA />;
    };
    ```

    ## 组件库的使用方法

    组件库的使用方法非常简单。您只需在您的项目中导入组件，然后在您的代码中使用它们即可。

    例如，要使用 ComponentA，您只需在您的项目中导入它：

    ```javascript
    import { ComponentA } from "my-component-library";
    ```

    然后，您就可以在您的代码中使用它了：

    ```javascript
    const App = () => {
      return <ComponentA />;
    };
    ```

    ## 组件库的安装方法

    组件库的安装方法也非常简单。您只需在您的项目中运行以下命令：

    ```
    npm install my-component-library
    ```

    安装完成后，您就可以在您的项目中使用组件库了。
  `;

  return <DocPage markdown={markdown} />;
};

export default Home;

最后，在 src/App.js 文件中，将 Home 组件作为应用程序的根组件：

import React from "react";
import Home from "./pages/Home";

const App = () => {
  return <Home />;
};

export default App;

4. 运行项目

现在，你可以运行项目了：

npm start

然后，在浏览器中打开 http://localhost:3000，你将看到组件库文档网站的首页。

5. 编写组件库文档

你可以通过编辑 src/pages/Home.js 文件中的 markdown 文本来编写组件库文档。

例如，要添加一个关于组件库使用说明的章节，你可以添加以下 markdown 文本：

## 组件库的使用说明

组件库的使用说明如下：

- 导入组件库：在您的项目中导入组件库。

```javascript
import { ComponentA } from "my-component-library";

使用组件：在您的代码中使用组件。

const App = () => {
  return <ComponentA />;
};


### 6. 部署网站

当你的组件库文档网站完成后，你可以将其部署到生产环境。

你可以使用 Netlify 来部署你的网站。

首先，你需要创建一个 Netlify 账户。

然后，你需要将你的项目推送到 GitHub。

最后，你需要在 Netlify 上连接你的 GitHub 仓库。

Netlify 会自动构建你的项目并将其部署到生产环境。

**就这样，你已经成功地构建了一个 React 组件库文档网站，让你能够像写 markdown 一样轻松创建组件库文档。现在，你可以开始撰写你的组件库文档，并将其发布到网站上了。希望这篇指南能够帮助你快速上手。**