跳到主要内容

Docusaurus 简介

·9 分钟阅读
Joel Marcey
Joel Marcey
Meta 公司开发者倡导者

我们很高兴推出 Docusaurus，它可以帮助您管理一个或多个开源网站。

我们创建 Docusaurus 是出于以下原因

  1. 专注于编写高质量的文档，而不是担心网站的基础设施。
  2. 提供我们许多开源网站所需的功能，例如博客支持、搜索和版本控制。
  3. 方便地一次性向所有人推送更新、新功能和错误修复。
  4. 最后，为我们所有的开源项目提供一致的外观和体验。

Docusaurus 是一个旨在让团队轻松发布文档网站的工具，无需担心基础设施和设计细节。其核心是，用户只需提供用 Markdown 编写的文档文件、对提供的 React 编写的主页进行自定义以及一些配置修改。Docusaurus 通过提供默认样式、站点格式和简单的文档导航来处理其余部分。入门非常简单，用户可以通过简单的初始化脚本使用 npm 或 yarn 安装它，该脚本可以立即创建一个可用的示例网站。

Docusaurus 还提供了开箱即用的核心网站和文档功能，包括博客支持、国际化、搜索和版本控制。虽然某些项目可能不需要这些功能，但启用它们通常只是更新配置选项的问题，而不是从头开始添加基础设施。随着 Docusaurus 添加更多功能，用户可以轻松更新到最新版本。这可以通过简单地运行 npm 或 yarn update 并更新配置选项来完成。用户或团队将不再需要每次添加新功能时都手动修改其整个网站基础设施。

Docusaurus 的诞生​

当 Facebook 首次启动其开源项目时，许多团队为其各自的开源项目都实施了定制网站。当开源项目团队被要求帮助项目团队改进其文档时，这种方法带来了挑战。由于每个网站都是独一无二的，添加博客、一致导航、搜索等基本基础设施变得具有挑战性。

开源团队试图通过提出一个基于 Jekyll 的标准模板来帮助缓解这个问题，该模板可以作为项目网站的起点。我们要求新的项目手动将我们的模板源复制到他们的仓库，编写文档并发布。这种模板方法被大多数已启动的开源项目所采用；一些现有项目甚至也将其定制网站实现转换到新模板。

“将模板复制到你的仓库”方法的问题在于，即使平台保持一致，向已使用模板的整个项目套件推送更新也变得难以维护。这是因为项目将其复制到仓库后，我们失去了对模板的控制。项目可以自由修改模板，并向其应用自己的项目特定功能。因此，尽管项目共享相同的网站生成平台，但它们现在已经分化到无法利用我们随时间推移添加到模板中的新功能的地步。没有简单的方法可以要求所有当前项目“复制”新版本的模板，因为它可能会破坏他们现有站点或删除他们自己添加的功能。相反，我们必须手动将更新一个接一个地应用到每个项目。当项目开始向我们的团队请求模板中的国际化支持时，这变得非常成问题，因为它需要对模板的结构和生成方式进行低级更改。

因此，我们开始思考如何帮助缓解在我们整个产品组合中保持网站更新和一致的挑战。我们还希望多个项目共享相同的网站生成软件。我们希望它们从相同的模板开始，但又具有灵活性，可以根据自己的需求定制和调整网站主题。他们应该能够扩展和自定义其网站，但当我们更新底层基础设施并进行修复和添加功能时，项目应该能够简单地更新，而不会出现任何破坏性更改。

Docusaurus 诞生了！

在 Facebook，Docusaurus 让我们能够快速让不同项目拥有文档网站，特别是对于那些没有太多 Web 开发经验或主要想要一个基本网站来展示其项目的团队。Docusaurus 已经支持需要更高级功能的网站，例如 Jest 的国际化和 React Native 的版本控制。随着不同项目为其网站请求新功能，这些功能会被添加到 Docusaurus 并同时提供给所有项目！总而言之，这大大减少了为不同项目维护不同网站所需的工作。我们的团队能够通过花费更多时间添加功能、修复错误和编写文档来使他们的项目更健康。

快速入门​

其核心是，我们希望运行 Docusaurus 的网站易于使用。通过一个安装命令和一些简单配置，您就可以拥有一个默认运行的网站。

当您运行 docusaurus-init 时，您将看到类似于以下结构的目录：

root-of-repo
├── docs-examples-from-docusaurus
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   ├── example-doc4.md
│   └── example-doc5.md
├── website
│   ├── blog-examples-from-docusaurus
│   │   ├── 2016-03-11-blog-post.md
│   │   └── 2017-04-10-blog-post-two.md
│   ├── core
│   │   └── Footer.js
│   ├── node_modules
│   ├── package.json
│   ├── pages
│   ├── sidebars.json
│   ├── siteConfig.js
│   └── static

除了 `node_modules` 和 `package.json` 之外，您看到的所有目录和文件都是您自定义和向基于 Docusaurus 的网站添加内容的地方。`docs` 文件夹是您添加代表您文档的 Markdown 文件的地方；`blog` 文件夹是您添加博客文章 Markdown 文件的地方；siteConfig.js 是您对网站进行大部分自定义的地方；sidebars.json 是您维护文档侧边栏布局和内容的地方；`pages` 文件夹是您为网站添加自定义页面的地方；`static` 文件夹是您所有静态资产（例如，CSS 样式表和图片）的存放之处；而 `core` 文件夹是您可以自定义网站核心组件的地方，在本例中是页脚。

Docusaurus 如何工作？​

Docusaurus 主要使用 JavaScript 和 React 编写，取代了我们在旧模板中使用的 Jekyll。我们使用 Remarkable 进行 Markdown 渲染，并使用 highlight.js 进行代码块语法高亮。Docusaurus 的核心功能位于 Docusaurus 仓库的 `lib` 目录中。大致结构如下：

root-of-Docusaurus
├── lib
│   ├── core
│   ├── server
│   │   ├── generate.js
│   │   ├── server.js
│   │   └── ...and more files
│   ├── static
│   ├── build-files.js
│   ├── copy-examples.js
│   ├── generate-feed.js
│   ├── publish-gh-pages.js
│   ├── rename-version.js
│   ├── start-server.js
│   ├── versions.js
│   └── write-translations.js

这里的关键文件是 `build-files.js` 和 `start-server.js`。这两个文件有很多相似之处：`build-files.js` 用于构建供外部 Web 服务器服务的物理工件。`start-server.js` 用于运行 Docusaurus 服务器并在本地测试您的网站。两者都通过以下通用流程，将所有 Markdown 和配置转换为可运行的网站：

  1. 处理您在 `siteConfig.js` 中的网站设置
  2. 读取 `docs` 目录中所有 Markdown 文件中的文档元数据。
  3. 根据从元数据中提取的 ID 为您的文档创建目录。
  4. 将 Markdown 转换为 HTML，包括进行链接替换。
  5. 这些文件将位于编译后站点的 `build/docs` 目录中，任何翻译版本将位于 `build/docs` 文件夹中特定语言的文件夹内。
  6. 对博客文章重复步骤 1-3。
  7. 博客文件将位于编译后站点的 `build/blog` 目录中。
  8. 读取 `main.css` 文件并将所有用户定义的 CSS 连接到主 CSS 文件中，该文件将位于编译后站点的 `build/css` 目录中。
  9. 将图片复制到编译后站点的 `build/img` 目录中。
  10. 将添加到站点 `pages` 文件夹中的所有自定义页面编译/复制到编译后站点的根 `build` 目录中。任何翻译版本将位于 `build` 内部的特定语言文件夹中。
  11. 创建 `CNAME` 和 `sitemap.xml` 文件并将它们添加到 `build` 目录。

请注意，此过程未完全考虑翻译或版本控制的工作方式。这些功能的底层细节将留待未来的博客文章中介绍。

您的编译后站点的最终结构将类似于

build
├── website
│   ├── CNAME
│   ├── blog
│   ├── css
│   ├── docs
│   ├── en
│   ├── help.html # custom page
│   ├── img
│   ├── index.html # landing page
│   ├── sitemap.xml
│   └── users.html # custom page

社区​

我们欢迎您为 Docusaurus 做出贡献，无论您是想将其用于自己的网站，还是想为 Docusaurus 核心做出贡献，或者只是有问题。在GitHub 和 X) 上关注我们。

鸣谢​

如果没有 Docusaurus 核心团队其他成员的工作，Docusaurus 将不复存在：Eric Nakagawa、Hector Ramos、Eric Vicenti 和 Frank Li——一位前 Facebook 实习生，他实现了核心技术和功能。

特别感谢 Docusaurus 的早期采用者

如果没有他们致力于创建或将其网站迁移到该平台，我们今天就不会处于这个位置。

资源​