Skip to main content

介绍 Docusaurus

· 9 min read
Joel Marcey
Joel Marcey
Developer Advocate at Meta

我们非常高兴地介绍Docusaurus来帮助您管理一个或多个开源网站。

我们创建Docusaurus的原因如下：

  1. 将重点放在编写好的文档上，而不是担心网站的基础设施。
  2. 提供我们许多开源网站所需的功能，如博客支持、搜索和版本控制。
  3. 为了便于一次性向所有人推送更新、新功能和错误修复。
  4. 最后，为了在我们所有的开源项目中提供一致的外观和感觉。

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

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

Docusaurus的诞生​

<img class="img_vXGZ" decoding="async" height="160" loading="lazy" src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAvgAAACgCAIAAAD2Ao8HAAAbm0lEQVR42u3dCVhV553HcbtMp31m2uk807TTaTvtzDx52sk002xNpjZeRBY3UMANRRQXQBQXFFEWAREBt2B2Y6IhNXFp0hhj1GhMYtQY9Rwu62WVXS67F3BFWeZ/uYYgIAIiXO7933PO9zznOc/5nO/5nO/5nO8ZtrW+DgAAwCINYxMAAACCDgAAgKADAABA0AEAACDoAAAAEHQAAAAIOgAAAAQdAAAAgg4AAABBBwAAgKADAABA0AEAACDoAAAAEHQAAAAIOgAAAAQdAAAAgg4AAABBBwAAgKADAABA0AEAACDoAAAAEHQAAAAIOgAAAAQdAAAAgg4AAABBBwAAgKADAABA0AEAACDoAAAAEHQAAAAIOgAAAAQdAAAAgg4AAABBBwAAgKADAABA0AEAACDoAAAAEHQAAAAIOgAAAAQdAAAAgg4AAABBBwAAgKADAABA0AEAACDoAAAAEHQAAAAIOgAAAAQdAAAAgg4AAABBBwAAgKADAABA0AEAACDoAAAAEHQAAAAIOgAAAAQdAAAAgg4AAABBBwAAgKADAABA0AEAACDoAAAAEHQAAAAIOgAAAAQdAAAAgg4AAABBBwAAgKADAABA0AEAACDoAAAAEHQAAAAIOgAAAAQdAAAAgg4AAABBBwAAgKADAABA0AEAACDoAAAAEHQAAAAIOgAAAAQdAAAAgg4AAABBBwAAgKADAABA0AEAACDoAAAAEHQAAAAIOgAAAAQdAAAAgg4AAABBBwAAgKADAABA0AEAACDoAAAAEHQAAAAIOgAAAAQdAAAAgg4AAABBBwAAgKADAABA0AEAACDoAAAAEHQAAAAIOgAAAAQdAAAAgg4AAABBBwAAgKADAABA0AEAACDoAAAAEHQAAAAIOgAAAAQdAAAAgg4AAABBBwAAgKADAABA0A</p>

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

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

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

所以我们开始思考我们能做些什么来帮助缓解在整个投资组合中保持网站更新和一致的挑战。我们还希望多个项目共享相同的网站生成软件。我们希望它们从相同的模板开始，但又有灵活性来定制和调整它们的网站主题以适应它们的需求。它们应该能够扩展和定制它们的网站，但当我们用修复和功能更新底层基础设施时，项目应该能够简单地更新而没有任何破坏性的变化。

Docusaurus 诞生了！

在Facebook，Docusaurus使我们能够快速为不同的项目启动和运行文档网站，特别是对于那些没有太多网页开发经验或主要希望有一个基本网站来展示他们的项目的团队。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 的核心功能位于 lib 目录 的 Docusaurus 仓库 中。其一般结构如下：

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. 将添加到站点页面文件夹中的任何自定义页面编译/复制到编译站点的根构建目录中。任何翻译版本将放入构建中的特定语言文件夹中。
  11. 创建CNAME和sitemap.xml文件并将它们添加到构建中。

请注意，此过程并未全面考虑翻译或版本控制的工作原理。这些功能的底层细节将留待未来的博客文章中讨论。

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

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:

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

资源​