---
title: Announcing Docusaurus 2 Beta
authors:
  - key: slorber
    image_url: ./img/slorber.png
  - JMarcey
  - yangshun
  - lex111

tags: [release, beta]
image: ./img/social-card.png
---

After a lengthy alpha stage in order to ensure feature parity and quality, we are excited to officially release the first **[Docusaurus 2 beta](https://github.com/facebook/docusaurus/releases/tag/v2.0.0-beta.0)**.

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

![](./img/image_cropped.png)

<!--truncate-->

## 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.](./img/trend.png)](https://www.npmtrends.com/docusaurus-vs-@docusaurus/core)

To get a fuller understanding of the quality of current Docusaurus 2 sites, our new [showcase](https://docusaurus.io/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](https://docusaurus.io/showcase?tags=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](./img/favorites.png)](https://docusaurus.io/showcase?tags=favorite)

## Why was Docusaurus v2 in alpha for so long?

It's hard to believe that the first alpha release [v2.0.0-alpha.0](https://github.com/facebook/docusaurus/releases/tag/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](https://docusaurus.io/blog/2021/03/09/releasing-docusaurus-i18n)**, and it has been **successfully adopted** by many Docusaurus sites (see [i18n showcase](https://docusaurus.io/showcase?tags=i18n)).

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](https://github.com/facebook/docusaurus/issues/3522) (including [Tailwind CSS](https://github.com/facebook/docusaurus/issues/2961)) 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](https://docusaurus.io/docs/sidebar#sidebar-item-autogenerated): no need to maintain a `sidebars.js` file anymore!
- [Webpack 5 / PostCSS 8](https://github.com/facebook/docusaurus/issues/4027): 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:

- [Sidebar category index pages](https://github.com/facebook/docusaurus/issues/2643)
- [Better mobile navigation UX](https://github.com/facebook/docusaurus/issues/2220)
- [Better admonition design](https://github.com/facebookincubator/infima/issues/55)
- [CSS-in-JS support](https://github.com/facebook/docusaurus/issues/3236)
- [Improve build time performance](https://github.com/facebook/docusaurus/issues/4765)
- [Extend Docusaurus plugins, CMS integration](https://github.com/facebook/docusaurus/issues/4138)
- [Fix trailing slashes and relative link issues](https://github.com/facebook/docusaurus/issues/3372)
- [Better compatibility with CommonMark](https://github.com/facebook/docusaurus/issues/3018)
- [Upgrade to MDX 2.0](https://github.com/facebook/docusaurus/issues/4029)

## Conclusion

This is an exciting time for Docusaurus.

We are inspired by the [positive feedback](https://twitter.com/sebastienlorber/timelines/1392048416872706049) 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. 🤗
