3.0.0-beta.0

[slorber]

3.0.0-beta.0 (2023-09-15)

Docusaurus v3 is now used by at least 3 major sites: Docusaurus, Jest and React-Native.

We fixed all the tiny issues encountered during that process.

This is now time to move v3 to the beta stage!

Main changes

Docusaurus v3 is mostly an infrastructure upgrade, notably:

• MDX 2
• React 18
• TS 5
• Mermaid 10

There are other "functional" breaking changes that should be relatively easy to handle.

The UI should mostly remain unchanged from the latest v2.x release.

New features coming with v3 will be presented later during the final release.

Example upgrade PRs:

Use these PRs as inspiration to figure out what it takes to upgrade to v3:

• React-Native v3 upgrade PR: Upgrade React-Native website to Docusaurus v3 react-native-website#3780
• Jest v3 upgrade PR: Upgrade Jest website to Docusaurus v3 jestjs/jest#14463

Release links

• GitHub discussions: 3.0.0-beta.0 #9312
• GitHub release: https://github.com/facebook/docusaurus/releases/tag/v3.0.0-beta.0
• Docs PR: chore: v3.0.0-beta.0 release #9311
• Tweet: https://twitter.com/sebastienlorber/status/1702742311514275978

Breaking changes

MDX v2 is the most annoying breaking change of Docusaurus v3: it will likely require you to update a few md/mdx files to ensure they still compile fine. Read the dedicated MDX v2 PR for more details.

Notably, characters such as { and < will likely raise new MDX compilation errors. The MDX v2 playground is your new best friend to troubleshoot these issues.

We also created a dedicated support discussion: MDX v2 - Upgrade Support

A cli will be introduced soon. It should provide a convenient way to detect which of your docs will fail to compile under MDX v2. You can run npx docusaurus-mdx-checker to have a preview.

💥 Breaking Change

• docusaurus-plugin-content-docs, docusaurus-theme-classic
  • #9310 chore(plugin-docs): remove legacy versioned prefix on doc ids and sidebar names in versioned sidebars (@slorber)
• docusaurus-theme-classic, docusaurus-theme-translations
  • #9308 fix(theme): make warning a first-class admonition, and deprecate caution admonition (@slorber)
• docusaurus-theme-common, docusaurus-theme-live-codeblock, docusaurus-theme-mermaid
  • #9305 feat(theme-mermaid): upgrade Mermaid to v10.4 - handle async rendering (@slorber)
• create-docusaurus, docusaurus-plugin-content-docs, docusaurus-plugin-debug, docusaurus-plugin-google-analytics, docusaurus-plugin-google-gtag, docusaurus-plugin-google-tag-manager, docusaurus-plugin-ideal-image, docusaurus-plugin-pwa, docusaurus-theme-classic, docusaurus-theme-common, docusaurus-theme-live-codeblock, docusaurus-theme-mermaid, docusaurus-theme-search-algolia, docusaurus-tsconfig, docusaurus
  • #9258 feat: Docusaurus v3 upgrades and require TypeScript 5 (@slorber)
• docusaurus-plugin-content-blog
  • #9189 feat(blog-plugin): limit option for blog feedOptions (@johnnyreilly)
• create-docusaurus, docusaurus-tsconfig
  • #9050 feat: create official TypeScript base config @docusaurus/tsconfig (@slorber)
• create-docusaurus, docusaurus-mdx-loader, docusaurus-module-type-aliases, docusaurus-plugin-client-redirects, docusaurus-plugin-content-blog, docusaurus-plugin-content-docs, docusaurus-plugin-content-pages, docusaurus-plugin-debug, docusaurus-plugin-google-analytics, docusaurus-plugin-google-gtag, docusaurus-plugin-google-tag-manager, docusaurus-plugin-ideal-image, docusaurus-plugin-pwa, docusaurus-plugin-sitemap, docusaurus-preset-classic, docusaurus-theme-classic, docusaurus-theme-common, docusaurus-theme-live-codeblock, docusaurus-theme-mermaid, docusaurus-theme-search-algolia, docusaurus-types, docusaurus
  • #8961 feat: React 18 + automatic JSX runtime + build --dev (@slorber)
• create-docusaurus
  • #9026 chore: remove facebook template (@slorber)
• create-docusaurus, docusaurus-mdx-loader, docusaurus-migrate, docusaurus-plugin-content-blog, docusaurus-remark-plugin-npm2yarn, docusaurus-theme-classic, docusaurus-theme-common, docusaurus-theme-mermaid, docusaurus-types, docusaurus-utils-validation, docusaurus-utils, docusaurus
  • #8288 feat: upgrade to MDX v2 (@slorber)
• docusaurus-plugin-content-docs, docusaurus-theme-classic, docusaurus-theme-common, docusaurus
  • #7966 fix(plugin-docs,theme): refactor docs plugin routes and component tree (@slorber)

---

This discussion was created from the release 3.0.0-beta.0.