跳至主要内容

介绍 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. 读取文档目录中所有 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 和 Twitter 上关注我们。

鸣谢​

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

我们还要特别感谢 Docusaurus 最早的使用者

如果没有他们对创建或将他们的网站迁移到该平台的奉献，我们将不会处于今天的位置。

资源​