核心在于结构可维护性与语义准确性：首行必须，次行强制，lang值须符合bcp 47标准；全局唯一且直属于；须配标题，否则用；含信息图片alt需实质描述，装饰性图片才用alt=""；必须置于最前。
大型文档类网站的HTML代码质量，核心不在“写得美不美”，而在于“结构能不能扛住十年、语义能不能被机器和人同时准确理解”。一旦页面量破千、协作人数超十、维护周期超三年，靠直觉写的HTML会迅速变成技术债黑洞。
DOCTYPE 和 lang 属性必须硬编码在首行
不是“建议”而是强制：每个 HTML 文件第一行必须是 ，第二行必须是 <code>（中文站）或 （英文站）。漏掉 lang 会导致屏幕阅读器语音错乱、搜索引擎语言识别失败；用 不带属性或写成 lang="zh"，部分辅助工具直接跳过语言切换逻辑。
必须全小写、无空格、无注释前置——浏览器只认这个精确字符串，多一个空格就可能触发怪异模式-
lang值必须符合 BCP 47 标准，zh-CN≠zh≠zh-chs，后者在 VoiceOver 中无法加载中文语音库 - 生成式构建流程（如 VuePress、Docusaurus）需检查模板是否默认注入了这两项，很多主题默认只写
main / section / article 的嵌套层级不能靠经验判断
文档类网站最容易滥用 <section></section>：把每个二级标题都包一层 <section></section>，结果生成一堆无标题、无语义的空容器。W3C 明确要求：<section></section> 必须有且仅有一个关联的标题（<h2></h2>–<h6></h6>），否则应改用 <div>。
<ul>
<li>
<code><main></main> 全局唯一，且不得嵌套在 <article></article>、<aside></aside> 或 <nav></nav> 内——这是校验器报错高频点
<article></article> 包裹独立可复用的内容单元（如一篇 API 文档），再用 <section></section> 划分子模块（如 “请求参数”、“响应示例”）<section></section>，用 <div class="divider"> 更诚实
<h3>alt 属性和 title 属性的分工必须明确</h3>
<p>文档站点大量使用图标、流程图、命令行截图、错误提示截图，但 <code>alt 和 title 经常被混用甚至留空。真实影响是：键盘用户按 Tab 焦点到图片时，读不出内容；爬虫无法索引图中关键命令或报错信息。
-
alt=""仅用于**完全装饰性**图片（如背景分隔线、纯图标无文字说明）；所有含信息的图必须写实质描述，例如：<img src="curl-example.png" alt="终端中执行 curl -X POST https://api.example.com/v1/users 命令的完整输出截图，包含 201 Created 响应头和返回的 JSON 数据"> -
title不是alt的备胎，它只在鼠标悬停时显示浮层文本，对无障碍无效；文档类站点慎用title，优先把关键说明写进正文或用<figure><figcaption></figcaption></figure> - SVG 图标若内联书写，需补
role="img"和aria-label，因为<svg></svg>默认无语义
meta charset 和 viewport 必须紧贴 head 开头
<meta charset="UTF-8"> 如果没放在 最前面（比如在 <title></title> 后面），某些旧版浏览器会先按系统默认编码解析前几行，导致标题乱码；<meta name="viewport"> 位置不敏感，但和 charset 挨着写能避免团队成员误删或挪动。
- 正确顺序：
<meta charset="UTF-8"> <meta name="viewport" content="width=device-width,initial-scale=1.0"> <title></title>… - 禁止用旧式写法：
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">—— HTML5 已废弃，部分校验器直接报错 - 文档类网站通常不需要
keywords或descriptionmeta，但若用自动化生成（如 DocSearch），需确保值来自实际内容而非模板占位符
真正难的不是记住这些规则，而是当 PR 里出现 200 行新增 HTML 时，能否一眼看出 <section></section> 是否缺标题、lang 是否写错、alt 是否又复制了上一张图的占位文本——这需要把规范编进 ESLint 或 HTMLHint 的 CI 流程里，而不是靠人眼 Review。
