Public service announcement: please do not use <blockquote>
(including by using the >
form in Markdown which creates a <blockquote>
) where you really mean some kind of admonition or callout. (This is the biggest accessibility consequence I can think of from Markdown’s limited vocabulary.) Use an actual admonition if your Markdown engine supports it, or custom HTML otherwise.
Why? Because people reading your site with assistive technology like VoiceOver will not see the visual presentation of your block quote (however much it looks like an admonition); they will simply hear it narrated as a quote. (Yes, people who need to use screen readers are used to working around that. No, that does not mean we should accept the status quo as “good enough”.)
For an example of appropriate HTML, you can do something like what I do for my website’s rendering of “Note” callouts, or check how GitHub renders its admonitions. For example, this note —
This is some content to which I would like to draw your attention!
— has this HTML:
<section class="note" aria-label="Note" aria-role="Note">
<p>This is some content to which I would like to draw your attention!</p>
</section>
aria-label
and aria-role
are good! Style it as you like; but don’t use blockquote
!
This little PSA was inspired by one particular blog I was just reading, but I am intentionally not mentioning which site: this is a general failure mode I see across many websites. Like I said: it falls out of Markdown’s limited vocabulary. Alas! But we can do better, even with the limitations of our tools.
If your Markdown engine does not support admonitions natively, and you find that extra HTML annoying to remember, see whether your blog engine lets you make a “shortcode” so you can create admonitions. I never write that out myself, because I do not remember the exact right set of attributes (I was always copying and pasting it!). I write this instead:
{% note %}
This is some content to which I would like to draw your attention!
{% endnote %}