semantic-html-and-seo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Semantic HTML and SEO

Semantic HTML与SEO

Good HTML is not just markup — it is the contract between your content, search engines, assistive technologies, and the browser. Semantic HTML, correct metadata, and progressive enhancement make UI resilient, findable, and accessible by default.

优质的HTML不只是标记——它是内容、搜索引擎、辅助技术与浏览器之间的约定。语义化HTML、正确的元数据和渐进式增强能让UI具备韧性、可被检索且默认支持可访问性。

Semantic HTML5

Use the element that describes the content's meaning, not just its appearance.

使用能描述内容含义而非仅外观的元素。

Document structure

文档结构

html

<header>       <!-- site header, logo, primary nav -->
<nav>          <!-- navigation links -->
<main>         <!-- primary page content, one per page -->
<article>      <!-- self-contained content: blog post, product card, news item -->
<section>      <!-- thematic grouping with a heading -->
<aside>        <!-- tangentially related content: sidebar, callout -->
<footer>       <!-- site footer, secondary links, copyright -->

html

<header>       <!-- site header, logo, primary nav -->
<nav>          <!-- navigation links -->
<main>         <!-- primary page content, one per page -->
<article>      <!-- self-contained content: blog post, product card, news item -->
<section>      <!-- thematic grouping with a heading -->
<aside>        <!-- tangentially related content: sidebar, callout -->
<footer>       <!-- site footer, secondary links, copyright -->

Headings

标题

One

<h1>

per page — the primary topic. Headings form an outline: do not skip levels (

h1

→

h3

without

h2

html

<h1>Product name</h1>
  <h2>Features</h2>
    <h3>Feature detail</h3>
  <h2>Pricing</h2>

每页一个

<h1>

——代表核心主题。标题需形成层级结构：不要跳过级别（如从

h1

直接到

h3

而没有

h2

）。

html

<h1>Product name</h1>
  <h2>Features</h2>
    <h3>Feature detail</h3>
  <h2>Pricing</h2>

Interactive elements

交互元素

html

<button>   <!-- clickable action, submits or triggers JS -->
<a href>   <!-- navigation to a URL -->
<input>    <!-- user data entry -->
<select>   <!-- option selection -->
<details> / <summary>  <!-- native disclosure/accordion -->

Never use

<div>

<span>

as interactive elements without full ARIA annotation — and even then, prefer the native element.

html

<button>   <!-- clickable action, submits or triggers JS -->
<a href>   <!-- navigation to a URL -->
<input>    <!-- user data entry -->
<select>   <!-- option selection -->
<details> / <summary>  <!-- native disclosure/accordion -->

切勿在未添加完整ARIA注解的情况下使用

<div>

或

<span>

作为交互元素——即便添加了注解，也优先使用原生元素。

Images and Alt Text

图片与Alt文本

Every

<img>

needs an

alt

attribute. What goes in it depends on context.

Image type	Alt text
Informative (product photo, chart)	Describe content: `alt="Red leather sofa, three-seater"`
Functional (icon button, logo link)	Describe function: `alt="Go to homepage"`
Decorative	Empty: `alt=""` — screen readers skip it
Complex (chart, diagram)	Short alt + longer description nearby or in `<figcaption>`

html

<!-- Informative -->
<img src="sofa.jpg" alt="Red leather sofa, three-seater">

<!-- Decorative -->
<img src="divider.svg" alt="">

<!-- With caption -->
<figure>
  <img src="chart.png" alt="Bar chart showing revenue growth Q1–Q4 2025">
  <figcaption>Revenue grew 42% year-on-year in Q4 2025.</figcaption>
</figure>

每个

<img>

都需要

alt

属性。属性内容取决于上下文。

图片类型	Alt文本
信息型（产品照片、图表）	描述内容： `alt="Red leather sofa, three-seater"`
功能型（图标按钮、Logo链接）	描述功能： `alt="Go to homepage"`
装饰型	留空： `alt=""` ——屏幕阅读器会跳过它
复杂型（图表、示意图）	简短alt文本 + 附近或 `<figcaption>` 中的详细说明

html

<!-- Informative -->
<img src="sofa.jpg" alt="Red leather sofa, three-seater">

<!-- Decorative -->
<img src="divider.svg" alt="">

<!-- With caption -->
<figure>
  <img src="chart.png" alt="Bar chart showing revenue growth Q1–Q4 2025">
  <figcaption>Revenue grew 42% year-on-year in Q4 2025.</figcaption>
</figure>

SEO Fundamentals

SEO基础

Title and description

标题与描述

html

<title>Product Name — Short descriptor | Brand</title>
<meta name="description" content="One or two sentences. What this page is, who it is for, what they will find.">

Title: 50–60 characters. Most important keyword first.
Description: 120–160 characters. Shown in search results — write for the human, not the algorithm.

html

<title>Product Name — Short descriptor | Brand</title>
<meta name="description" content="One or two sentences. What this page is, who it is for, what they will find.">

标题：50–60字符。核心关键词前置。
描述：120–160字符。会显示在搜索结果中——要面向用户撰写，而非算法。

Canonical URL

规范URL

html

<link rel="canonical" href="https://example.com/the-definitive-url">

Prevents duplicate content penalties when the same page is accessible via multiple URLs.

html

<link rel="canonical" href="https://example.com/the-definitive-url">

当同一页面可通过多个URL访问时，避免重复内容处罚。

Open Graph (social sharing)

Open Graph（社交分享）

html

<meta property="og:title" content="Page title">
<meta property="og:description" content="Page description">
<meta property="og:image" content="https://example.com/og-image.jpg">
<meta property="og:url" content="https://example.com/page">
<meta property="og:type" content="website">

<!-- Twitter/X -->
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Page title">
<meta name="twitter:image" content="https://example.com/og-image.jpg">

OG image: 1200×630px. Appears when the URL is shared on Slack, LinkedIn, Twitter, iMessage.

html

<meta property="og:title" content="Page title">
<meta property="og:description" content="Page description">
<meta property="og:image" content="https://example.com/og-image.jpg">
<meta property="og:url" content="https://example.com/page">
<meta property="og:type" content="website">

<!-- Twitter/X -->
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Page title">
<meta name="twitter:image" content="https://example.com/og-image.jpg">

OG图片尺寸：1200×630px。在Slack、LinkedIn、Twitter、iMessage分享URL时会显示。

Structured Data (JSON-LD)

结构化数据（JSON-LD）

Machine-readable content enables rich search results.

html

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Product Name",
  "description": "Product description",
  "image": "https://example.com/product.jpg",
  "offers": {
    "@type": "Offer",
    "price": "49.00",
    "priceCurrency": "EUR"
  }
}
</script>

Common types:

Product

Article

BreadcrumbList

FAQPage

Organization

SiteLinksSearchBox

机器可读的内容可实现丰富的搜索结果。

html

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Product Name",
  "description": "Product description",
  "image": "https://example.com/product.jpg",
  "offers": {
    "@type": "Offer",
    "price": "49.00",
    "priceCurrency": "EUR"
  }
}
</script>

常见类型：

Product

、

Article

、

BreadcrumbList

、

FAQPage

、

Organization

、

SiteLinksSearchBox

。

Progressive Enhancement

渐进式增强

Build in layers. The core content and function must work without JavaScript. Enhance with CSS. Enhance further with JS.

Layer 1: HTML — content is readable, links work, forms submit
Layer 2: CSS  — layout, typography, visual design
Layer 3: JS   — interactivity, animations, dynamic content

In practice:

Forms must submit via native
```
<form action>
```
without JS — JS can intercept and enhance with fetch
Navigation links must be real
```
<a href>
```
— JS can add transitions
Content must be in the HTML — JS can enhance with lazy-load or personalisation
Images must have
```
src
```
— JS can add lazy loading via
```
loading="lazy"
```
(now native)

分层构建。核心内容与功能必须在无JavaScript的情况下正常工作。用CSS增强视觉效果，再用JS增强交互性。

Layer 1: HTML — 内容可阅读、链接可跳转、表单可提交
Layer 2: CSS  — 布局、排版、视觉设计
Layer 3: JS   — 交互性、动画、动态内容

实践要点：

表单必须能通过原生
```
<form action>
```
提交，无需JS——JS可拦截并通过fetch增强
导航链接必须是真实的
```
<a href>
```
——JS可添加过渡效果
内容必须嵌入HTML中——JS可通过懒加载或个性化功能增强
图片必须设置
```
src
```
——JS可通过原生
```
loading="lazy"
```
实现懒加载

SPA Considerations

SPA注意事项

Single-page applications break browser defaults that SEO and accessibility depend on. Fix them explicitly.

单页应用会打破SEO和可访问性依赖的浏览器默认行为，需要明确修复这些问题。

Server-side rendering or static generation

服务端渲染或静态生成

Client-rendered HTML is not reliably indexed by search engines. Use SSR (Next.js, Nuxt, SvelteKit) or static generation for any content that needs to be found.

客户端渲染的HTML无法被搜索引擎可靠索引。对于需要被检索的内容，使用SSR（Next.js、Nuxt、SvelteKit）或静态生成。

Title and meta updates

标题与元标签更新

Update

document.title

and meta tags on every route change. Use the framework's

<Head>

component or equivalent.

在每次路由切换时更新

document.title

和元标签。使用框架的

<Head>

组件或等效工具。

Focus management

焦点管理

On route change, move focus to the new page's

<h1>

<main>

— screen readers do not detect SPA navigation automatically.

// After route change
document.querySelector('h1')?.focus();

路由切换后，将焦点移至新页面的

<h1>

或

<main>

元素——屏幕阅读器无法自动检测SPA导航。

// After route change
document.querySelector('h1')?.focus();

Scroll restoration

滚动恢复

Restore scroll position to top on navigation, or to the saved position on back navigation. Browser default scroll restoration is disabled in SPAs.

导航时将滚动位置恢复到顶部，或在返回导航时恢复到保存的位置。SPA会禁用浏览器默认的滚动恢复功能。

History API

Use

pushState

replaceState

so back/forward navigation and bookmarking work correctly.

使用

pushState

replaceState

确保后退/前进导航和书签功能正常工作。

Device Capabilities and User Context

设备能力与用户情境

Design and code should adapt to what the device and user can actually do.

设计与编码应适配设备和用户的实际能力。

Input method detection

输入方式检测

css

@media (hover: hover) {
  /* hover states — mouse or trackpad */
  .btn:hover { background: var(--color-primary-hover); }
}

@media (hover: none) {
  /* touch device — no hover, larger targets */
  .btn { min-height: 44px; }
}

css

@media (hover: hover) {
  /* hover states — mouse or trackpad */
  .btn:hover { background: var(--color-primary-hover); }
}

@media (hover: none) {
  /* touch device — no hover, larger targets */
  .btn { min-height: 44px; }
}

Pointer precision

指针精度

css

@media (pointer: coarse) {
  /* fat-finger touch — increase target sizes */
  .interactive { min-height: 44px; min-width: 44px; }
}

@media (pointer: fine) {
  /* mouse — precise, can use smaller targets */
}

css

@media (pointer: coarse) {
  /* fat-finger touch — increase target sizes */
  .interactive { min-height: 44px; min-width: 44px; }
}

@media (pointer: fine) {
  /* mouse — precise, can use smaller targets */
}

Network conditions

网络状况

html

<!-- Lazy load images below the fold -->
<img src="product.jpg" loading="lazy" alt="...">

<!-- Serve modern formats with fallback -->
<picture>
  <source srcset="image.avif" type="image/avif">
  <source srcset="image.webp" type="image/webp">
  <img src="image.jpg" alt="...">
</picture>

html

<!-- Lazy load images below the fold -->
<img src="product.jpg" loading="lazy" alt="...">

<!-- Serve modern formats with fallback -->
<picture>
  <source srcset="image.avif" type="image/avif">
  <source srcset="image.webp" type="image/webp">
  <img src="image.jpg" alt="...">
</picture>

User preferences

用户偏好

css

@media (prefers-reduced-motion: reduce) { /* disable animations */ }
@media (prefers-color-scheme: dark)     { /* dark mode tokens */ }
@media (prefers-contrast: more)         { /* increase contrast */ }
@media (forced-colors: active)          { /* Windows high contrast mode */ }

css

@media (prefers-reduced-motion: reduce) { /* disable animations */ }
@media (prefers-color-scheme: dark)     { /* dark mode tokens */ }
@media (prefers-contrast: more)         { /* increase contrast */ }
@media (forced-colors: active)          { /* Windows high contrast mode */ }

Review Checklist

审查清单

One
```
<h1>
```
per page, headings form a logical outline

Semantic elements used:

<main>

<nav>

<header>

<footer>

<article>

<section>

Every
```
<img>
```
has a meaningful
```
alt
```
or
```
alt=""
```
for decorative images
```
<title>
```
is unique per page, 50–60 characters, keyword-first
```
<meta name="description">
```
present and 120–160 characters
Open Graph tags present on all shareable pages
```
<link rel="canonical">
```
on pages accessible via multiple URLs
Structured data (JSON-LD) on product, article, and FAQ pages
Forms work without JavaScript
SPA updates
```
document.title
```
and meta tags on route change
SPA moves focus on route change
Hover states scoped to
```
@media (hover: hover)
```
Touch targets ≥ 44px on
```
@media (pointer: coarse)
```
Images use
```
loading="lazy"
```
below the fold
```
prefers-reduced-motion
```
respected

每页一个
```
<h1>
```
，标题形成逻辑层级

使用了语义化元素：

<main>

、

<nav>

、

<header>

、

<footer>

、

<article>

、

<section>

每个
```
<img>
```
都有有意义的
```
alt
```
或针对装饰型图片设置
```
alt=""
```
```
<title>
```
每页唯一，长度为50–60字符，核心关键词前置
存在
```
<meta name="description">
```
且长度为120–160字符
所有可分享页面都添加了Open Graph标签
可通过多个URL访问的页面设置了
```
<link rel="canonical">
```
产品、文章和FAQ页面添加了结构化数据（JSON-LD）
表单无需JavaScript即可工作
SPA在路由切换时更新
```
document.title
```
和元标签
SPA在路由切换时移动焦点
悬停状态限定在
```
@media (hover: hover)
```
范围内
在
```
@media (pointer: coarse)
```
下触摸目标≥44px
首屏下方的图片使用
```
loading="lazy"
```
遵循
```
prefers-reduced-motion
```
偏好设置