Which semantic HTML tag for displaying side notes and admonitions?

Question

I am writing an online tutorial with sort of side notes or as they call it "admonitions" similar to those in Django tutorial: https://docs.djangoproject.com/en/dev/intro/tutorial01/ (I mean the the boxes with green a frame and a note icon).

Which HTML tag I should use to enclose such notes to add a semantic meaning of a note that may be useful to read at a given point of a tutorial, but is not part of the main tutorial flow?

Noteworthy, the tag must allow for enclosing block elements.

Answer 1

I believe the accepted answer is not quite correct. According to the HTML5 working draft, the <aside> element can be used to mark up side notes in certain, but not all cases:

1. <aside> is appropriate if the side note "could be considered separate from the content", for example background material on Switzerland in a much longer news story, or a pull quote in a longer article. (examples from W3C document)
2. <aside> is not appropriate if the side note is "a parenthetical". The W3C gives no examples of what it means. A narrow interpretation would be anything that is put in parentheses, between commas or between dashes.

If you want to interpret the W3C spec strictly, not all of the sidenotes in the Django tutorial can be marked up with <aside>. For example, the note titled "Doesn't match what you see?" could not really be considered separate from the content, since it does not make sense without the content next to it. Arguably, "Where should this code live?" is also not an <aside>, as it mentions "this code", which ties it to the content.

In my opinion, the W3C definition is unnecessarily confusing and restrictive. The dictionary definition of aside is "a temporary departure from a main theme or topic", and the spec should just stick to that, rather than introducing subtle distinctions. Of course, there is no reason why you can't use <aside> for all sidenotes, if it makes your code simpler. Think of it as civil disobedience. :)

---

Relevant quote:

The aside element represents a section of a page that consists of content that is tangentially related to the content around the aside element, and which could be considered separate from that content. Such sections are often represented as sidebars in printed typography.

The element can be used for typographical effects like pull quotes or sidebars, for advertising, for groups of nav elements, and for other content that is considered separate from the main content of the page.

Note: It's not appropriate to use the aside element just for parentheticals, since those are part of the main flow of the document.