迈向 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 加载内容的方式。例如，本机不支持添加 Sass 和 Less 等 CSS 预处理器，并且需要用户通过添加自定义脚本进行很多 hack。
对于 Docusaurus 2，我们将使用 webpack 作为模块打包器，并且我们将更改提供内容的方式。添加 CSS 预处理器就像添加 webpack 加载器一样简单。而不是纯静态 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 与 Highlight.js）。我们应该将这些选择留给用户。
对于 Docusaurus 2，用户可以弹出并选择自己的 Markdown 解析器。他们是否要使用其他 Markdown 解析器（如 Remark）或他们自己的内部 Markdown 解析器都没有关系。根据经验法则，用户必须提供一个 React 组件，我们将在其中提供一个包含Markdown 的原始字符串的 children 属性。默认情况下，我们将使用 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 对代码库进行了重写和重新架构。
重大更改的确切列表目前还没有完全确定，因为开发工作尚未完全完成。但是，我要强调的一点是，我们将弃用 siteConfig.js 中的许多选项，并且我们计划使其尽可能精简。例如，cleanUrl siteConfig 将被弃用，因为所有 Docusaurus 2 站点的 URL 都将没有 .html 后缀。
我们的目标是大多数站点都能够轻松地升级到 Docusaurus 2。我们还将在发布 Docusaurus 2 时提供迁移指南。届时，欢迎您在 Discord 或 Twitter 上向我们提出问题并寻求帮助。
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 网站。