|$ curl https://forge-ai.dev/api/markdown?path=docs/html/semantic

$cat docs/semantic-html.md

updated This week·40 min read·published

Semantic HTML

◆HTML◆Semantics◆Core◆Beginner

Introduction

Semantic HTML means using elements that convey meaning about their content — not just how it looks. Instead of wrapping everything in generic <div> tags, semantic elements like <nav>, <article>, and <aside> tell browsers, search engines, and assistive technologies what each part of the page represents.

The word "semantic" comes from the Greek semantikos, meaning "significant." In HTML, semantic markup gives meaning to content structure. A <h1> isn't just big bold text — it is the ◆primary heading of the document. A <button> isn't just a styled box — it is interactive and can be activated via keyboard. Writing semantic HTML is the foundation of accessible, maintainable, and SEO-friendly web development.

Why Semantics Matter

Semantic HTML provides benefits across three critical dimensions: search engine optimization, accessibility, and code maintainability. Each dimension reinforces the others — accessible markup is inherently semantic, and semantic markup provides better SEO signals.

Benefit	Impact	How It Works
SEO	Higher search rankings	Search engines use semantic elements to understand content hierarchy and relevance
Accessibility	Screen reader navigation	AT users navigate via landmarks, headings, and semantic regions
Readability	Easier maintenance	Developers understand page structure at a glance without parsing class names
Future-proofing	Standards-compliant	Browsers and tools evolve, but semantic meaning remains stable
Progressive enhancement	Works without CSS/JS	Semantic elements have default browser behaviors and styles

✓

best practice

Think of semantic HTML as the foundation of your accessibility and SEO strategy. No amount of ARIA attributes or meta tags can fix a page built entirely from <div> elements. Start with proper semantics, then enhance with ARIA where needed.

Semantic Elements Reference

HTML5 introduced a comprehensive set of semantic elements that describe document structure. Each element has a specific meaning and purpose. Understanding when to use each one is essential for writing semantic markup.

◆Sectioning Elements define the document outline and create regions of content:

Element	Purpose	ARIA Role (implicit)	Usage Notes
<header>	Introductory content, logo, navigation	banner (when top-level)	Can be used per-section, not just page-wide
<nav>	Navigation links block	navigation	Use for primary/secondary nav, not all link groups
<main>	Dominant content unique to this page	main	Exactly one per page; not inside article/aside/header/footer
<article>	Self-contained, reusable composition	article	Blog post, forum thread, news story, comment
<section>	Thematic grouping of content	region (with heading)	Should have a heading; not a generic wrapper
<aside>	Tangentially related content	complementary	Sidebars, pull quotes, related links, ads
<footer>	Footer for nearest sectioning root	contentinfo (when top-level)	Copyright, contact, sitemap links

◆Inline Semantic Elements add meaning within text content:

Element	Meaning	Example
<strong>	Strong importance (not just bold)	<strong>Warning:</strong> high voltage
<em>	Emphasis (not just italic)	This is <em>very</em> important
<mark>	Highlighted / marked text	Search result: <mark>semantic</mark>
<time>	Machine-readable date/time	<time datetime="2026-07-07">Today</time>
<address>	Contact information for the author	<address>Contact us at...</address>
<figure> / <figcaption>	Self-contained content with caption	<figure><img><figcaption>...</figcaption></figure>
<details> / <summary>	Disclosure widget (expand/collapse)	<details><summary>More info</summary>...</details>
<cite>	Title of a creative work	<cite>The Great Gatsby</cite>
<q>	Inline quotation	<q>Hello World</q>
<abbr>	Abbreviation / acronym	<abbr title="World Wide Web">WWW</abbr>
<code>	Computer code fragment	<code>console.log('hi')</code>
<kbd>	Keyboard input	Press <kbd>Ctrl+S</kbd>
<samp>	Sample program output	<samp>Error: 404</samp>
<var>	Variable name	<var>username</var>
<dfn>	Defining instance of a term	<dfn>HTML</dfn> is a markup language
<del> / <ins>	Deleted / inserted text	<del>old</del> <ins>new</ins>

semantic-elements.html

HTML

1	<!-- Sectioning elements page structure -->
2	<body>
3	<header>
4	<nav aria-label="Main navigation">
5	<a href="/">Home</a>
6	<a href="/blog">Blog</a>
7	<a href="/about">About</a>
8	</nav>
9	</header>
10
11	<main>
12	<article>
13	<header>
14	<h1>Understanding Semantic HTML</h1>
15	<p>
16	Published <time datetime="2026-07-07">July 7, 2026</time>
17	by <address>Jane Doe</address>
18	</p>
19	</header>
20
21	<section>
22	<h2>What is Semantic HTML?</h2>
23	<p>
24	Semantic HTML uses <strong>meaningful</strong> elements.
25	For example, <em>emphasis</em> is marked with
26	<code><em></code>, not <code><i></code>.
27	</p>
28	<p>
29	Search for <mark>HTML semantics</mark> to learn more.
30	</p>
31	</section>
32
33	<section>
34	<h2>Interactive Example</h2>
35
36	<details>
37	<summary>Click to expand: Why semantics matter</summary>
38	<p>
39	Accessibility, SEO, and maintainability all improve
40	when you use the right element for the right job.
41	</p>
42	</details>
43
44	<figure>
45	<figcaption>
46	Figure 1: Growth in semantic HTML adoption
47	</figcaption>
48	</figure>
49
50	<blockquote cite="https://www.w3.org/standards/">
51	<q>The web's power is in its universality.</q>
52	<footer>— <cite>Tim Berners-Lee</cite></footer>
53	</blockquote>
54	</section>
55
56	<footer>
57	<address>
58	Written by <a href="mailto:jane@example.com">Jane Doe</a>
59	</address>
60	</footer>
61	</article>
62
63	<aside>
64	<h3>Related Articles</h3>
65	<ul>
66	<li><a href="/docs/aria">ARIA Guide</a></li>
67	<li><a href="/docs/seo">SEO Best Practices</a></li>
68	</ul>
69	</aside>
70	</main>
71
72	<footer>
73	<small>© 2026 Example Corp. All rights reserved.</small>
74	</footer>
75	</body>

🔥

pro tip

The <section> element should always have a heading. If you need a generic container without a heading, use <div>. The <article> element can contain nested <article> elements (e.g., comments on a blog post), but <section> nesting should follow the document outline logically.

Document Outline

The HTML document outline is a structural map of the page generated from heading elements (<h1> through <h6>) and sectioning elements (<section>, <article>, <nav>, <aside>). Each sectioning element creates a new entry in the outline, with its heading as the title.

While the HTML5 outline algorithm was designed to allow multiple <h1> elements (one per sectioning root), no browser implements this algorithm in practice. For practical purposes, use a single <h1> per page and nest headings hierarchically (h1 → h2 → h3) without skipping levels.

document-outline.html

HTML

1	<!-- Correct heading hierarchy -->
2	<h1>Page Title (one per page)</h1>
3
4	<section>
5	<h2>Section Level 2</h2>
6	<p>Content for this section.</p>
7
8	<section>
9	<h3>Nested Section Level 3</h3>
10	<p>Content for the subsection.</p>
11	</section>
12	</section>
13
14	<section>
15	<h2>Another Section</h2>
16	<p>More content.</p>
17	</section>
18
19	<!-- Incorrect: skipping heading levels -->
20	<h1>Page Title</h1>
21	<h3>Level 3 after Level 1 (skipped Level 2)</h3>
22
23	<!-- Correct: heading level matches nesting depth -->
24	<article>
25	<h2>Blog Post Title</h2>
26	<section>
27	<h3>Introduction</h3>
28	<p>Opening content.</p>
29	</section>
30	<section>
31	<h3>Detailed Analysis</h3>
32	<p>Deep dive content.</p>
33	<section>
34	<h4>Subpoint A</h4>
35	<p>Fine-grained detail.</p>
36	</section>
37	</section>
38	</article>

✓

best practice

Use a tool like the WAVE browser extension or Nu HTML Checker to validate your document outline. Screen readers use heading structure for navigation — users can jump between headings with keyboard shortcuts. A well-structured outline is one of the highest-impact accessibility improvements you can make.

Landmarks & ARIA Roles

ARIA (Accessible Rich Internet Applications) landmark roles provide a way to programmatically identify regions of a page. Most semantic HTML elements have implicit ARIA roles — for example, <nav> implicitly has role="navigation". You only need to add ARIA roles explicitly when the HTML element does not provide the correct semantics.

ARIA Landmark Role	Implicit HTML Equivalent	When to Use Explicitly
role="banner"	<header> (top-level)	When <header> is inside <article> and is not the page banner
role="navigation"	<nav>	Rarely needed; <nav> already provides this role
role="main"	<main>	Only if <main> cannot be used due to legacy constraints
role="complementary"	<aside>	Rarely needed; <aside> already provides this role
role="contentinfo"	<footer> (top-level)	When <footer> is inside <article> and is not the page footer
role="region"	<section> (with heading)	When a <div> needs to be a landmark (always include aria-label)
role="search"	—	Search form region (use on <form> or <div> containing search)
role="form"	<form>	Rarely; <form> already has this role. Use with aria-label for multiple forms

The "ARIA Landmark — First Rule of ARIA" states: ◆do not use ARIA if a native HTML element provides the semantics you need. Always prefer the semantic HTML element over its ARIA role equivalent. ARIA should supplement, not replace, semantic HTML.

landmarks.html

HTML

1	<!-- Good: native semantic elements with implicit roles -->
2	<header role="banner">
3	<nav role="navigation" aria-label="Main">
4	<a href="/">Home</a>
5	<a href="/blog">Blog</a>
6	</nav>
7	</header>
8
9	<main role="main">
10	<article>
11	<h1>Article Title</h1>
12	<p>Content goes here.</p>
13	</article>
14
15	<aside role="complementary">
16	<h2>Related Content</h2>
17	<ul>
18	<li><a href="/related">Related article</a></li>
19	</ul>
20	</aside>
21	</main>
22
23	<footer role="contentinfo">
24	<p>© 2026 Example Corp</p>
25	</footer>
26
27	<!-- When you must use div, add explicit landmarks -->
28	<div role="region" aria-label="Weather widget">
29	<p>Current temperature: 72°F</p>
30	</div>
31
32	<div role="search" aria-label="Site search">
33	<form>
34	<input type="search" placeholder="Search..." />
35	<button type="submit">Go</button>
36	</form>
37	</div>

ℹ

info

When using role="region" on a <div>, you must provide an aria-label or aria-labelledby attribute. Otherwise, screen readers announce "region" with no name, which is confusing. Landmarks need names to be navigable.

Semantic vs Non-Semantic

The most common mistake in HTML is using <div> and <span> for everything. While these elements are necessary as generic containers, they carry no semantic meaning. Replacing them with the appropriate semantic element improves accessibility, SEO, and code clarity at no cost.

Non-Semantic	Semantic Replacement	Why It Matters
<div class="header">	<header>	Screen readers announce "banner landmark"
<div class="nav">	<nav>	Users can skip to navigation landmarks
<div class="article">	<article>	Indicates self-contained syndicatable content
<span class="bold">	<strong>	Screen readers emphasize with different voice
<span class="italic">	<em>	Convey emphasis, not just visual style
<div onclick="...">	<button>	Keyboard accessible, Enter/Space activates
<span class="date">	<time>	Machine-readable for calendars, search engines
<div class="footer">	<footer>	Screen readers announce "contentinfo landmark"

semantic-vs-non.html

HTML

1	<!-- ❌ Non-semantic: everything is a div or span -->
2	<div class="page">
3	<div class="header">
4	<div class="nav">
5	<span class="nav-item" onclick="goHome()">Home</span>
6	<span class="nav-item" onclick="goAbout()">About</span>
7	</div>
8	</div>
9	<div class="content">
10	<div class="post">
11	<div class="post-title">Blog Post</div>
12	<div class="post-meta">
13	<span class="date">July 7, 2026</span>
14	<span class="author">Jane Doe</span>
15	</div>
16	<div class="post-body">
17	Content with <span class="bold">important</span> parts.
18	</div>
19	</div>
20	</div>
21	</div>
22
23	<!-- ✅ Semantic: elements convey meaning -->
24	<header>
25	<nav aria-label="Main">
26	<a href="/">Home</a>
27	<a href="/about">About</a>
28	</nav>
29	</header>
30	<main>
31	<article>
32	<h1>Blog Post</h1>
33	<p>
34	<time datetime="2026-07-07">July 7, 2026</time>
35	by <address>Jane Doe</address>
36	</p>
37	<p>
38	Content with <strong>important</strong> parts.
39	</p>
40	</article>
41	</main>
42	<footer>
43	<small>© 2026 Example Corp</small>
44	</footer>

✓

best practice

Use the "div element last" principle: before reaching for a <div>, ask whether any semantic element fits. This includes <section>, <article>, <nav>, <aside>, <header>, <footer>, <figure>, <details>, and <main>. Only use <div> when no other element is semantically appropriate.

Common Patterns

Here are three common page layouts implemented with semantic HTML. These patterns serve as templates for blog pages, documentation sites, and landing pages.

Blog Layout

blog-layout.html

HTML

1	<body>
2	<header>
3	<nav aria-label="Main">
4	<a href="/">Home</a>
5	<a href="/blog">Blog</a>
6	<a href="/about">About</a>
7	<a href="/contact">Contact</a>
8	</nav>
9	<!-- Search landmark -->
10	<div role="search">
11	<form action="/search">
12	<input type="search" name="q" aria-label="Search blog" />
13	<button type="submit">Search</button>
14	</form>
15	</div>
16	</header>
17
18	<main>
19	<h1>Latest Articles</h1>
20
21	<article>
22	<h2><a href="/post-1">How to Use Semantic HTML</a></h2>
23	<p>
24	<time datetime="2026-07-07">July 7, 2026</time>
25	by <a href="/author/jane">Jane Doe</a>
26	</p>
27	<p>Semantic HTML is the foundation of accessible web development...</p>
28	<a href="/post-1">Read more →</a>
29	</article>
30
31	<article>
32	<h2><a href="/post-2">CSS Grid Layout Guide</a></h2>
33	<p>
34	<time datetime="2026-07-05">July 5, 2026</time>
35	by <a href="/author/john">John Smith</a>
36	</p>
37	<p>CSS Grid is a powerful layout system...</p>
38	<a href="/post-2">Read more →</a>
39	</article>
40	</main>
41
42	<aside>
43	<h2>Categories</h2>
44	<ul>
45	<li><a href="/category/html">HTML (12)</a></li>
46	<li><a href="/category/css">CSS (8)</a></li>
47	<li><a href="/category/js">JavaScript (15)</a></li>
48	</ul>
49	</aside>
50
51	<footer>
52	<p>© 2026 Example Blog</p>
53	<nav aria-label="Footer">
54	<a href="/privacy">Privacy</a>
55	<a href="/terms">Terms</a>
56	</nav>
57	</footer>
58	</body>

Live preview of a semantic page structure:

preview

SEO Benefits

Search engines use semantic HTML to understand page structure, content hierarchy, and topical relevance. Semantic elements provide strong signals that help search engines parse and rank content correctly.

Semantic Element	SEO Signal	Impact
<h1> – <h6>	Content hierarchy and topic	Strong ranking signal for keywords in headings
<article>	Self-contained content	Featured snippets, Google Discover, rich results
<nav>	Site structure and navigation	Internal link equity distribution
<main>	Primary page content	Core content identified; influences relevance scoring
<time>	Publication/publish date	Freshness signals, date-based rich snippets
<address>	Contact information	Local SEO, knowledge panel data
<figure> / <figcaption>	Image context and caption	Image search ranking, alt text context
<blockquote> / <q>	Quoted content	Citation signals, quote snippets
<abbr>	Definition of acronyms	Entity recognition, knowledge graph

Semantic HTML also enables structured data (Schema.org via itemscope / itemtype) which powers rich results in search engine results pages. Rich results include star ratings, recipe cards, FAQ accordions, and event listings — all of which improve click-through rates.

seo-semantic.html

HTML

1	<!-- Semantic HTML with structured data for SEO -->
2	<article
3	itemscope
4	itemtype="https://schema.org/Article"
5	>
6	<meta itemprop="datePublished" content="2026-07-07" />
7	<meta itemprop="author" content="Jane Doe" />
8
9	<h1 itemprop="headline">
10	How Semantic HTML Improves SEO
11	</h1>
12
13	<p itemprop="description">
14	Discover how using proper HTML elements signals
15	content relevance to search engines.
16	</p>
17
18	<figure itemprop="image" itemscope
19	itemtype="https://schema.org/ImageObject">
20	<img
21	src="semantic-seo-chart.jpg"
22	alt="Chart showing SEO ranking improvement with semantic HTML"
23	itemprop="url"
24	width="800"
25	height="400"
26	/>
27	<figcaption itemprop="caption">
28	Figure 1: Sites using semantic HTML rank 15% higher on average.
29	</figcaption>
30	</figure>
31	</article>
32
33	<!-- Breadcrumb structured data -->
34	<nav aria-label="Breadcrumb">
35	<ol itemscope itemtype="https://schema.org/BreadcrumbList">
36	<li itemprop="itemListElement" itemscope
37	itemtype="https://schema.org/ListItem">
38	<a itemprop="item" href="/">
39	<span itemprop="name">Home</span>
40	</a>
41	<meta itemprop="position" content="1" />
42	</li>
43	<li itemprop="itemListElement" itemscope
44	itemtype="https://schema.org/ListItem">
45	<a itemprop="item" href="/blog">
46	<span itemprop="name">Blog</span>
47	</a>
48	<meta itemprop="position" content="2" />
49	</li>
50	</ol>
51	</nav>

ℹ

info

Combine semantic HTML with JSON-LD structured data for maximum SEO impact. While semantic HTML provides implicit signals, JSON-LD gives search engines explicit, structured metadata about the page. Both approaches complement each other — use semantic HTML for structure and JSON-LD for detailed entity descriptions.

Best Practices

Semantic HTML Checklist

◆Use exactly one <main> element per page — it should contain the unique page content

◆Use <header> and <footer> for both page-level and section-level introductory/footer content

◆Use <nav> for primary and secondary navigation blocks; avoid wrapping every link group in <nav>

◆Use <article> for self-contained content that could be syndicated (blog posts, news items, comments)

◆Use <section> only when there is a natural heading; otherwise use <div>

◆Use <aside> for content tangentially related to the surrounding content (sidebars, related links)

◆Use <figure> with <figcaption> for images, diagrams, code snippets, and charts

◆Use <details> with <summary> for expandable content sections — no JavaScript needed

◆Use <time> with datetime attribute for all dates and times — machine-readable formats benefit calendars and search engines

◆Use <address> only for contact information for the author or organization, not for arbitrary addresses

◆Use <mark> for highlighting text that is relevant in the current context (search results, quotations)

◆Use <strong> for importance (not styling) and <em> for emphasis (not styling)

◆Never use <div> where a semantic element exists — apply the 'semantic element first' rule

◆Maintain a flat heading hierarchy: one h1, then h2, h3, etc. without skipping levels

ARIA Landmark Rules

◆Prefer native HTML semantics over ARIA roles — <nav> over role='navigation'

◆If you must use role='region', always provide an accessible name via aria-label or aria-labelledby

◆Use role='search' on the search form (not <form> itself unless it is a search form)

◆Do not duplicate landmarks — one <main>, one <header role='banner'>, one <footer role='contentinfo'> per page

◆Use aria-label on <nav> when multiple nav elements exist (aria-label='Main', aria-label='Footer')

◆Test landmarks with screen reader landmark navigation to verify proper structure

◆Landmarks should form a complete and non-overlapping structure of the page regions

✓

best practice

Semantic HTML is not optional — it is the foundation of the web platform. Every div that could be a semantic element represents a missed opportunity for accessibility, SEO, and code clarity. Start every HTML document by choosing the most descriptive elements, and add ARIA only where native semantics are insufficient. This approach costs nothing and benefits everyone.

Semantic HTML

Blog Layout

Semantic HTML Checklist

ARIA Landmark Rules

Related Topics