fix(theme): make warning a first-class admonition, and deprecate caution admonition

[slorber]

Breaking change

• The undocumented :::warning admonition becomes yellow instead of red, like most users expect
• :::warning is now a first-class official admonition keyword
• :::caution is deprecated in v3 and will be removed in v4

Motivation

Fix #7558

:::warning should render as:

Instead of:

Note :::warning used to be a legacy admonition alias that we didn't even document in the very first v2.0.0 (see docs).

Now :::warning becomes a first-class official admonition keyword.

It replaces the :::caution admonition keyword that keeps working in v3 but will be removed in v4 as part of #9307

Test Plan

Preview

Test links

https://deploy-preview-9308--docusaurus-2.netlify.app/tests/docs/tests/admonitions

[netlify]

✅ [V2]

Name	Link
🔨 Latest commit	3f6dd84
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/650334f70d7afa0008983192
😎 Deploy Preview	https://deploy-preview-9308--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
/	🟠 62	🟢 97	🟢 92	🟢 100	🟠 89	Report
/docs/installation	🟠 81	🟢 98	🟢 92	🟢 100	🟠 89	Report

[github-actions]

Size Change: 0 B

Total Size: 1.11 MB

ℹ️ View Unchanged

Filename	Size
website/.docusaurus/globalData.json	117 kB
website/build/assets/css/styles.********.css	113 kB
website/build/assets/js/main.********.js	836 kB
website/build/index.html	41.4 kB

_{compressed-size-action}

[Josh-Cena]

Can we emit a warning server-side (and/or in dev mode) each time a deprecated type is used?

[slorber]

Can we emit a warning server-side (and/or in dev mode) each time a deprecated type is used?

Yes but I'll do that later as I don't want users to be overwhelmed by the v3.0 upgrade immediately

[Josh-Cena]

Fair enough. We can emit warnings later

[Josh-Cena]

Fair enough. We can emit warnings later

[boevski]

Would you guys consider keeping both in v4? Both warning and caution have their place in writing, especially in some industries. There are plenty of discussions online explaining what the difference is between them.

[slorber]

@boevski please comment on this issue instead: #9307

Make sure provide an exhaustive list of arguments and reference links to convince us it's worth it to keep caution, because a simple GitHub comment/claim is not enough to act on for us.