Markdown Template / style like "read the docs" for documents

Instead of

<div class="important">

### Important

First paragraph

Second paragraph

</div>

use

<aside>

# Important

first paragraph

second paragraph
…
</aside>

<div> has no semantics, so the blocks (“Important”, “Notification”, whatever) are considered to be semantically part of the normal text flow. Which they are not (why else would one want them to stand out this much?). Everything you need to know (as usual in this context) is at MDN:

This is relevant for several reasons:

• A h3 element without a preceding h2 is not considered semantically correct
• A screen reader might (I don’t know, though) just read out the “Important” div like any other text, which could be irritating

Also, I was wrong in assuming that one could use any heading in an aside element: The W3C examples use an h1 here, so I have modified the MD accordingly. CSS should also be modified to address h1 instead of h3 in this case.

https://www.w3.org/TR/2011/WD-html5-author-20110809/the-aside-element.html