Docusaurus 是一款构建开源软件文档网站的软件，于约九个月前正式发布。 那时起，本项目收获了 8600 个 GitHub 星标，并被包括 React Native、Babel、Jest、Reason 及 Prettier 在内的活跃开源项目所使用。
俗话说：“逆水行舟，不进则退”，软件也是如此。 您可能不知道，我们正规划开发下一版 Docusaurus 🎉。
Docusaurus 介绍
一切都源始于由 Yangshun 于 2018 年 6 月底新建的RFC 议题。
[RFC] Docusaurus v2 · Issue #789 · facebook/docusaurus
以下是我在 Docusaurus 中遇到的问题，及我们将如何在 v2 中解决。 我们受到了 VuePress 及其他静态站点生成器的启发，产生了这里的一系列想法。 在当前静态网站生成器的生态系统中，存在以下工具……
此议题中提到了多数推荐的改进措施；我将阐述 Docusaurus 1 中所存在的部分问题，以及在 Docusaurus 2 中的解决方式。
基础设施
内容
Docusaurus 1 站点实际上被构建为一系列静态 HTML 页面。 虽然使用了 React，但我们并未发挥出它所提供的所有特性，如允许动态及交互页面的组件状态功能。 React 仅仅被我们作为一款静态内容模板引擎，交互性则透过脚本标签及 dangerouslySetInnerHTML 实现😱。
此外，改变 Docusaurus 加载内容的方式较为困难。 举个例子，我们不支持原生添加如 Sass 及 Less 在内的 CSS 预处理器，这导致了用户添加自定义脚本的一些奇技淫巧。
在 Docusaurus 2 中，我们将使用 webpack 作为模块打包程序，并重构内容的提供方式。 添加 CSS 预处理器仅如添加一款 webpack 加载器一样容易。 我们将在构建过程中创建应用程序的服务端渲染版本，并渲染相应的 HTML 文件，而非提供纯静态 HTML。 Docusaurus 网站将成为一款同构/通用的应用程序。 此特性深受 Gatsby 的启发。
分版
您若使用了一段时间的 Docusaurus，您可能会留意到它在只会在当且仅当文档内容不一致时才会创建分版文档。
举个例子，假设存在文件 docs/hello.md：
---
id: hello
title: 你好
---
你好，世界！
And we cut version 1.0.0, Docusaurus will create versioned_docs/version-1.0.0/hello.md:
---
id: version-1.0.0-hello
title: hello
original_id: hello
---
Hello world !
However, if there are no changes to hello.md when cutting v2.0.0, Docusaurus will not create any versioned docs for that document. In other words, versioned_docs/version-2.0.0/hello.md will not exist.
This can be very confusing for users; if they want to edit the v2.0.0 docs, they have to edit versioned_docs/version-1.0.0/hello.md or manually add versioned_docs/version-2.0.0/hello.md. This could potentially lead to unwanted bugs. Here is a real scenario in Jest.
In addition, this adds complexity within the codebase as we require a mechanism for version fallbacks. And during build time, Docusaurus has to replace the linking to the correct version. This is also the cause of a bug where renaming docs breaks links in old versions.
For Docusaurus 2, every time we cut a new version, we will instead take a snapshot of all the docs. We will not require the content of a document to have changed. This is a space complexity trade-off for a better developer and user experience. We will use more space for better separation of concerns and guaranteed correctness.
翻译
Docusaurus 通过使用 Crowdin 提供简便的翻译功能。 英文编写的文档文件会被上传到 Crowdin，由社区中的用户进行翻译。 我们总是将 英语 作为默认语言，但这对有些用户来说不太友好。 我们已经看到大量非英语的开源项目在使用 Docusaurus。
对于 Docusaurus 2, 我们不会假定英语是默认语言 当用户启用国际化功能时，他们需要在 siteConfig.js 中设置默认语言。 We will then assume that all the files in docs are written in that language.
In addition, after working on the MVP of Docusaurus 2, I realized that it is possible not to use Crowdin for translations. Thus, we might need to add an additional workflow to enable that scenario. However, we will still strongly recommend people use Crowdin for easier integration.
可自定义性
布局
Docusaurus 当前的问题是它全权掌控了所有的布局和风格， 无意中使用户很难按照自己的愿望定制自己网站的外观。
在 Docusaurus 2 中，布局和样式应能由用户控制。 Docusaurus 将处理内容生成、路由、翻译和版本控制。 受到 Create-react-app 和 VuePress 的启发，Docusaurus 仍将提供一个默认主题，但是用户可以从中剥离出来，进一步的自定义布局和风格。 这意味着用户甚至可以使用 React Helmet 来更改HTML meta。 社区主题也是很可能会被推出的。 大多数静态站点生成器都采取了这种允许用户负责布局和样式的做法。
Markdown
我们目前使用 Remarkable 来解析Markdown。 但是如果用户想要使用 Markdown-it 或者 MDX 怎么办？ 然后还有要使用哪个语法高亮的问题（例如：使用 Prism 还是 Highlight.js）。 我们应该让用户自己作出选择。
对于Docusaurus 2, 用户可以不选择默认配置并选择自己的Markdown解析器。 如果用户想要使用另一个Markdown 解析器，如 Remark，甚至他们自己的内部Markdown 解析器都无关紧要。 作为规范，用户必须提供一个React组件。 我们将提供一个字符串，包含了_原 Markdown 字符串_。 默认情况下，我们将使用 Remarkable 作为 Markdown 解析器并使 用 Highlight.js 进行语法高亮。 默认解析器将来可能会改变，因为我们仍在不断尝试不同的Markdown 解析器。
搜索
我们的核心搜索功能基于 Algolia。 有用户希望能使用不同的搜索服务，例如 lunrjs 来进行离线搜索。
我个人喜欢 Algolia，我们有很多与他们合作的经验。 他们反应速度很快；我们可以轻松地向Algolia提交pull请求，因为他们的 Docsearch 是开源的。 例如，最近我提交了这个 PR，使得 DocSearch 能够在站点地图中抓取其他语言。
对于Docusaurus 2，我们将允许用户自定义搜索框。 用户只需从默认主题中继承并修改搜索界面（一个React组件）。 然而，我们仍将在默认主题中使用Algolia。
稳定性
软件永远不会完美，我们希望 Docusaurus 不要在我们添加新功能时项目中断。 当 Docusaurus 首次发布时，它没有任何强大的自动化测试套件。 导致了许多问题没能早早地被发现。 尽管我们最近增加了大量测试，但测试覆盖面相对较低。
对于Docusaurus 2, 我们会在开发时进行测试，因为我们要进行一次重构 因此我认为Docusaurus 2应该比以往任何时候、任何版本都将更加稳定，与Docusaurus 1相比，出问题应该也更加困难。
常见问题
会有重大变更吗？
If you've read the post up until to this point, you should be able to notice that there will be breaking changes. While we will try to minimize the number of breaking changes and make it backward compatible as much as possible, we believe that some breaking changes are required. This is mostly due to Docusaurus 2 being a major rewrite and re-architecting of the codebase.
The exact list of breaking changes is not totally known yet as development is not 100% finalized. However, one thing that I will highlight is that we will deprecate a lot of options in siteConfig.js and we plan to keep it as lean as possible. For example, the cleanUrl siteConfig will be deprecated as all the URL for Docusaurus 2 sites will be without the .html suffix.
Our goal is that most sites should be able to upgrade to Docusaurus 2 without a lot of pain. We will also include a migration guide when we release Docusaurus 2. When the times come, feel free to ping us on Discord or Twitter for questions and help.
Docusaurus 2 何时发布？
As of now, we do not have an exact date planned for the release. I personally estimate that we might be able to release an alpha version in the next one to two months, but this is, of course, just an estimate.
One thing that I would like to share is that while Docusaurus is part of Facebook Open Source and most of the team are Facebook employees, the maintenance and development work is mostly done outside of normal working hours. I am currently a final year undergraduate student at NTU Singapore, so I had to juggle between doing my coursework, my final year project and maintaining/developing Docusaurus. However, that does not mean that we do not want to make Docusaurus better. In fact, we want to make it as awesome as possible.
For now, the actual Docusaurus 2 work is still hosted in a private repository. In the near future, we will move them into the public repository. When that time arrives, I encourage everyone to look into it and hopefully contribute in some way. Before then, please stay tuned 😉!
Final Thoughts
Docusaurus has had a large impact on the open source community as seen from the many popular projects which use Docusaurus for documentation. In order to move faster in the future, we are taking the opportunity to fix some core problems with Docusaurus 1 and striving to make Docusaurus better for everyone. In fact, it is safe to say that Docusaurus 2 is not just a plan any longer; the work on it has started and, hopefully, we will be able to see it materialize in the near future.
Docusaurus' mission has always been to make it really easy for you to get a website with documentation up and running out of the box. That mission does not change with Docusaurus 2.
We also want to let people know that due to work on Docusaurus 2, we will be less likely to accept new features/major changes on Docusaurus 1.
If you are using Docusaurus, you are part of our community; keep letting us know how we can make Docusaurus better for you. If you appreciate the work we're doing, you can support Docusaurus on Open Collective.
If you are sponsoring our work on Open Collective, we'll personally offer you a helping hand for maintenance and upgrading of Docusaurus website.
Lastly, if you haven't done so already, click the star and watch button on GitHub, and follow us on Twitter.