Skip to main content

Announcing Docusaurus 2 Beta

· 4 min read
Sébastien Lorber
Sébastien Lorber
Docusaurus maintainer, This Week In React editor
Joel Marcey
Joel Marcey
Developer Advocate at Meta
Yangshun Tay
Yangshun Tay
Front End Engineer at Meta
Alexey Pyltsyn
Alexey Pyltsyn
Open-source enthusiast

After a lengthy alpha stage in order to ensure feature parity and quality, we are excited to officially release the first Docusaurus 2 beta.

With the announcement of this beta, the team is even more confident that Docusaurus 2 is ready for mainstream adoption!

Docusaurus adoption​

Don't fear the beta tag!

Docusaurus 2 is widely adopted and growing fast:

Docusaurus v1 vs. v2 npm trends from 2019 to mid 2021. The installations of Docusaurus v2 is sharply rising, while v1 is mostly stable. V1 fluctuates between 10000 and 20000, while v2 starts at 0 and ends at almost 60000. The intersection happens around June 2020.

To get a fuller understanding of the quality of current Docusaurus 2 sites, our new showcase page allows you to filter Docusaurus sites by features, so you may get inspired by real-world production sites with a similar use-case as yours!

Don't miss our favorite sites; they all stand out with something unique:

A screenshot of the showcase's favorites section, with 12 cards each displaying the information and preview of one site

Why was Docusaurus v2 in alpha for so long?​

It's hard to believe that the first alpha release v2.0.0-alpha.0 was 2 years ago 😳 , unusually long for a software alpha.

As this was a substantial re-architecture of the code base, we wanted to ensure that we had confidence in the stability and features of Docusaurus 2 before moving on to a beta stage, since beta suggests a high level of quality. We are happy to say that Docusaurus 2 has reached feature parity with Docusaurus 1 with i18n, and it has been successfully adopted by many Docusaurus sites (see i18n showcase).

We're now quite confident that the core features of Docusaurus 2 are stable enough to be in beta.

What are the goals of the beta?​

Now that Docusaurus 2 is stable and major feature complete, the goal of the beta is to inspire confidence in new users on the production-readiness of Docusaurus 2, migrate more remaining Docusaurus 1 users to version 2, and officially deprecate Docusaurus 1. We will, of course, continue to resolve any issues and bugs that may be discovered.

In addition, we will use the beta phase to improve our theming system.

We want to make it:

  • easier to implement a custom theme, including for ourselves. We want to provide multiple official themes (including Tailwind CSS) for a long time.

  • safer to extend an existing theme: it can be painful to upgrade a highly customized Docusaurus site, as customizations can conflict with internal changes. We need to make the theme public API surface more explicit, and make it clear what is safe to customize.

We will build a better theming infrastructure and refactor the classic theme to use it.

If you customize your site, you may find these planned improvements quite valuable.

What's new?​

In case you missed it, we recently shipped two major improvements:

What's next?​

Shipping the official 2.0 release!

To get there, we will continue to fix bugs and implement the most wanted features, including:

Conclusion​

This is an exciting time for Docusaurus.

We are inspired by the positive feedback about Docusaurus, and discover new sites online every single day.

We are so excited for this beta release. We strove for quality and stability while continuing to try to increase the adoption of Docusaurus. For those that have been on the fence from migrating an existing Docusaurus site to Docusaurus 2, it is a great time to upgrade. We want you running on the latest infrastructure when we deprecate Docusaurus 1 at the end of this beta period. Let us know how we can help.

Thank you to everyone for reading and to the entire community who supports Docusaurus. 🤗