Semantic HTML
Use landmarks, one h1, ordered headings and real tables so agents and extractors can find the main content of a page.
Most agents that read the web do not see a rendered page. They fetch the raw HTML and run it through a readability extractor or a simple parser that looks for structure. Semantic HTML is what gives that parser something to hold on to. When the markup says what each part of the page is, the agent can keep the content and throw away the rest.
The page skeleton
Every page should start with the same basic parts. Each one answers a question an agent will ask.
<!doctype html>puts the browser and parser in standards mode.langon thehtmlelement says which language the text is in.<title>and<meta name="description">give a name and a summary.<link rel="canonical">names the one true URL of the page.
Then come the landmarks. Use one <main> per page and wrap the content in <article>. Keep <header>, <nav> and <footer> outside of <main>, so an extractor can drop them in one step.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Semantic HTML</title>
<meta name="description" content="Landmarks and headings for agents.">
<link rel="canonical" href="https://example.com/guide/semantic-html/">
</head>
<body>
<header>Site name</header>
<nav>Main links</nav>
<main>
<article>
<h1>Semantic HTML</h1>
<h2 id="skeleton">The page skeleton</h2>
</article>
</main>
<footer>Footer links</footer>
</body>
</html>
Headings as an outline
Agents use headings to split a page into chunks and to build a table of contents. Two rules keep that outline sound.
- Use exactly one
<h1>per page, and make it match the title. - Never skip a level. An
h2can be followed by anh3, but not by anh4.
Give every h2 and h3 an explicit id so it can be linked to. Ids are covered in more depth in Stable URLs and anchors.
Elements that carry meaning
Some elements tell a parser what kind of data it is looking at. Prefer them to styled div and span tags.
- Tables
- Use a real
<table>with<th scope="col">or<th scope="row">, so each cell can be tied to its header. - Code
- Wrap code in
<pre>and<code>, so whitespace is kept and the agent knows not to treat it as prose. - Dates
- Use
<time datetime="2026-10-28">, so the date can be read without guessing the format. - Terms
- Use a
<dl>with<dt>and<dd>for glossaries and key-value data.
How this site does it
Every page on this site is built from one template that follows the skeleton above, with no JavaScript other than a JSON-LD data block. The build checks that each page has one h1 and that every id is unique. If you want the same content without any markup at all, use the Markdown twin described in Markdown twins. To see why the HTML must work before any script runs, read Content without JavaScript.