Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Upgrade Docusaurus from ^2.4.3 to ^3.0.0 #34

Closed
3 tasks done
Tracked by #32 ...
tukib opened this issue Nov 1, 2023 · 4 comments · Fixed by #37
Closed
3 tasks done
Tracked by #32 ...

Upgrade Docusaurus from ^2.4.3 to ^3.0.0 #34

tukib opened this issue Nov 1, 2023 · 4 comments · Fixed by #37
Assignees

Comments

@tukib
Copy link
Member

tukib commented Nov 1, 2023

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

This upgrade is:

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

Tasks

Future Work?

  • Use typescript files for configs

Footnotes

  1. Docusaurus v3 Announcement Announcing Docusaurus 3.0 -

@tukib tukib self-assigned this Nov 1, 2023
@tukib
Copy link
Member Author

tukib commented Nov 1, 2023

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 features12. 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 side3.

  • Support for additional Mermaid diagram types and async rendering.

Breaking Changes

Docusaurus handles most breaking changes internally1, 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 ❌)
  • 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

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

  3. Support React Server Components: docusaurus #9089 -

@seanmakesgames

This comment was marked as resolved.

@seanmakesgames

This comment was marked as resolved.

@tukib tukib changed the title Evaluate upgrade to Docusaurus v3 Upgrade Docusaurus from ^2.4.3 to ^3.0.0 Nov 3, 2023
@tukib tukib mentioned this issue Nov 3, 2023
8 tasks
@tukib

This comment was marked as resolved.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants