Member-only story
The HTML Document Outline
The HTML “Document Outline” is fundamental to our jobs as web developers. When you create a webpage you are ultimately organizing data that will be presented to user agents (Web Browsers, RSS Feeds, Screen readers, Etc.).
The document outline is a visual/written interpretation of how the data on your page will be understood by browsers and search engines, which make up the majority of your sites consumers.
It is commonly written as a tree-list of semantic topics and sub-topics that make up your content, breaking down the information into smaller and smaller chunks. For example, the wikipedia page for the Lord of the Rings has a document outline that looks like this:
[document]The Lord of the Rings
├── [h2]Contents
└── [h2]Plot[edit]
└──[h3]The Fellowship of the Ring[edit]
├──[h4]Prologue[edit]
├──[h4]Book I: The Ring Sets Out[edit]
└──[h4]Book II: The Ring Goes South[edit]If you want to visualize the document outline of any webpage in this way, you can use a copy/paste tool like this one, or you can download a chrome extension to help you visualize it. For example, the header tree for chrome shows me the outline of the Stranger Things IMDB entry like so:
Why This is Important
Document outlines for some of the most prominent websites on the internet are broken. Even Amazon.com does not organize their content thoughtfully, leaving more semantic understanding to the web crawlers that are trying to decipher them. This can lead to unpredictable SEO results, difficulty for screen readers to understand, and poor website organization. But don’t fear, if you write your HTML content thoughtfully then you should have no problem building an understandable document outline.
The Document Outline Algorithm and a Decade of Confusion
For many years there has been a major discrepancy between the HTML5 specification and the actual implementation of the document outline algorithm supported by…
