feat: Add basic styling to Alerts in the HTML exporter

[nathanlesage]

This PR contains the style changes I pulled out of #11836. See that PR for context.

EDIT: I just saw that this thing also includes the two changes from the other branch because I drafted this branch from the other one. I suspect we can first merge #11836 and then I can update this branch from main and get rid of the changes to the Markdown parser.

[nathanlesage]

It seems to have worked — the only changes currently showing in the diff are the three HTML files. Sorry again, and thanks for your help @jgm.

[jgm]

If you rebase against main and force push, you'll get a clean commit with just the style changes.

[nathanlesage]

So, that took a while, which is quite embarassing, but at least now I know what to do in such cases in the future… the branch is now clean and ready for review. Sorry about the hiccups.

[jgm]

Can you paste a screenshot that shows how these look with this CSS?

Also, if we do this, it might make sense to gate the inclusion of the CSS for alerts under a template variable which would be set automatically by the writer if there are actually alerts present. This keeps the size down for other cases.

My main reservation so far is that we don't do automatic styling of these in other formats; our thought was that there are too many ways to do it, so we wanted to leave it to users to handle with filters etc. However, in HTML everything can be done with CSS, so perhaps this is an exception.

[nathanlesage]

Can you paste a screenshot that shows how these look with this CSS?

Sure, here you go:

Also, if we do this, it might make sense to gate the inclusion of the CSS for alerts under a template variable which would be set automatically by the writer if there are actually alerts present. This keeps the size down for other cases.

I had the same thought, but couldn't find a variable that is being set in the metadata when there are alerts in the file. Is there one? If not, should I see if I can add one in the Markdown reader?

My main reservation so far is that we don't do automatic styling of these in other formats; our thought was that there are too many ways to do it, so we wanted to leave it to users to handle with filters etc. However, in HTML everything can be done with CSS, so perhaps this is an exception.

I absolutely agree that styling, especially in this case, is very opiniated and people may disagree on the styles. However, I decided to propose this styling for two reasons: (a) if someone actually uses alerts, they would currently not actually see any alerts because they are not at all styled. I would argue that it is more user-friendly to just provide some default styles but make it simple to change them. I figure that many Pandoc users want just some working default styles, especially now that Pandoc is established in a lot of tools where people don't necessarily want to or know how to customize exports. And (b) that's why it's very easy with Pandoc HTML templates to override these styles if people prefer, so I fathom it wouldn't be detrimental to anyone who dislikes these defaults.

---

Regarding other export profiles: I was actually considering adding something like that for at least PDF and Word exports, too, but at least for PDFs that would necessitate a change to the writer, since it would require custom LaTeX code to be emitted. Again, I do think that if some syntax is detected and properly parsed, it seems odd if the resulting code is not at all styled, even if it can be overwritten.

[jgm]

I had the same thought, but couldn't find a variable that is being set in the metadata when there are alerts in the file. Is there one? If not, should I see if I can add one in the Markdown reader?

We would have to add code to the HTML writer that sets this variable if the document contains admonitions. Probably we'd need to add a field in the writer state that tracks this, and set it when we hit admonitions. Then in the main function we'd check this state variable and set the template variable accordingly. There are probably already some examples of things like this in the HTML writer.

[jgm]

I wonder if it would make sense to style them more like the GitHub default:

I believe the icons could even be inserted via CSS.