跳转至主内容

Docusaurus 2020 回顾

· 5 分钟阅读
Sébastien Lorber

2020 was great for Docusaurus, despite a regrettable start and a tumultuous year for everyone.

我们不断对 Docusaurus 2 做出改良,其功能特性可与 Docusaurus 1 等量齐观

我们现在推荐您在新 Docusaurus 项目中使用 Docusaurus 2,同时鼓励 v1 版本的用户进行更新

We are still in alpha, but expect some good news very soon!

Docusaurus v1 vs v2 npm trends

Docusaurus 2 highlights

We have worked on many features this year, and would like to highlight the most significant ones:

  • i18n: easily translate your Docusaurus site, released soon! (预览文档
  • Version dropdown: enable contextual version switch
  • Versioning options: solving the most common pain-points users had with versioning
  • Contextual search: search in the current version, use the brand-new DocSearch 3 experience
  • Markdown pages: use Markdown instead of React components to create standalone pages
  • Better theme: various UI, UX and accessibility improvements
  • PWA: add offline support to your site, and make it installable
  • Fail-fast: strict config validation, detect broken links, and prevent bad production deployments
  • Multi-instance: use the docs plugin twice on a single site (e.g. iOS/Android SDK docs)
  • Migration CLI: automate the upgrade from Docusaurus 1
  • CodeSandbox: assess Docusaurus easily from your browser with new.docusaurus.io
  • Canary releases: use the @canary npm tag to use the upcoming release before anyone else
  • TypeScript: progressive adoption for internal code, and improve usage for users
  • Publish Infima: it is now open-source

Docusaurus 2 growth

The plan to rebuild Docusaurus from scratch in 2019 paid off: after a slow start, Docusaurus 2 has been widely adopted and has already outgrown Docusaurus 1 usage.

Docusaurus v1 vs v2 npm trends

知名项目、初创及大型企业和个人均采用了 Docusaurus 2(案例展示):

We helped large scale Docusaurus 1 sites to upgrade, ensuring a proper migration path and feature parity.

React Native was successfully upgraded to Docusaurus 2 (archived v1 site):

React Native screenshot

Localized Docusaurus 1 sites (like Jest) will be able to upgrade too:

Jest in Japanese screenshot

We also saw the first right-to-left Docusaurus 2 site published:

Datagit screenshot

GitHub 数据

  • Stars: 14632 -> 20946 (+43.2% y/y)
  • Total Contributors: 303 -> 512 (+68.9% y/y). Most of which are non-Facebook contributors
  • Weekly npm Downloads: 2356 -> 25592 (+986% y/y)
  • On GitHub, Docusaurus 1 is used by 6311 projects (+62.9% y/y) while Docusaurus 2 is used by 5039 projects (+1940% y/y)

Collaboration with Major League Hacking

We have welcomed Major League Hacking (MLH) fellows for 2 seasons already.

We are very thankful for the various contributions they made, such as:

  • Writing the foundations of the v1 to v2 migration CLI
  • Help migrate the React Native website from v1 to v2
  • Making the config validation more strict and exhaustive, returning helpful error messages
  • Adding CodeSandbox support
  • Improving the CI pipelines: build size and Lighthouse bots

We look forward to continuing this collaboration in 2021.

媒体

Dmitry Vinnik (Developer Advocate @ Facebook) explains Docusaurus in 60 seconds or 15min videos.

Rachel Nabors (Documentation Engineer @ Facebook) talked a bit about Docusaurus in React Native Radio 178 (podcast), and William Candillon the React Native website migration (video).

Many blog posts have been published:

社群

The Docusaurus community continues to grow, the Discord server is quite active, and Stack Overflow questions keep being posted.

Docusaurus 2 的模块化架构可让社群轻松构建并发布第三方插件。 As we would like to federate better our community, if you are building a plugin, please let us know.

何去何从?

As the core features of Docusaurus 2 have finally been built, we will be able to dedicate more time to solve the pain points and bugs reported by the community, and make Docusaurus stable and convenient enough to enter the beta and release-candidate phase.

With proper support for i18n and versioning, and large scale migrations such as React Native and Jest, we now have a clear migration path for all Docusaurus 1 sites.

We still have a few major features that we would like to work on:

Huge thanks to the community for their contributions in 2020, especially:

  • Joel Marcey for creating Docusaurus and supporting the project all this time
  • the core team - Alexey Pyltsyn, Sébastien Lorber, Yangshun Tay
  • the Major League Hacking and Facebook interns for their significant impact
  • the Algolia team for DocSearch 3 and their support
  • Bartosz Kaszubowski for his investment in the React Native migration
  • the whole community for their contributions, and providing support to each other

Cheers to a great 2021! 🎉