Upgrade Docusaurus from ^2.4.3 to ^3.0.0

[tukib]

Upgrade Proposal

Docusaurus v3 now has a stable release. The version we use, Docusaurus v2, has entered maintenance mode for major security issues, and will be deprecated after 31 January 2024¹.

This upgrade is:

• required for security.
• advantageous for new features & improvements.

Tasks

• Dependency Upgrade Policy #35
• Upgrade proposal assessed and in line with policy.
• Upgrade to Docusaurus v3 #37

Future Work?

• Use typescript files for configs

Footnotes

1. Docusaurus v3 Announcement Announcing Docusaurus 3.0 - ↩

[tukib]

While reading the announcement to define the problem, I noted down the features and breaking changes that I thought were relevant, and would make a good base for discussion and evaluating the decision to upgrade.

New Features

In addition to the bug fixes and performance improvements that Docusaurus v3 implements, the new release enables several new features¹². Some of note are:

• Defining custom directives such as :textDirective, ::leafDirective, and :::containerDirective.

• Docusaurus configuration with ESM or TypeScript for better DX (site config, docs sidebar, plugins and presets).

• Unlisted page option, making them uncrawlable. This supplements the existing draft page option which excludes pages from production builds.

• Building the site in dev mode, making debugging easier without relying on the live development script.

• Additional linting rules such as catching usage of <a> instead of Docusaurus <Link>.

• Benefits that come with React v18 such as new/upcoming features and performance improvements. For example, React Server Components will bring a substantial improvement to bundle size and page load times, which the Docusaurus team can implement on their side³.

• Support for additional Mermaid diagram types and async rendering.

Breaking Changes

Docusaurus handles most breaking changes internally¹, for our usage of it we only need to consider:

• #9189: new default blog RSS feed limit of 20 entries
• #9308: fix and re-introduce the :::warning admonition, deprecate :::caution
• #9310: remove the legacy versioned sidebar id prefix, used for sites versioned before v2.0.0-beta.10 (December 2021)
• #7966: refactor docs theme components, eventually requiring to you re-swizzle them

I do not believe any of those four items applies to us?

Regarding the remaining breaking changes of our direct dependencies:

• Node.js v16 -> v18 (ours: v20 ✅)
• React v17 -> v18 (ours: v17 ❌)
  • We have very few (if any) custom react components to consider, so this is unlikely to be an issue.
  • Migration Guide: React 18 Upgrade Guide
• MDX v1 -> v3 (ours: v1 ❌)
  • We have not populated this wiki with many pages yet, making now the best time to migrate if we choose to upgrade.
  • The overall format for documents is unchanged.
  • Migration Guides:
    • Migrating from v1 to v2
    • Migrating from v2 to v3
• TypeScript v4 -> v5 (ours: v5 ✅)

There were several other changes we do not explicitly depend on:

• prism-react-renderer v1 -> v2
• react-live v2 -> v4
• Mermaid v9 -> v10
• import-fresh v3 -> jiti v1
• remark-emoji v2 -> v4

Footnotes

1. Docusaurus v3 Announcement Announcing Docusaurus 3.0 - ↩ ↩²

2. Docusaurus v3 release notes: 3.0.0 (2023-10-31) - ↩

3. Support React Server Components: docusaurus #9089 - ↩