高质量网站html核心在于结构可维护性与语义准确性：doctype必须首行全小写无空格，lang须为bcp 47标准如zh-cn，全局唯一且直属于，必配标题，含信息图片alt需实质描述，须为首项。
高质量网站的 HTML 代码，核心不在“写得漂亮”，而在于结构扛得住协作、语义经得起机器解析、十年后还能被新成员一眼看懂。硬性规范不是可选项，是避免后期技术债爆炸的底线。
DOCTYPE 和 lang 属性必须手敲，不能靠模板自动补全
很多构建工具（如 VuePress、Docusaurus）默认模板漏掉 lang 或把 DOCTYPE 写成 （首字母大写）或前面带空格/注释——浏览器只认精确的 <code> 全小写无空格字符串，否则触发怪异模式（Quirks Mode），CSS 布局和 JS 行为可能错乱。
lang 值必须是 BCP 47 标准格式：zh-CN（不是 zh 或 zh-cn），否则屏幕阅读器语音引擎无法切换中文发音规则，搜索引擎也可能降权。
- 检查所有生成的 HTML 文件，第一行必须是
，第二行必须是 <code> - CI 流程中加入校验脚本：用
grep -n "^\s*" file.html和grep -n "^" file.html强制拦截 - 不要依赖编辑器插件自动注入——它们常在已有文件上追加，导致
DOCTYPE不在首行
main / section / article 的嵌套必须有标题锚点
文档类网站最常见错误：把每个二级标题都包一层 <section></section>，但没配 <h2></h2>。W3C 明确要求 <section></section> 必须有且仅有一个关联标题（<h2></h2>–<h6></h6>），否则语义失效，辅助工具直接忽略该区块。
<main></main> 全局唯一且必须直属于 ；它里面可以嵌 <article></article>（如单篇 API 文档），<article></article> 再用 <section></section> 划分子模块（如“请求参数”“响应示例”）；纯样式分隔容器（比如页脚前一条横线）禁用 <section></section>，改用 <div class="divider">。
<ul>
<li>校验命令：<code>html-validate --config .htmlvalidate.json *.html（配置项需启用 require-heading 规则）
<section><p>这是参数说明</p></section> → 应改为 <div> <h3>参数说明</h3> <p>...</p><div class="aritcle_card flexRow artxards"> <div class="artcardd flexRow"> <a class="aritcle_card_img" rel="nofollow" href="/xiazai/skill4293" title="Doc To HTML"><img src="https://img.php.cn/upload/skill/000/000/081/178998486916110.jpg" alt="Doc To HTML" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a> <div class="aritcle_card_info flexColumn"> <a rel="nofollow" href="/xiazai/skill4293" title="Doc To HTML" class="overflowclass">Doc To HTML</a> <p class="overflowclass">使用 MinerU 文档处理引擎将 Word 文档（.doc、.docx）转换为保留结构和格式的干净 HTML。</p> </div> <a rel="nofollow" href="/xiazai/skill4293" title="Doc To HTML" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span> </a> </div> </div> </div>
<main> 出现在 <code><header></header> 或 <nav></nav> 内部？校验器必报 main-not-in-bodyalt 属性不是可选填空，而是信息等价声明
文档站点大量使用终端截图、错误日志图、流程图，但 alt 留空或写“截图”“流程图”等于没写。键盘用户 Tab 到图片时读不出任何有效信息；爬虫无法索引图中关键命令或 HTTP 状态码。
alt="" 仅用于**完全装饰性**图片（如背景分隔线、纯图标且旁有文字说明）；所有含信息的图必须写实质描述，长度不限，重点是让听障用户能“看见”内容。
- 正确示例：
<img src="curl-404.png" alt="终端执行 curl -i https://api.example.com/v1/users/999 返回 404 Not Found，响应头包含 Content-Type: application/json，响应体为 {" error not found> - 错误现象：
alt="错误截图"→ 读屏软件只读出“错误截图”，用户不知道是 404 还是 500，也不知道接口路径 - CI 中可用
html-proofer --check-html --alt-ignore "/.*/" *.html配合自定义正则排除空值和泛化词
meta charset 必须在 head 最顶部，且不能被 JS 动态插入
<meta charset="UTF-8"> 必须出现在 的**第一个子节点**，否则浏览器在解析到它之前已按默认编码（如 ISO-8859-1）解码前面的内容，中文会直接乱码——这个过程不可逆，JS 后续修改 document.charset 完全无效。
常见陷阱：模板里把 <script></script> 或 <link rel="preload"> 放在 <meta charset> 前面；或者用 JS 动态创建 <meta> 标签注入。
- 手动检查：打开浏览器开发者工具 → Elements → 查看
下第一个子节点是否为<meta charset="UTF-8"> - 构建时用正则校验：
grep -A 5 "" *.html | grep -E "^\s*<meta charset=" | head -1，确保它紧接<head>后出现 - 禁止在
<head>内写任何非<meta>、<title>、<link>的标签（如<script>）放在<meta charset>前
真正难的不是写出合法 HTML，而是让每个标签的存在都有不可替代的理由——当别人删掉一个 <section> 时，得清楚知道语义损失在哪；当修改 alt 时，得确认听障用户获取的信息量没缩水。这些细节不体现在渲染结果上，但决定了网站能不能活过三年。
