迈向 Docusaurus 2
Docusaurus was officially announced over nine months ago as a way to easily build open source documentation websites. Since then, it has amassed over 8,600 GitHub Stars, and is used by many popular open source projects such as React Native, Babel, Jest, Reason and Prettier.
俗话说:“逆水行舟,不进则退”,软件也是如此。 您可能不知道,我们正规划开发下一版 Docusaurus 🎉。
Docusaurus 介绍
It all started with this RFC issue opened by Yangshun towards the end of June 2018.
[RFC] Docusaurus v2 · Issue #789 · facebook/docusaurus
These are some of the problems I'm seeing in Docusaurus now and also how we can address them in v2. 我们受到了 VuePress 及其他静态站点生成器的启发,产生了这里的一系列想法。 在当前静态网站生成器的生态系统中,存在以下工具……
此议题中提到了多数推荐的改进措施;我将阐述 Docusaurus 1 中所存在的部分问题,以及在 Docusaurus 2 中的解决方式。
基础设施
内容
Docusaurus 1 站点实际上被构建为一系列静态 HTML 页面。 虽然使用了 React,但我们并未发挥出它所提供的所有特性, 如允许动态及交互页面的组件状态功能。 React was only used as a templating engine for static content and interactivity has to be added through script tags and dangerouslySetInnerHTML
😱.
此外,改变 Docusaurus 加载内容的方式较为困难。 举个例子,我们不支持原生添加如 Sass 及 Less 在内的 CSS 预处理器,这导致了用户添加自定义脚本的一些奇技淫巧。
For Docusaurus 2, we will be using webpack as a module bundler and we are changing the way we serve content. 添加 CSS 预处理器仅如添加一款 webpack 加载器一样容易。 Instead of a pure static HTML, during build time we will create a server-rendered version of the app and render the corresponding HTML. Docusaurus 网站将成为一款同构/通用的应用程序。 This approach is heavily inspired by Gatsby.
分版
If you have been using Docusaurus for a while, you might notice that Docusaurus creates versioned docs if and only if the docs content are different.
For example, if we have 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 !