Search code examples
htmloutline

HTML 5 outlines: why do these two examples generate a different outline?

I wonder why the following two (pretty similar) examples generate radically different HTML5 outlines.

Example #1

This generates the following outline:

Example #1: Outline

This outline looks ok to me.

Example #2

This generates the following outline:

Example #2: Outline

This outline doesn't look ok to me: the main content is now part of the header!

The difference is one single section container around the "This is the main content" h1 tag.

Can anyone explain me the logic behind this?

Update: Example #3

As pointed out in the answer below, it is important to know that header, footer and main do not start a new section, while having an h-element of the same size than a preceding h-element does start a new section.

So the simple rule of thumb to remember is the following: **When having a header on top of the page, a main in the middle, and a header at the bottom, then each of them have to start with an h1 (which starts the implicit section). Under those h1 elements, you then can add as many other sections (introduced explicitly by sectioning elements [nav, aside, section, and article] or implicitly by lower h-elements [h2 to h6]).

I created another example which (in my opinion) resembles a perfect HTML5 outline - which is also a 100% understandable to pre-HTML5 devices.

This generates the following outlines:

Example #3: HTML5 outline Example #3: pre-HTML5 outline

Solution

  • This is the whole point of <article>, <section>, <nav>, and <aside> tags ("sectioning content" in terms of the spec): they define sub-sections of the larger document.

    You say "the main content is now part of the header", but that's not what the outline shows - it shows that the <section> is a subsection of the main document (<body>), titled <h1>Header</h1>.

    In your first example:

    <body>
  <header><h1>Header</h1></header>
  <main><h1>This is the main content</h1></main>
  <footer><h1>Footer</h1></footer>
</body>

    ..the <header>, <main>, and <footer> elements don't affect the outline. (There's even a note to that effect in the spec - look for "The header element is not sectioning content; it doesn't introduce a new section."), so for the purposes of the outlining algorithm it's equivalent to:

    <body>
  <h1>Header</h1>
  <h1>This is the main content</h1>
  <h1>Footer</h1>
</body>

    In your second example,

    <body>
  <header><h1>Header</h1></header>
  <main>
    <section>
      <h1>This is the main content</h1>
    </section>
  </main>
  <footer><h1>Footer</h1></footer>
</body>

    ..the <section> element introduces a subsection of the first section of the <body> element, so it's equivalent to:

    <body>
  <div>
    <h1>Header</h1>
    <section>
      <h2>This is main content</h2>
    </section>
  </div>
  <div>
    <h1>Footer</h1>
  </div>
</body>

    (I added <div>s to mark up the logical sections of the document implied by the outlining algorithm.)

    So the outline for this is:

    1. Header
  1.1. This is the main content
2. Footer

    This might make more sense with an example from the spec:

    <!DOCTYPE HTML>
<title>The Tax Book (all in one page)</title>
<h1>The Tax Book</h1>
<section>
 <h1>Earning money</h1>
 ...
</section>
<section>
 <h1>Spending money</h1>
 ...

    produces the following outline:

    1. The Tax Book
  1.1 Earning money
  1.2 Spending money

    Notice that "The Tax Book" is the heading of the document, and "earning" and "spending" are subheadings.

    See also the article on HTML5 outlines on MDN, it provides some background for the feature, which will hopefully make this all clearer.