Semantic HTML Outline Guide: Headings That Make Sense

A well-structured page reads like a well-structured document: a title, sections with headings, subsections beneath them, in an order that reflects the content's logic. That structure is called the document outline, and in HTML it is expressed through heading elements from h1 down to h6, together with sectioning elements such as article, section and nav. A good outline helps every reader, but it helps some readers most: people using screen readers navigate by headings, jumping from section to section, and a broken outline turns that navigation into a maze.

The HTML Semantic Outline Checker tool inspects pasted HTML and reports its heading structure: the sequence of headings, their levels, and problems such as skipped levels or missing top-level headings. The rules it checks are simple. A page should generally have one h1 that names the page's main topic. Headings should nest in order: an h2 introduces a section, an h3 introduces a subsection within it, and jumping from an h2 straight to an h4 skips a level and confuses the hierarchy. Headings should describe the content that follows them, not merely look large: size is a visual property, while level is a structural one, and choosing a heading level for its font size is one of the commonest markup mistakes.

Semantic elements add a second layer. An article marks self-contained content, a section marks a thematic grouping, and a nav marks navigation. Used well, they reinforce the outline; used as generic containers, they add noise. The checker focuses on headings because headings are the backbone, but a good outline review also asks whether the sectioning elements match the content they wrap.

A worked example you can follow

Suppose a page has these headings in order: h1 Page Title, h2 Getting Started, h4 Advanced Options, h2 Troubleshooting. The checker flags one problem: the jump from h2 to h4 skips h3, a skip of one level. The fix is to change Advanced Options to h3, giving the sequence h1, h2, h3, h2, which nests correctly: Getting Started contains Advanced Options as a subsection, and Troubleshooting returns to the top-level sections. Counting levels confirms it: the sequence of levels is 1, 2, 3, 2, and no step increases by more than 1, which is the nesting rule in arithmetic form.

Now consider a page with two h1 headings: one for the site name in the header and one for the article title. Strictly, a page should have one main topic, and two h1 elements make the outline ambiguous: which one is the page about? The usual fix is to keep the article title as the h1 and demote the site name to a paragraph or a logo element styled to look prominent, since visual prominence and structural level are independent. After the fix, the level sequence starts with a single 1, and screen reader users landing on the page hear the article title first, which is what they came for.

After fixing an outline, re-check it and read it as a table of contents. If the headings alone, read in order, summarise the page accurately, the outline is good. If they read as a random list of phrases, the headings need rewriting, not just re-levelling. The Accessibility Contrast Matrix tool checks the visual side of readability, and the HTML Minify tool shrinks the markup, and see the HTML Formatter Guide for keeping the markup behind the outline tidy.

Common mistakes to avoid

The first mistake is choosing heading levels by font size instead of structure. The second is skipping levels for visual effect, which breaks the hierarchy for assistive technology. The third is using multiple h1 elements for several visually prominent titles. The fourth is writing vague headings such as Introduction or More Info that tell a navigating reader nothing about what follows. The fifth is treating the outline as a search-engine trick rather than a reader aid: keyword-stuffed headings help nobody and read badly to everyone.

For the wider audit context, see 15-Minute On-Page Audit. Check the outline, fix the levels, read the headings as a summary, and the page becomes navigable for every reader, not just the sighted ones.

Outlines beyond headings

Headings carry the outline, but other elements shape how it is experienced. Landmark elements such as header, nav, main and footer divide the page into regions, and assistive technology can jump between them, so a page with a clear main region and a distinct navigation region is easier to traverse than a page where everything sits in generic containers. The main element deserves particular attention: a page should have exactly one, wrapping the content that is unique to that page, excluding repeated headers, navigation and footers. When a page has two main elements or none, region navigation breaks, and the outline, however good its headings, loses its frame.

Lists are another structural signal that is often flattened by mistake. A navigation menu built from divs looks like a menu but announces as unrelated text, while the same menu built as a list announces as a list of a certain number of items, which tells a screen reader user how much navigation to expect. The same applies to step-by-step instructions, feature lists and related links: whenever content is a list in meaning, it should be a list in markup. That principle, meaning in markup rather than appearance alone, is the heart of semantic HTML, and the outline checker is one tool for verifying it.

Testing an outline should involve more than running the checker. Read the headings aloud in order and ask whether a stranger could summarise the page from them. Navigate the page using only a keyboard and a screen reader if possible, even briefly, since that experience reveals problems no automated report captures, such as headings that make sense visually but read confusingly out of context. Automated checks catch level skips and missing headings; human testing catches meaning problems. Both are needed, and neither replaces the other.