Remove legacy admonition keywords

[slorber]

Have you read the Contributing Guidelines on issues?

• [X] I have read the Contributing Guidelines on issues.

Motivation

We historically have admonition keyword "aliases" that we don't even document since v2.0.

Those came from an old v2 dependency: https://github.com/elviswolcott/remark-admonitions

In Docusaurus v4 is time to remove them officially and throw an error for sites that still use them.

Note: in Docusaurus v3 we made :::warning the official admonition, and :::caution an alias to remove in v4 (see https://github.com/facebook/docusaurus/issues/7558)

EDIT: maybe we should have some kind of siteConfig.markdown.admonitions config and probably let users define their own set of directive/icon/color/label without requiring swizzling anything?

Self-service

• [X] I'd be willing to do some initial work on this proposal myself.

[tats-u]

FYI AsciiDoc uses both warning and caution.

https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/

Caution vs. Warning

When choosing the admonition type, you may find yourself getting confused between "caution" and "warning" as these words are often used interchangeably. Here’s a simple rule to help you differentiate the two:

• Use CAUTION to advise the reader to act carefully (i.e., exercise care).
• Use WARNING to inform the reader of danger, harm, or consequences that exist.

To find a deeper analysis, see www.differencebetween.com/difference-between-caution-and-vs-warning/.

In the distant future, it would be nice if a remark-compatible AsciiDoc parser would appear and get supported by Docusaurus. (This is just my personal ideal though)

[tats-u]

I have no authority but I believe manuals of many (physical) products use both cautions and warnings.

From: https://www.muirgraphics.com/2016/08/difference-life-death-choosing-right-safety-signal-words/

From: http://www.overheadlifting.org/understanding-safety-signs-and-overhead-lifting-equipment-hazards/

I'd like to and I believe we can use both in software manuals depending on severity, too.

Or do you want us to substitute :::warning Caution for the current :::caution?

[slorber]

I guess we could keep it, as long as the color/icon is consistent with what users could expect

If we look at our legacy admonition aliases, some are really off (success with a lightbulb? important blue? wtf is secondary? 🤔 ) but caution still kinda makes sense

[tats-u]

If we keep caution, we should adjust the hues of "warning" and "caution" because they share the same icon ⚠; "warning" should be closer to red and "caution" can be closer to yellow.

success

If we could keep it, we'll have to change the icon from 💡 to ✔ at least.

important

A warm color could be better, but I don't know what color is best (possibly non-warm color). At lease the current aqua seems different from what I want "important" admonition to be,

secondary

I don't know how and where I should use it instead of the others.

[Josh-Cena]

success, important, and secondary are not semantic names—they are leaks of abstraction from the theme color names of the Infima styles. Namely, Infima defines --ifm-color-secondary, --ifm-color-success, etc., which are the colors used by these admonitions.

[tats-u]

https://infima.dev/docs/components/alert Infima means this, right? That's why every variable name starts with ifm.

I guess we have no choice but to follow these classifications...

• secondary → note
• success → tip

For caution, it seems the best to treat it as an alias for warning. I'll recommend readers of our documents to write :::warning caution instead when I have a time.

[connorjs]

Just FYI - GitHub has Note, Tip, Important, Warning, and Caution for their alerts: https://github.blog/changelog/2023-12-14-new-markdown-extension-alerts-provide-distinctive-styling-for-significant-content/.

This matches the Microsoft Learn alerts: https://learn.microsoft.com/en-us/contribute/content/markdown-reference#alerts-note-tip-important-caution-warning

No official request to keep; just sharing data points as I came across this.

[boevski]

One more vote for keeping both Warning and Caution. Providing config options instead of swizzling sounds like the cherry on top, but even if we have that, Warning and Caution should be part of the default options IMHO.

In general, Warning is tied to physical danger. Caution is of similar weight, suggesting things could go very wrong, but without any direct risk of physical injury.

Cisco, for one, uses both in its documentation. VMware, being a pure software company, guides for using Caution exclusively. These are two examples of companies I've worked at.