9

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.

jan
  • 1,593
  • 2
  • 12
  • 15
  • Why XHTML? Well, perhaps I should specify at least HTML version - but would be nice to know a solution both for HTML4 and 5. – jan Sep 28 '11 at 08:25
  • because, as Ben Lee answered, xhtml doesn't have a semantic tag for this kind of content, where html5 does =) – Clement Herreman Sep 28 '11 at 09:51

2 Answers2

8

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.

Tomasz P. Szynalski
  • 377
  • 3
  • 8
  • Definitions of aside: "a comment or discussion that **does not relate directly** to the main subject being discussed" [merriam-webster](https://www.merriam-webster.com/dictionary/aside), and "a remark or story in a speech or text that is not part of the main subject" [Cambridge](https://dictionary.cambridge.org/us/dictionary/english/aside). I believe the HTML spec is very much in agreement with these authoritative definitions. – Inigo Apr 16 '20 at 21:26
  • It looks like recent versions of the [Django tutorial](https://docs.djangoproject.com/en/dev/intro/tutorial01/) don't have the referenced notes titled "Doesn't match what you see?" and "Where should this code live?". Here is a version that does: https://web.archive.org/web/20160211202857/https://docs.djangoproject.com/en/1.4/intro/tutorial01/ – Tyler Rick Apr 06 '21 at 00:37
4

In HTML5 (supported by all modern browsers), the tag is aside.

From http://www.whatwg.org/specs/web-apps/current-work/multipage/sections.html#the-aside-element:

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.

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

This is a block-level element and enclose anything a block-level element usually can (i.e. almost anything). It is essentially a "semantic div".

Ben Lee
  • 52,489
  • 13
  • 125
  • 145
  • 1
    A better description is in the [specification](http://www.whatwg.org/specs/web-apps/current-work/multipage/sections.html#the-aside-element) itself. Why read secondary remarks when the source is written so good? – Arsen7 Sep 28 '11 at 08:11
  • An admonition is a parenthetical, which as you quote in the answer is not an appropriate use of an `aside`, therefore this answer is wrong if one is trying to use HTML5 elements as they were intended. – Inigo Apr 15 '20 at 07:09
  • @Inigo I respectfully disagree with your assessment. You are referencing the quote "It's not appropriate to use the aside element just for parentheticals, since those are part of the main flow of the document." However the OP specifically said that they are looking for a semantic element for "a note that may be useful to read at a given point of a tutorial, but is not part of the main tutorial flow". That is what "aside" is for. It's not part of the main content flow. – Ben Lee Apr 16 '20 at 20:31
  • @BenLee Look at what the Django admonition examples in the OP links to. They can't "be considered separate from that content" (quote from the HTML spec) because they can't stand on their own -- the are parentheticals insertions related to the immediately surrounding content. They are part of the flow because their positions in the surrounding content are important, not arbitrary; You can't just move them elsewhere. Think of a Warning admonition in any documentation: It's position in the flow matters extremely. See [the answer with more votes](https://stackoverflow.com/a/8297157/8910547). – Inigo Apr 16 '20 at 21:19
  • The linked example does not match what the OP was describing, so there is an inconsistency there. – Ben Lee Apr 17 '20 at 00:25