translate
  1. Learn
  2. Quicksheets
  3. HTML Document Organization

HTML Document Organization

Introduction

Well organized documents enable all users to more easily scan and understand the page. They also enable users to more quickly access specific sections of the document in a number of different ways.

Concepts

Document Outline

The Document Outline is a means of visualizing the organization of your pages based on heading levels. Heading elements (h1-h6) establish overall content hierarchy. h2 elements nest under h1 elements, h3 elements under h2 elements, and so on. Users of assistive technology can "skim" documents by reading the headings, jumping to the one they want more information on.

  • Use h1 for the most important heading of the page (e.g., the page or article title)
  • Use h2 for section titles
  • Use h3 and below to create subsections
  • Verify the flow of your documents by analyzing the Document Outline in your browser’s developer tools

ARIA Landmarks

You can use a subset of available role attribute values to indicate major sections of your page, such as the navigation. Assistive technology users can jump to these landmarks quickly.

  • Use role="banner" on the container for the overall site identifier/header.
  • Use role="main" for the primary content of the page.
  • Use role="navigation" on the container for the site’s navigation.
  • Use role="contentinfo" on the container for the site’s copyright and footer information.
  • Use role="aside" for any sidebar content.
  • Use role="search" on the container for the site’s search form (note: do not use it on the form element itself).

<div role="banner">
   <p>Site Title</p>
</div>
<div role="navigation">
   <ul>
     <li><a href="/">Home</a></li>
     <li>…</li>
   </ul>
</div>
<div role="main">
   <p>Main Content</p>
</div>
<div role="contentinfo">
   <p>Copyright, etc.</p>
</div>

Some HTML elements are granted these roles automatically without use of the role attribute:

  • The first header element within the body is automatically role="banner".
  • The main element is automatically role="main".
  • The nav element is automatically role="navigation".
  • The first footer element within the body is automatically role="contentinfo".

<header>
   <p>Site Title</p>
</header>
<nav>
   <ul>
     <li><a href="/">Home</a></li>
     <li>…</li>
   </ul>
</nav>
<main>
   <p>Main Content</p>
</main>
<footer>
   <p>Copyright, etc.</p>
</footer>

Non-visibly Titled Sections

In some instances, you may not want to visibly label a section of the document, but you would like to provide a section label for non-sighted users. You can do this using the aria-label attribute.

<nav aria-label="Site Navigation">
   <ul>
     <li><a href="/">Home</a></li>
     <li>…</li>
   </ul>
</nav>
… Then elsewhere in your document …
<nav aria-label="Programs Navigation">
   <ul>
     <li><a href="/programs/">Programs Overview</a></li>
     <li>…</li>
   </ul>
</nav>

Bibliography

  1. Robinson M and Faulkner S. Document Outlines, URL: http://html5doctor.com/outlines/
  2. Gustafson A. Adaptive Web Design: Crafting Rich Experiences with Progressive Enhancement. 2015, New Riders. pgs 73-77.
  3. W3C. Using ARIA landmarks to identify regions of a page, URL: https://www.w3.org/WAI/GL/wiki/Using_ARIA_landmarks_to_identify_regions_of_a_page.
  4. W3C. Using HTML5 section element, URL: https://www.w3.org/WAI/GL/wiki/Using_HTML5_section_element.