Docusaurus 是一款构建开源软件文档网站的软件，于约九个月前正式发布。 那时起，本项目收获了 8600 个 GitHub 星标，并被包括 React Native、Babel、Jest、Reason 及 Prettier 在内的活跃开源项目所使用。
俗话说，好软件进步，坏软件止步。 您可能不知道，我们正规划开发下一版 Docusaurus 🎉。
简介#
一切都源始于由 Yangshun 于 2018 年 6 月底新建的RFC 议题。
[RFC] Docusaurus v2 · 议题 #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: hellotitle: 你好---你好，世界！And we cut version 1.0.0, Docusaurus will create versioned_docs/version-1.0.0/hello.md:
---id: version-1.0.0-hellotitle: hellooriginal_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 allows for easy translation functionality by using Crowdin. Documentation files written in English are uploaded to Crowdin for translation by users within a community. We always assumed that English is the default language, but this might not be the case for all users. We have seen plenty of non-English open source projects using Docusaurus.
For Docusaurus 2, we will not assume English is the default language. When a user enables internationalization, they have to set a default language in 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.
可自定义性#
布局#
The current state of Docusaurus is that it is in charge of the entire layout and styling, unintentionally making it very hard for users to customize their site's appearance to their wishes.
For Docusaurus 2, layout and styling should be controlled by the user. Docusaurus will handle the content generation, routing, translation, and versioning. Inspired by create-react-app and VuePress, Docusaurus will still provide a default theme, which the user can eject from, for further layout and styling customization. This means that it is very possible for the user to even change the HTML meta by using React Helmet. Community-based themes are also very possible. This approach of allowing users to be in charge of layout and styling is taken by most static site generators.
Markdown#
Our markdown parsing is currently powered by Remarkable. What if the user wants to use markdown-it or even MDX? And then there is an issue of which syntax highlighter to use, (e.g: Prism vs Highlight.js). We should leave these choices open to the user.
For Docusaurus 2, users can eject and choose their own markdown parser. It does not matter if they want to use another markdown parser such as Remark, or even their own in-house markdown parser. As a rule of thumb, the user has to provide a React component, in which we will provide a children props containing the RAW string of markdown. By default, we will use Remarkable for the markdown parser and Highlight.js for the syntax highlighting. The default parser could still change in the future as we're still experimenting with different markdown parsers.
搜索#
Our core search functionality is based on Algolia. There are requests by users to be able to use different search offerings, such as lunrjs for offline search.
I personally like Algolia and we have a great experience working with them. They are very responsive; we can easily submit a pull request to Algolia since their DocSearch is open source. For example, I recently submitted this PR that enables DocSearch to scrape alternate languages in sitemap.
For Docusaurus 2, we will allow users to customize the search box. Users simply need to eject from the default theme and modify the Search UI (a React component). However, we will still use Algolia in the default theme.
稳定性#
Software is never going to be perfect, but we want Docusaurus to not break as we add new features. When Docusaurus was first released, it did not have any strong automated test suites. As a result, there were a lot of regressions not caught early. Although we have recently added a lot of tests, the test coverage is still relatively low.
For Docusaurus 2, we are adding tests as we develop since we are going for a fresh rewrite. Hence, I believe that it should be more stable than ever and it should be harder to break things compared to 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.