Replace all blockquote admonitions with the shortcode

[jdbaldry]

The admonition shortcode renders its content in a blockquote with consistent styling across the website.

I hope that this will also encourage future contributions to avoid blockquote notes and use the shortcode since it is common throughout the documentation.

[pstibrany]

I hope that this will also encourage future contributions to avoid blockquote notes and use the shortcode since it is common throughout the documentation.

Blockquote syntax is much more memorable (TIL that admonition term exists), can we please keep using it and let the tools handle the rendering?

[jdbaldry]

Blockquote syntax is much more memorable (TIL that admonition term exists), can we please keep using it and let the tools handle the rendering?

Mm, I do agree that it's easier to remember blockquote syntax.

The website squad maintains the HTML template for the admonition shortcode and ensures that it has consistent styling, and also proper semantic tags, and attributes for accessibility. Conversely, blockquotes with bold text are just blockquotes in the HTML output and are inconsistently used throughout the documentation.

Example of different usage I've seen in Mimir documentation (also present for tips, warnings, and cautions):

• Note: Capitalized first word

• NOTE: Capitalized first word

• Note: Capitalized first word

• NOTE: Capitalized first word

• Note: lower first word

• NOTE: lower first word

• Note: lower first word

• NOTE: lower first word

Unfortunately, there is no render hook in Hugo for blockquotes which means that the conversion cannot be done with Hugo alone -- gohugoio/hugo#7876.

Of course we could introduce a transpilation step in Mimir but I think that would be more awkward than using the shortcode.

[pstibrany]

Unblocking.

[jdbaldry]

Thanks for taking another look @pstibrany.

I don't want to introduce additional complexity where it is not wanted but I do feel that the admonition shortcode is better than blockquote conventions. Of course, if there is anything I can do to make this easier to use or any feedback I pass on to the website squad, let me know and I will happily do that.

It would be great to merge this sooner rather than later because of the risk of conflicts with changes across so many files.

[pstibrany]

It would be great to merge this sooner rather than later because of the risk of conflicts with changes across so many files.

Feel free to merge this. I see that there's too much complexity to make blockquotes "just work", so let's use "admonition" for now.

[jdbaldry]

Thanks Peter, I agree.

I'm not authorized to merge PRs because I'm no longer a member of @grafana/mimir-maintainers. Would you mind doing the honors? :)