迈向 Docusaurus 2
Docusaurus 在九个多月前正式发布，旨在轻松构建开源文档网站。自那时起，它已获得超过 8,600 个 GitHub 星标，并被许多流行的开源项目使用，例如 React Native、Babel、Jest、Reason 和 Prettier。
俗话说，最好的软件是不断进化的，而最差的则不然。如果您还不知道，我们一直在计划并致力于 Docusaurus 的下一个版本 🎉。
引言
这一切都始于 Yangshun 于 2018 年 6 月底提出的 RFC 问题。
[RFC] Docusaurus v2 · Issue #789 · facebook/docusaurus
这些是我目前在 Docusaurus 中看到的一些问题，以及我们如何在 v2 中解决它们。这里的一些想法受到了 VuePress 和其他静态站点生成器的启发。在当前的静态站点生成器生态系统中，t...
大多数建议的改进都已在问题中提及；我将详细说明 Docusaurus 1 中的一些问题以及我们如何在 Docusaurus 2 中解决它们。
基础设施
内容
Docusaurus 1 网站实际上是由一堆静态 HTML 页面构建而成的。尽管使用了 React，但我们并未充分利用 React 提供的功能，例如组件状态，它允许动态和交互式页面。React 仅用作静态内容的模板引擎，交互性必须通过脚本标签和 dangerouslySetInnerHTML 😱 来添加。
此外，没有简单的方法来改变 Docusaurus 加载内容的方式。例如，原生不支持添加 CSS 预处理器（如 Sass 和 Less），并且需要用户通过添加自定义脚本进行大量修改。
对于 Docusaurus 2，我们将使用 webpack 作为模块打包器，并且我们将改变内容服务方式。添加 CSS 预处理器将像添加 webpack loader 一样简单。Docusaurus 站点将不再是纯静态 HTML，而是在构建时创建应用程序的服务器渲染版本并渲染相应的 HTML。Docusaurus 站点本质上将是一个同构/通用应用程序。这种方法深受 Gatsby 启发。
版本控制
如果您已经使用 Docusaurus 一段时间，您可能会注意到 Docusaurus 仅在文档内容不同时才创建版本化文档。
例如，如果我们有 docs/hello.md
---
id: hello
title: hello
---
Hello world !
并且我们切出 1.0.0 版本，Docusaurus 将创建 versioned_docs/version-1.0.0/hello.md
---
id: version-1.0.0-hello
title: hello
original_id: hello
---
Hello world !
然而，如果在切出 v2.0.0 时 hello.md 没有变化，Docusaurus 将不会为该文档创建任何版本化文档。换句话说，versioned_docs/version-2.0.0/hello.md 将不存在。
这可能会让用户感到非常困惑；如果他们想编辑 v2.0.0 文档，他们必须编辑 versioned_docs/version-1.0.0/hello.md 或手动添加 versioned_docs/version-2.0.0/hello.md。这可能会导致不必要的错误。这是一个Jest 中的真实场景。
此外，这增加了代码库的复杂性，因为我们需要一个版本回退机制。在构建时，Docusaurus 必须将链接替换为正确的版本。这也是一个导致重命名文档会破坏旧版本链接的错误的原因。
对于 Docusaurus 2，每次我们切出新版本时，我们将 instead 采取所有文档的快照。我们将不要求文档内容必须发生变化。这是为了更好的开发者和用户体验而进行的空间复杂度权衡。我们将使用更多空间来更好地分离关注点并保证正确性。
翻译
Docusaurus 通过使用 Crowdin 实现了简单的翻译功能。用英文编写的文档文件被上传到 Crowdin，供社区用户翻译。我们一直假设英语是默认语言，但这可能不适用于所有用户。我们已经看到许多非英语开源项目使用 Docusaurus。
对于 Docusaurus 2，我们不会假设英语是默认语言。当用户启用国际化时，他们必须在 siteConfig.js 中设置一个默认语言。然后我们将假设 docs 中的所有文件都以该语言编写。
此外，在完成 Docusaurus 2 的 MVP 后，我意识到可以不使用 Crowdin 进行翻译。因此，我们可能需要添加一个额外的工作流程来启用这种情况。但是，我们仍然强烈建议人们使用 Crowdin 以便更轻松地集成。
可定制性
布局
Docusaurus 的现状是它负责整个布局和样式，无意中使得用户很难按照自己的意愿定制网站的外观。
对于 Docusaurus 2，布局和样式应由用户控制。Docusaurus 将处理内容生成、路由、翻译和版本控制。受 create-react-app 和 VuePress 的启发，Docusaurus 仍将提供一个默认主题，用户可以从该主题中“弹出（eject）”，以进行进一步的布局和样式定制。这意味着用户甚至可以使用 React Helmet 更改 HTML meta。基于社区的主题也很有可能。这种允许用户控制布局和样式的方法被大多数静态站点生成器所采用。
Markdown
我们当前的 Markdown 解析由 Remarkable 提供支持。如果用户想使用 Markdown-it 甚至 MDX 怎么办？还有一个问题是使用哪种语法高亮工具（例如：Prism vs Highlight.js）。我们应该把这些选择权留给用户。
对于 Docusaurus 2，用户可以弹出（eject）并选择自己的 Markdown 解析器。无论他们是想使用像 Remark 这样的另一个 Markdown 解析器，还是他们自己的内部 Markdown 解析器，都没有关系。作为一般规则，用户必须提供一个 React 组件，我们将为其提供一个包含原始 Markdown 字符串的子 props。默认情况下，我们将使用 Remarkable 作为 Markdown 解析器，使用 Highlight.js 作为语法高亮。默认解析器将来可能仍会改变，因为我们仍在尝试不同的 Markdown 解析器。
搜索
我们的核心搜索功能基于 Algolia。用户要求能够使用不同的搜索服务，例如用于离线搜索的 lunrjs。
我个人喜欢 Algolia，并且我们与他们合作得非常愉快。他们反应迅速；我们可以轻松地向 Algolia 提交拉取请求，因为他们的 DocSearch 是开源的。例如，我最近提交了这个 PR，它使 DocSearch 能够抓取站点地图中的备用语言。
对于 Docusaurus 2，我们将允许用户自定义搜索框。用户只需从默认主题中弹出并修改搜索 UI（一个 React 组件）即可。但是，默认主题中我们仍将使用 Algolia。
稳定性
软件永远不会完美，但我们希望 Docusaurus 在添加新功能时不会崩溃。Docusaurus 最初发布时，没有任何强大的自动化测试套件。因此，早期没有发现很多回归问题。尽管我们最近添加了大量测试，但测试覆盖率仍然相对较低。
对于 Docusaurus 2，我们将在开发过程中添加测试，因为我们正在进行全新重写。因此，我相信它将比以往任何时候都更加稳定，并且与 Docusaurus 1 相比，破坏事物的难度更大。
常见问题
会有重大变更吗？
如果您已经读到这里，您应该会注意到将会有重大变更。虽然我们会尽量减少重大变更的数量并尽可能保持向后兼容，但我们认为有些重大变更是有必要的。这主要是因为 Docusaurus 2 是对代码库的重大重写和重新架构。
由于开发尚未 100% 完成，因此重大变更的确切列表尚不完全清楚。但是，我将强调的一点是，我们将弃用 siteConfig.js 中的许多选项，并且我们计划使其尽可能精简。例如，cleanUrl siteConfig 将被弃用，因为 Docusaurus 2 站点的所有 URL 将不带 .html 后缀。
我们的目标是大多数站点都应该能够轻松升级到 Docusaurus 2。发布 Docusaurus 2 时，我们还将提供一份迁移指南。届时，如有问题和需要帮助，请随时在 Discord 或 X 上联系我们。
Docusaurus 2 何时发布？
截至目前，我们尚未确定具体的发布日期。我个人估计我们可能在一到两个月内发布 Alpha 版本，但这当然只是一个估计。
我想分享的一点是，虽然 Docusaurus 是 Facebook 开源的一部分，并且团队的大多数成员都是 Facebook 员工，但维护和开发工作大部分是在正常工作时间之外完成的。我目前是 新加坡南洋理工大学 的一名大四学生，所以我必须兼顾学业、毕业设计以及 Docusaurus 的维护和开发。然而，这并不意味着我们不想让 Docusaurus 变得更好。事实上，我们希望让它尽可能地出色。
目前，Docusaurus 2 的实际工作仍托管在私有仓库中。在不久的将来，我们会将其转移到公共仓库中。届时，我鼓励大家关注它，希望能以某种方式做出贡献。在此之前，请保持关注😉！
结语
Docusaurus 对开源社区产生了巨大影响，这从许多使用 Docusaurus 进行文档编制的流行项目中可见一斑。为了未来更快地发展，我们正在借此机会修复 Docusaurus 1 中的一些核心问题，并努力使 Docusaurus 对每个人都更好。事实上，可以肯定地说，Docusaurus 2 不再只是一个计划；它的工作已经开始，希望在不久的将来我们能看到它成为现实。
Docusaurus 的使命始终是让您轻松地开箱即用地搭建一个带有文档的网站。这一使命在 Docusaurus 2 中并未改变。
我们还想让大家知道，由于正在进行 Docusaurus 2 的工作，我们不太可能接受 Docusaurus 1 上的新功能/重大更改。
如果您正在使用 Docusaurus，您就是我们社区的一员；请继续告诉我们如何才能让 Docusaurus 更好地为您服务。如果您赞赏我们所做的工作，您可以在 Open Collective 上支持 Docusaurus。
如果您在 Open Collective 上赞助我们的工作，我们将亲自为您提供 Docusaurus 网站的维护和升级帮助。