Update docusaurus and use v4 future

[liuxingbaoyu]

This PR can be reviewed commit by commit.
This PR used codex to help me perform batch replacements.

[netlify]

👷 Deploy request for babel-next pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	082941c

[netlify]

✅ Deploy Preview for babel ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	082941c
🔍 Latest deploy log	https://app.netlify.com/projects/babel/deploys/69f05885278e320008afd574
😎 Deploy Preview	https://deploy-preview-3195--babel.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 project configuration.

[liuxingbaoyu]

The default browser target will convert the default CSS to :root:not(#\#):not(#\#) {...}, which means that custom CSS cannot override them without modification.
@slorber This might be a common issue with useCssCascadeLayers, and you might be interested in it. :)

[JLHwung]

Do we already have latest caniuse-lite in the lock file? Chances are defaults already supports css-cascade-layers but the definition of defaults in the lock file lags behind.

[liuxingbaoyu]

You're right! After my update, defaults is now supported.

[slorber]

:not(#\#) is a way for postCSS to downgrade CSS cascade layers to "older CSS". Technically each :not(#\#) helps increase the selector specificity.

CSS Cascade layers are well supported now, however if you need to downgrade and keep your CSS overrides, I'd recommend adding a layer to your site's custom CSS so that :not(#\#) is also added to your own CSS so that it gets a higher specificity.

But yeah, if it's in defaults it's just simpler to upgrade.

[liuxingbaoyu]

Thanks!

[slorber]

Hey 👋

TLDR: I think you should break this PR into multiple smaller ones that focus on a single thing at a time. This makes it easier to review/merge, and it helps me helps you if you need.

---

v3.10 doesn't ship any breaking change, it's only if you use our v4 "future flags" that you opt in into future breaking changes purposefully. One strategy could be to opt in to each breaking change in an individual PR that focuses on a single change at a time.

Note that you do not need to migrate all your files to .mdx, it's just a recommendation. Also, Docusaurus v4 will preserve compatibility options with MDX v1, so you don't really need to change/rename all your MDX files in this PR as part of the upgrade.

My suggestion would be:

• upgrade to v3.10 only, no breaking change

Optional:

• enable v4.useCssCascadeLayers, fix possible CSS issues
• disable siteConfig.markdown.mdx1Compat individual options one by one in separate PRs (migrate to admonition directives, mdx comments, mdx heading ids in separate focused PRs)
• rename all extensions/links to .mdx (unless you purposefully want to use CommonMark for some docs)
• enable v4: true if you have successfully handled all the individual v4 future flags