Docusaurus 2 发展方向
九个月前，Docusaurus 正式发布 ，旨在轻松构建开源文档网站。此后，它已在 GitHub 上获得超过 8,600 个星标，并被许多流行的开源项目使用，例如 React Native , Babel , Jest , Reason 和 Prettier 。
俗话说，最好的软件一直在不断发展，而最差的软件则停滞不前。如果您不知道，我们一直在规划和开发 Docusaurus 的下一个版本 🎉。
简介
这一切都始于 Yangshun 在 2018 年 6 月底提出的这个 RFC issue 。
[RFC] Docusaurus v2 · Issue #789 · facebook/docusaurus
这些是我现在在 Docusaurus 中看到的一些问题，以及我们如何在 v2 中解决它们的方法。这里的一些想法受到了 VuePress 和其他静态站点生成器的启发。在当前的静态站点生成器生态系统中，t...
该 issue 中提到了大部分建议的改进；我将详细介绍 Docusaurus 1 中的一些问题以及我们如何在 Docusaurus 2 中解决它们。
架构
内容
事实上，Docusaurus 1 网站构建成一堆静态 HTML 页面。尽管使用了 React，但我们并没有充分利用 React 提供的功能，例如组件状态，它允许创建动态和交互式的页面。React 只被用作静态内容的模板引擎，交互性必须通过脚本标签和 dangerouslySetInnerHTML 😱 来添加。
此外，没有简单的方法来更改 Docusaurus 加载内容的方式。例如，原生不支持添加 Sass 和 Less 等 CSS 预处理器，需要用户通过添加自定义脚本进行许多hack操作。
对于 Docusaurus 2，我们将使用 webpack 作为模块打包器，并将更改我们提供内容的方式。添加 CSS 预处理器将像添加 webpack loader 一样简单。我们将 在构建时创建应用程序的服务器端渲染版本 并渲染相应的 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， 每次我们发布新版本时，我们将对所有文档进行快照 。我们不需要文档的内容发生更改。这是以空间复杂性为代价换取更好的开发者和用户体验。我们将使用更多空间来实现更好的关注点分离和保证正确性。
翻译
Docusaurus 通过使用 Crowdin 允许轻松实现翻译功能。用英语编写的文档文件上传到 Crowdin，由社区中的用户进行翻译。我们总是假设 英语 是默认语言，但这可能并非所有用户都是如此。我们已经看到许多非英语的开源项目使用了 Docusaurus。
对于 Docusaurus 2， 我们将不会假设英语是默认语言 。当用户启用国际化时，他们必须在 siteConfig.js 中设置默认语言。然后，我们将假设 docs 中的所有文件都是用该语言编写的。
此外，在完成 Docusaurus 2 的 MVP 后，我意识到可以不使用 Crowdin 进行翻译。因此，我们可能需要添加一个额外的流程来启用这种情况。但是，我们仍然强烈建议大家使用 Crowdin，以便更容易集成。
可定制性
布局
Docusaurus 的当前状态是它负责整个布局和样式，无意中使得用户很难根据自己的意愿自定义网站的外观。
对于 Docusaurus 2， 布局和样式应由用户控制 。Docusaurus 将处理内容生成、路由、翻译和版本控制。受 create-react-app 和 VuePress 的启发，Docusaurus 仍将提供一个默认主题，用户可以从中弹出以进行进一步的布局和样式定制。这意味着用户甚至可以使用 React Helmet 来更改 HTML 元数据。基于社区的主题也是非常可能的。这种让用户负责布局和样式的方法已被大多数静态站点生成器采用。
Markdown
我们当前的 Markdown 解析器由 Remarkable 提供支持。如果用户想使用 Markdown-it 甚至 MDX 会怎样？然后就是使用哪个语法高亮器的问题（例如： Prism vs Highlight.js ）。我们应该将这些选择留给用户。
对于 Docusaurus 2， 用户可以弹出并选择他们自己的 Markdown 解析器 。他们是否想使用其他 Markdown 解析器，例如 Remark ，甚至是他们自己内部的 Markdown 解析器都没有关系。根据经验法则，用户必须提供一个 React 组件，我们将在其中提供一个 children 属性，其中包含 Markdown 的_原始字符串_。默认情况下，我们将使用 Remarkable 作为 Markdown 解析器，并使用 Highlight.js 进行语法高亮。默认解析器将来可能还会更改，因为我们仍在尝试不同的 Markdown 解析器。
搜索
我们的核心搜索功能基于 Algolia 。用户请求能够使用不同的搜索服务，例如 lunrjs 用于离线搜索。
我个人喜欢 Algolia，并且我们与他们的合作非常愉快。他们非常有响应能力；我们可以轻松地向 Algolia 提交 pull request，因为他们的 DocSearch 是开源的。例如，我最近提交了 这个 PR，它使 DocSearch 能够在站点地图中抓取备用语言 。
对于 Docusaurus 2， 我们将允许用户自定义搜索框 。用户只需要从默认主题中弹出并修改搜索 UI（一个 React 组件）即可。但是，我们仍然会在默认主题中使用 Algolia。
稳定性
软件永远不可能完美，但我们希望 Docusaurus 在添加新功能时不会崩溃。Docusaurus 首次发布时，没有任何强大的自动化测试套件。结果，许多回归测试没有及早发现。虽然我们最近添加了许多测试，但测试覆盖率仍然相对较低。
对于 Docusaurus 2， 我们在开发时添加测试 ，因为我们正在进行全新的重写。因此，我相信它应该比以往任何时候都更加稳定，并且与 Docusaurus 1 相比，破坏事物应该更加困难。
常见问题
会有重大更改吗？
如果您已经阅读了本文，您应该会注意到会有重大更改。虽然我们将尝试 尽量减少重大更改的次数 并使其尽可能向后兼容，但我们认为需要进行一些重大更改。这主要是因为 Docusaurus 2 对代码库进行了 主要的重写和重新架构 。
重大更改的确切列表尚不完全确定，因为开发尚未完全完成。但是，我要强调的一点是，我们将弃用 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 网站。