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