HTML文档大纲由语义化标题标签<h1>–<h6>的层级与顺序决定，必须连续嵌套、避免跳级，配合<section>/<article>等分组元素形成子大纲，并通过axe等工具验证真实解析结构。
HTML 文档大纲由 <h1> 到 <h6> 的嵌套关系决定，不是靠 class 或 div 堆出来的
浏览器和读屏软件解析文档结构时，只认语义化标题标签的层级和顺序，<h1> 是顶层，<h2> 是其子节，依此类推。用 <div class="title-h2"> 或 CSS 伪造的“标题”完全不参与大纲生成。
常见错误现象：document-outline 工具报“大纲断裂”“跳级（如 <h1> 后直接 <h3>）”“无主标题（缺失 <h1>）”。
- 必须保证标题层级连续：从
<h1>开始，下一级只能是<h2>，不能跳到<h3> - 同一层级多个
<h2>是合法的，表示并列章节 -
<h1>应该全页唯一，且出现在主要内容区域（避开页眉/侧边栏的装饰性标题）
用 axe-core 或浏览器扩展检查大纲是否符合预期
手动数 <h1>–<h6> 容易漏，得靠工具验证实际被解析出的结构。
推荐方法：
立即学习“前端免费学习笔记（深入）”；
- Chrome 安装
axe DevTools扩展 → 打开页面 → 点 “Analyze” → 查看 “Structure” 类别下的heading-order和heading-has-content报错 - 命令行跑
axe-cli https://yoursite.com --rules=heading-order（需提前安装） - Firefox 可用内置的“辅助功能检查器”（右键 → 检查元素 → 切到 Accessibility 面板 → 点 Outline）
注意：DevTools 的 Elements 面板里看到的 DOM 结构 ≠ 大纲结构；必须用专门的无障碍检测工具，因为它们模拟的是屏幕阅读器的真实解析逻辑。
<section>、<article> 等区块标签本身不生成大纲节点，但会影响标题作用域
HTML5 规范里，<section>、<article>、<nav>、<aside> 这些是“大纲分组元素”，它们内部的标题会自动形成独立子大纲，父级标题不会被跳过。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
比如：
<h1>主标题</h1>
<section>
<h2>章节一</h2>
<section>
<h3>小节一</h3>
</section>
</section>
这段会生成三级大纲；但如果把内层 <section> 换成 <div>，<h3> 就变成“跳级”，破坏大纲。
- 用
<section>包裹一组有逻辑关联的标题+内容，才能让其内部标题正确归属 -
<article>内部可重新从<h1>开始，它会被视为独立文档单元 - 不要为了“视觉缩进”而滥用
<section>—— 没语义的包裹反而干扰大纲
服务端渲染或框架组件中，动态插入标题容易导致大纲错乱
React/Vue 里用 v-if 或 {showTitle && <h2>...</h2>} 控制标题渲染时，如果条件变化导致标题突然出现/消失，大纲可能在首屏加载后才补全，或留下空缺层级。
典型问题：
- SPA 路由切换后，新页面没及时挂载
<h1>，工具扫到的是上一页的大纲残留 - SSR 页面中，服务端没输出标题，客户端 JS 补上，但 axe 工具可能只分析初始 HTML
- 组件库里的
<Card title="xxx">如果内部用<div>渲染标题，就根本不在大纲里
解决方向：确保每个逻辑页面至少有一个语义化标题标签，并在首屏 HTML 中静态存在；动态内容区域用 <section> 包裹，内部标题用真实 <h2>–<h6>。
最常被忽略的一点：大纲不是“写完再检查”的事，而是从第一个 <h1> 就得规划好整页层级——后面加个 <section> 或删个 <h2>，都可能让整个结构偏移。
