Admonitions in online documentation are eye-searingly hard to read

[ferdnyc]

The admonition blocks in the Meson documentation — which I see from examining the generated MarkDown are defined entirely by the docs build scripts, they're not a hotdoc feature — are downright unpleasant to read. In both the light and dark color schemes!

In the dark scheme, they glow far too brightly compared to the surrounding page, and white-on-orange/white-on-light-blue is not the most readable of color combinations:

Also, sometimes they are actually unreadable. Like, can you make out what the hyperlink text says in this Note?

The light theme is... not really any better, since it's largely ignored by the admonitions:

At least the link is more readable...

I assume the actual color choices come from the theme, IOW they're probably bootstrap(?) alert-info and alert-warning styles.

If so, I can only guess that those colors were not intended to be used the way they are (as background-colors over large amounts of text). Perhaps they were intended more the way admonition boxes are decorated in the default asciidoctor theme:

(Their theme uses incredibly similar colors for those two levels of admonition, in fact. Which makes it seem even more likely that's the case.)

[ferdnyc]

Aha! In fact, the colors were originally defined for buttons:

The alert.js plugin expands their use to alert message boxes, but with a text color that's derived from the alert color rather than forced to white. And they definitely don't put complex text with inline styling inside them. (TBH they're still kind of ugly, even in the Bootstrap docs:)

[xclaesse]

That theming probably comes from hotdoc. CC @MathieuDuponchelle

[ferdnyc]

@xclaesse

AFAICT, it does but it doesn't.

The .alert-{info,warning,emergency,etc...} styles come from the hotdoc_bootstrap_theme. It's entirely possible that's what's doing the "corrupting" of the colors (forcing the foreground color to #fff, which differs from the bootstrap defaults).

But hotdoc doesn't have any sort of admonition feature, and doesn't use those styles in its own content at all. They're being applied by custom HTML that's inserted by the refman generator, specifically from this template:

https://github.com/mesonbuild/meson/blob/00007e197ef7fa2c83fe8dcd4b9084afa5a7bb55/docs/refman/templates/notes.mustache#L1-L14

[ferdnyc]

(So my point is, I don't think hotdoc can really be blamed for Meson's documentation [ab]using its styles in incredibly ugly ways. :wink: )

[xclaesse]

Oh, I didn't know that CSS was from meson. Indeed hotdoc is not to blame then.

[ferdnyc]

@xclaesse (or anyone), any chance you could take a look at my PR for this, #13505? @jpakkane and @mensinda were review-requested as codeowners, but they haven't had a chance to review it yet. I won't claim it's perfect, but IMHO it's a LOT better. Compared to the above...

After (light/dark)