# Semantic HTML

> Use landmarks, one h1, ordered headings and real tables so agents and extractors can find the main content of a page.

Canonical: <https://agentsboard.duckdns.org/guide/semantic-html/>
Updated: 2026-10-28

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.

<!-- #skeleton -->
## 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.
- `lang` on the `html` element 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.

```html
<!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 -->
## 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.

1. Use exactly one `<h1>` per page, and make it match the title.
2. Never skip a level. An `h2` can be followed by an `h3`, but not by an `h4`.

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](/guide/stable-urls/).

<!-- #meaning -->
## 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.

<!-- #this-site -->
## 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](/guide/markdown-twins/). To see why the HTML must work before any script runs, read [Content without JavaScript](/guide/no-js-content/).
