Announcing Docusaurus 2 Beta

May 12, 2021 · 4 min read

Sébastien Lorber

Docusaurus maintainer

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 beta party

Docusaurus adoption#

Don't fear the beta tag!

Docusaurus 2 is widely adopted and growing fast:

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:

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:

Auto-generated sidebars: no need to maintain a sidebars.js file anymore!
Webpack 5 / PostCSS 8: persistent caching significantly speeds up rebuild time!

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. 🤗