探索Docusaurus：源自Facebook的高效静态文档站点构建利器

在开源世界中，优秀的文档是项目成功的重要基石。当谈到快速、优雅地搭建文档站点，Docusaurus 这个名字无疑会出现在许多开发者的首选列表中。今天，我们就来简单了解一下这个出自 Facebook 的静态站点生成器，看看它能为我们的文档工作带来哪些便利。

出身名门，实力不凡

Docusaurus，这位文档界的“明星”，诞生于科技巨头 Facebook 的开源项目之中。这意味着它不仅享有大厂背书的稳定性与专业性，还拥有活跃的社区支持和持续的迭代更新。选择 Docusaurus，就是选择了一个成熟且有保障的技术伙伴。

核心价值：让文档写作回归本质

简化流程，聚焦内容

Docusaurus 的核心使命是让文档编写变得轻松愉快。它提供了开箱即用的模板和工具链，只需几步简单的配置，就能将 Markdown 格式的文档转换为功能齐全、设计精良的静态网页。这意味着你不再需要为前端构建烦恼，可以全身心投入到知识的梳理与传达中。

功能丰富，满足多样需求

内置的版本控制、多语言支持、搜索功能（如集成 Algolia）以及自动生成的侧边导航，让复杂的信息体系变得有序且易于查找。此外，Docusaurus 还支持一键部署至各大云服务商，确保你的文档站点能够迅速上线，触手可达。

不止于文档，更宜于知识分享

尽管 Docusaurus 以文档站点构建见长，但其强大的灵活性使其在更多场合大放异彩：

1. 个人博客：借助 Docusaurus，你可以轻松搭建专业的技术博客，专注于创作，让技术之美通过优雅的界面传递给读者。
2. 产品手册：无论是 SaaS 产品还是硬件设备，Docusaurus 都能助你打造用户友好的帮助中心，提升产品的易用性和客户满意度。
3. 内部知识库：在企业环境中，用 Docusaurus 搭建技术规范、设计指南、内部教程等资源库，有助于团队知识沉淀与高效协作。

本文将简单介绍下，如何快速使用 Docusaurus 搭建一个包含全局搜索、国际化、主题切换的文档站点。

创建模板

使用如下命令可以快速创建一个 Docusaurus 应用：

npx create-docusaurus@latest my-website classic

如果你喜欢使用 TypeScript，可以使用如下命令：

npx create-docusaurus@latest my-website classic --typescript

生成的应用组织结构大致如下：

my-website
├── blog
│   ├── 2019-05-28-hola.md
│   ├── 2019-05-29-hello-world.md
│   └── 2020-05-30-welcome.md
├── docs
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   └── mdx.md
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── styles.module.css
│       └── index.js
├── static
│   └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

然后使用npm run start 命令，即可本地运行应用，如下图所示

主题

创建的应用中默认已经配置了相关主题，你可以参考官方文档进行深度定制。下图是默认的另一种主题表现：

全局搜索

Docusaurus 应用提供了多种用于全文搜索的插件，例如：官方提供的Algolia DocSearch,你只需要按照文档安装相应的插件即可。

在这里我使用一个可以进行本地搜索的插件：docusaurus-search-local作为介绍。

安装插件

可以使用 npm 命令安装插件到项目中

npm install @cmfcmf/docusaurus-search-local

如果使用 npm 安装过程中报错，请添加 --force 参数重试。

插件配置

将此插件添加到 docusaurus.config.js 中的插件数组中。

module.exports = {
  // ...
  plugins: [require.resolve("@cmfcmf/docusaurus-search-local")],

  // or, if you want to specify options:

  // ...
  plugins: [
    [
      require.resolve("@cmfcmf/docusaurus-search-local"),
      {
        // Options here
      },
    ],
  ],
};

最终你会看到如下页面：

此时你还不能直接进行全局搜索，你需要使用npm run buid和npm run serve命令后，即可体验搜索功能，如下所示：

国际化

默认创建的引用中，已经有了基础的国际化配置：

module.exports= {
  // Even if you don't use internationalization, you can use this field to set
  // useful metadata like html lang. For example, if your site is Chinese, you
  // may want to replace "en" with "zh-Hans".
  i18n: {
    defaultLocale: "en",
    locales: ["en"],
  },
}

还需要一些额外的配置，才能显示语言切换菜单，切换后显示不同语言的文档。

修改i18n配置

下面是一个使用英文和中文的配置：

module.exports= {
 i18n: {
    defaultLocale: "en", // 默认使用的语言
    locales: ["en", "zh"],// 使用哪些语言
    localeConfigs: { // 语言配置
      en: {
        htmlLang: "en-GB",
      },
      zh: {
        htmlLang: "zh-Hans",
        direction: "ltr",
      },
    },
  },
}

在themeConfig的navbar中添加如下配置：

themeConfig: {
    image: "img/docusaurus-social-card.jpg",
    navbar: {
      items: [
        {
          type: "localeDropdown",
          position: "right", // 菜单的显示位置
        },
      ],
    },

现在你可以在页面上看见语言切换菜单了：

添加对应语言下需要显示的素材

这里我们使用docs为例，看看如何添加不同语言下的素材。

将 docs Markdown 文件从 docs/ 复制到 i18n/zh/docusaurus-plugin-content-docs/current 并翻译它们：

mkdir -p i18n/zh/docusaurus-plugin-content-docs/current
cp -r docs/** i18n/zh/docusaurus-plugin-content-docs/current

完成后，代码结构如下：

然后使用npm run buid和npm run serve命令后，即可查看语言切换功能：

当然你可以使用如下命令，指定语言在开发阶段运行项目：

npm run start -- --locale zh

Docusaurus的确是一个非常棒的文档生成器，有需要的朋友可以用起来，这是一件很酷的事情。

微信扫码关注公众号，获取更多前端资讯

本文由mdnice多平台发布