Docs: add/unify advice on contextual colors and accessibility

[patrickhlauke]

• add callout warning about conveying meaning to assistive technologies when using color modifiers
• use more generalised callout text where already present

[cvrebert]

Perhaps we could use Jekyll's include directive rather than having the same text copypasta'd in multiple places?

[patrickhlauke]

Don't know anything about Jekyll, but this http://wolfslittlestore.be/2013/10/rendering-markdown-in-jekyll/ seems to put a spanner in the works unless the fragment's already in HTML?

[cvrebert]

We're already using custom Jekyll plugins, so we might as well add the one from the post you linked to.

[patrickhlauke]

I'll need somebody to either give me some massive pointers...or do it before I break everything ;) (i.e. grunt and co are a complete black box mystery to me, sadly)

[cvrebert]

I'll take a crack at the Jekyll plugin.

[patrickhlauke]

i had a few attempts at doing the jekyll plugin thing. however, it ended up giving me all sorts of annoying side effects (like complaining about %endmarkdown in the getting started download.md file), and needed to be unnecessarily hacked (to make sure the includes were grabbed explicitly from docs/_includes). decided to go the slightly more wordy, but perfectly legit route of

{% capture my-include %}{% include test.md %}{% endcapture %}
{{ my-include | markdownify }}

instead. closing this in favor of the successor PR #19255