Docusaurus 简介
我们非常高兴地向您介绍 Docusaurus ，它可以帮助您管理一个或多个开源网站。
我们创建 Docusaurus 的原因如下：
- 将重点放在撰写优质文档上，而不是担心网站的基础设施。
- 提供许多开源网站所需的特性，例如博客支持、搜索和版本控制。
- 方便一次性向所有人推送更新、新功能和错误修复。
- 最后，为我们所有的开源项目提供一致的外观和感觉。
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 和配置以创建可运行的网站：
- 处理
siteConfig.js中的网站设置。 - 读取文档目录中所有 Markdown 文件中存在的文档元数据。
- 根据从元数据中提取的 ID 创建文档的目录。
- 将 Markdown 转换为 HTML，包括进行链接替换。
- 这些文件将进入编译站点的 build/docs 目录，任何翻译版本都将进入 build/docs 文件夹内的特定语言文件夹。
- 对博客文章重复步骤 1-3。
- 博客文件将进入编译站点的 build/blog 目录。
- 读取 main.css 文件并将任何用户定义的 css 连接到将位于编译站点 build/css 目录中的主 css 文件中。
- 将图像复制到编译站点的 build/img 目录中。
- 获取添加到站点 pages 文件夹的任何自定义页面，并将这些页面编译/复制到编译站点的根 build 目录中。任何翻译版本都将进入 build 内的特定语言文件夹。
- 创建 CNAME 和 sitemap.xml 文件并将它们添加到 build 中。
请注意，此过程并未完全考虑翻译或版本控制的工作方式。这些功能的底层细节将保留在以后的博客文章中。
编译后站点的最终结构将类似于：
build
├── website
│ ├── CNAME
│ ├── blog
│ ├── css
│ ├── docs
│ ├── en
│ ├── help.html # 自定义页面
│ ├── img
│ ├── index.html # 首页
│ ├── sitemap.xml
│ └── users.html # 自定义页面
社区
我们欢迎您对 Docusaurus 的 贡献 ，无论您是想将其用于您自己的站点，是想 贡献 Docusaurus 核心，还是只是有疑问。请在 GitHub 和 X 上关注我们。
致谢
如果没有 Docusaurus 核心团队其他成员的工作，Docusaurus 将不存在： Eric Nakagawa 、 Hector Ramos 、 Eric Vicenti 和 Frank Li ——Facebook 的前实习生，他实现了核心技术和功能。
还要特别感谢我们 Docusaurus 最早的 采用者 ：
如果没有他们致力于创建或将他们的网站迁移到该平台，我们就不会处于今天的境地。