chore: upgrade syntax highlighting dependencies, prism-react-renderer to v2, react-live to v4

[harryzcy]

Breaking changes

Docusaurus v3 bumps 2 major dependencies related to code syntax highlighting

• prism-react-renderer v1 => v2
• react-live v2 => v4

prism-react-renderer v2

The prism-react-renderer v2 release notes are not super exhaustive, but there are 2 major changes to be aware of for Docusaurus users.

Theme API

The API for prism-react-renderer is changed. Previously, to import a theme, you would use const customTheme = require('prism-react-renderer/themes/<themeName>');.

But now, prism-react-renderer exports all themes as a single variable themes. So now you would import like the following:

import { themes } from "prism-react-renderer";
const customTheme = themes.github; // or other theme names

Default languages

Previously, react-prism-render included more languages by default: https://github.com/FormidableLabs/prism-react-renderer/blob/v1.3.5/src/vendor/prism/includeLangs.js

From v2+, less languages are included: https://github.com/FormidableLabs/prism-react-renderer/blob/prism-react-renderer%402.1.0/packages/generate-prism-languages/index.ts#L9

You may need to add the languages you need to the Docusaurus config:

const siteConfig = {
  themeConfig: {
    prism: {
      additionalLanguages: ["bash", "diff", "json"],
    }
  }
};

Reminder: the list of languages supported by prism: https://prismjs.com/#supported-languages

Note: make sure to restart the Docusaurus dev server after adding a language, or you'll get a console error: runtime~main.js:39 Uncaught Error: Cannot find module './prism-scss'

react-live v4

Docusaurus upgrades react-live from v2 to v4. This shouldn't affect much Docusaurus users but newer versions might have new useful features to check.

Major version release notes:

• v3: swap code transpiler from Bublé to Sucrase, swap internal editor
• v4: upgrade codebase to TypeScript

---

Motivation

Upgrade major code syntax highlighting libraries to be on newer versions and have access to latest features.

Some code blocks will have improved highlighting for free.

For example, on the Docusaurus websites our visual regression tests noticed those improvements: https://app.argos-ci.com/meta-open-source/docusaurus/builds/249

Test Plan

CI + visual tests

Test links

https://deploy-preview-9316--docusaurus-2.netlify.app/

Related issues/PRs

fix #8940

[netlify]

✅ [V2]

Name	Link
🔨 Latest commit	bcc6bdf
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/65203ceb78e37e0008f8eb68
😎 Deploy Preview	https://deploy-preview-9316--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[github-actions]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟠 73	🟢 97	🟢 92	🟢 100	🟠 89	Report
/docs/installation	🟠 72	🟢 98	🟢 92	🟢 100	🟠 89	Report

[slorber]

Thanks

That's a good idea to do this upgrade for Docusaurus v3

We'll also have to update the docs as well:

• https://docusaurus.io/docs/next/markdown-features/code-blocks
• https://docusaurus.io/docs/next/api/themes/configuration

We'll also want to upgrade react-live to avoid a duplicate prism version. React-Live v4 uses prism-react-renderer v2
https://github.com/FormidableLabs/react-live
Supersed this PR: #6589

Also we'll need some notes to explain users how to handle this breaking change. Can you write down some notes to explain what users should do when upgrading, and link to relevant external resources explaining breaking changes in depth?

Also related but apparently react-live upgrade breaks SSR support, and regression is still not fixed today (cf #6246 (comment)). Is it safe to upgrade or can it annoy our users? 🤷‍♂️ We need to study that. I think it should be fine because afaik we SSR a "loading..." placeholder for the preview, and bypass SSR for now.

[harryzcy]

Also we'll need some notes to explain users how to handle this breaking change. Can you write down some notes to explain what users should do when upgrading, and link to relevant external resources explaining breaking changes in depth?

@slorber where should this go?

[slorber]

Also we'll need some notes to explain users how to handle this breaking change. Can you write down some notes to explain what users should do when upgrading, and link to relevant external resources explaining breaking changes in depth?

@slorber where should this go?

I usually put a ## Breaking changes section at the top of each PR with some notes and external ref links.

This makes it easier to aggregate all those notes into the final v3.0 blog post on release. It doesn't have to be super polished but please note down things that we might have forgotten in a few weeks, and that Docusaurus users should be aware of when upgrading ;) Links to upgraded packages release notes and breaking change docs can be useful for example.

See for example PRs listed in v3 beta:
https://github.com/facebook/docusaurus/releases/tag/v3.0.0-beta.0

[slorber]

Apparently we have some pages that produce errors now 😅 site can't build in production mode.

Try:

• https://localhost:3000/tests/pages/markdown-tests-mdx
• https://localhost:3000/docs/markdown-features/code-blocks

[harryzcy]

I'll take another look. I can't reproduce it locally for some reason

Edit: reference: PrismJS/prism#1400 (comment)

[slorber]

Looks like we have weird hydrations issues here:
https://deploy-preview-9316--docusaurus-2.netlify.app/docs/docusaurus-core

[slorber]

I think this is the issue, we used the "vendored prism library" and should keep using it so passing a prism instance is not needed now. I'll remove it.

[slorber]

LGTM thanks 🎉 will be in Docusaurus v3