Document 100% font size admonitions

[adamchainz]

Furo’s admonitions use a font size about 80% of the surrounding content. This decision was picked to try and avoid distracting users, quote #104 (comment):

It's essentially an opinionated design choice, and there's a knob for it too -- admonitions are supposed to be side content, something that's an aside from the regular text in the document. At the same size as the rest of the page, they look significantly more eye catching and distract the content's flow way more than I'd like.

I looked around and there seemed to be an even split in how they're handled, and I picked the approach that mkdocs-material takes on that front; since that's where I borrowed the admonitions' design from. :)

I prefer full-size admonitions, since they often contain important information for the reader, and I'm worried the smaller size de-emphasizes the text and leads readers to skip over it. I found the fix in that linked discussion:

html_theme_options = {
    "dark_css_variables": {
        "admonition-font-size": "100%",
        "admonition-title-font-size": "100%",
    },
    "light_css_variables": {
        "admonition-font-size": "100%",
        "admonition-title-font-size": "100%",
    },
}

Would it be acceptable to document this tweak? The docs don't currently cover admonition-font-size / admonition-title-font-size afaict. The only places I could find informatino on these variables were in the source code, that previous issue or this question.

[pradyunsg]

Yea, the docs don't list out the exact variables that you can use/override.

I guess we could improve the docs by listing those but that's a non-trivial endeavour.

I'm noticing that light/dark CSS variables also doesn't have a link to the sources (only colors does) so... that would be a good quick win as well.

[pradyunsg]

A PR doing any of these things would be welcome!

To err on the side of over communicating… let’s not do something that’ll require me to update the docs when I add more CSS variables. :)