[RFC] Differenciate "caution" admonitions

[smnandre]

TLDR: Way too much text to suggest two things :

• differenciate "caution" depending on the level (or soften the "red")
• minor CSS adaptations on mobile (see the screenshots at the end)

---

While reading the bundle docs, I felt a bit... "attacked" (big quotes around, I'm all right haha..) This is a minor topic. But even on an tiny tiny level, i think there may be something there to improve easily.

Why "attacked" ? As the perfect human beeing i am (**cough**), when it's red, in my head i understand "this is a danger, a risk and i must read this right now".

It was neither a danger, neither something i had to read. And when it happens a lot, i really feel patronized / yelled at.

So maybe a softer red could be used (see suggestions at the end of this message), or ....

Differenciate DANGER and... ??

I think there is a semantic difference between "danger/alert/caution" and "warning"(?).

To illustrate, the following blocs should be (in my mind) on two really different levels of importance.

Profiler	Bundles

We had a similar discussion recently on the UX repository about the UX packages docs. I was not keen to display a big red/caution block to give an information. But that information was a pretty highly important one.

So i suggest to differenciate CAUTION either by

• introducing a lower level
• introducting a higher level

But in both case i don't find the "perfect word" for it.

Style on mobile

On mobile, i find the admonition-* blocks really large. Maybe some small modifications could be made to ease the reading:

• remove the margin-bottom after the title
• diminish the font-size (as it's done for the "since-version" blocks)
• use a smaller border-width (2px currently)

See how it compares in the following before/after table.

Suggestion

Here a 3 screens to visualise what those ideas could render

-	Profiler	Bundles	Content
Before
After

[OskarStark]

cc @javiereguiluz

[wouterj]

ReStructuredText comes with a .. caution:: and .. danger:: admonition that we currently use as aliases, we might want to differentiate between them?

[smnandre]

I do think "data integrity" and "security" (in a broad meaning) deserve to be separated from the rest.

But if you people do not think it's worth it i'm fine with it.

I'll list all those "gray area" admonitions and we may discuss the "not-obvious" ones, maybe write a sort of "rule" down ?

[smnandre]

Well Github now does the same move: https://github.blog/changelog/2023-12-14-new-markdown-extension-alerts-provide-distinctive-styling-for-significant-content/

[javiereguiluz]

Yes, I think this change makes sense. As Wouter said, RST gives us danger in addition to caution. So, let's demote caution to warning messages and let's add danger for truly dangerous problems.

What Simon said is a good way to decide which one to use: "data integrity or security" issues --> danger; anything else --> caution.

The map from GitHub admonitions would be:

GitHub	Us
note	.. note::
tip	.. tip::
important	(none)
warning	.. caution::
caution	.. danger::

Next steps?

• (Someone) Check if https://github.com/symfony-tools/docs-builder needs to do some change for this
• (Me) Change the current styles of caution and make them orange/yellow and add a new danger style with the same styles as the current caution styles
• (Community) Review all Symfony Docs and change some .. caution:: directives to .. danger::

Anything else?

[smnandre]

I'm having a look at docs-builder

[alexandre-daubois]

I'm having a look at cautions in the overall docs repo to change some to danger.

[smnandre]

Here are some suggestions for the danger icon (from tabler)

Currently the danger are rendered as caution, so we'll need to check the doc for them too (cc @alexandre-daubois )

[alexandre-daubois]

Got it, thank you for letting me know!

[smnandre]

@javiereguiluz the only thing that'd need to change i think is the LEVEL => ICON mapping in src/Templates/default/html/directives/admonition.html.twig

I can open a PR and add a test with a new expected / source block for danger if you want ?

[smnandre]

source	border	title	icon
tip	#059669	#10b981	#047857
warning	#d97706	#f59e0b	#b45309
caution	#db2777	#ec4899	#be185d

(don't mind me i just discovered we can show colors in github's markdown)

[javiereguiluz]

Let's close this one as fixed.

We did an amazing team work here 💪

• Updated the directives in Symfony Docs Builder: Add directive test for admonition/danger symfony-tools/docs-builder#169
• Tagged a new version and deployed to production
• Tweaked some caution/danger directives in docs: Mutate some cautions to dangers #19305
• Rebuilt the docs in production
• Done!

E.g.

• The profiler page now displays the danger admonition: https://symfony.com/doc/current/profiler.html
• The bundle article no longer displays the danger admonition; instead, it displays the new caution design: https://symfony.com/doc/current/bundles.html

Thanks!

[smnandre]

Thank you all 😃