直接用h2–h6就能生成可用索引，因浏览器和爬虫自动解析标题层级形成大纲；需不跳级、不嵌套错、每标题带id、用section/article包裹，否则大纲断裂或锚点失效。
为什么直接用 h2–h6 就能生成可用索引
浏览器和爬虫会自动解析标题层级形成大纲（Document Outline），只要结构不跳级、不嵌套错，h2 到 h6 的顺序本身就是天然的索引骨架。不需要额外插件或 JS 就能被屏幕阅读器识别、被搜索引擎提取为目录项。
- 必须用
section或article包裹每个h2，否则大纲可能断裂（比如连续两个h2没容器，部分读屏器会合并为同一节） - 禁止跳级：不能
h2后直接写h4；子节必须用h3，再下一级才是h4 - 每个标题必须带
id，例如<h3 id="api-usage">API 使用方式</h3>，否则锚点链接无法定位
手写静态索引列表时 nav + ul 的关键细节
这是兼容性最强、加载最快的方式，但容易因路径或拼写问题导致点击无反应。
-
nav必须放在main外部（如页首或侧边），不能塞进某个section里，否则语义混乱 - 索引项文字必须与对应
h2–h6的文本完全一致（包括空格、标点），否则用户用 Ctrl+F 搜索时对不上 - 链接 href 值要写成
#introduction这种片段标识符，不是./index.html#introduction——后者在单页内会触发刷新 - 若索引项较多，建议用
details/summary包一层，避免首屏信息过载，例如：<details><summary>高级用法</summary><ul>...</ul></details>
scroll-margin-top 不生效的三个常见原因
设置了 scroll-margin-top: 60px 却还是被顶部导航栏遮住标题？大概率是下面这几个配置没对齐。
- 该样式必须加在目标标题元素上，例如
h2 { scroll-margin-top: 60px; }，不能只加在body或main - 父容器不能有
overflow: hidden或overflow: auto，否则滚动行为被截断，锚点定位退化为默认跳转 - 如果用了固定定位的页眉（
position: fixed），scroll-margin-top的值得略大于其高度（比如页眉高 56px，这里至少设 64px），否则仍有 1–2px 偏移
JavaScript 动态生成索引时别忽略的 DOM 状态
用脚本遍历 document.querySelectorAll('h2, h3') 生成索引很常见，但容易在内容异步加载后失效。
立即学习“前端免费学习笔记（深入）”；
- 如果页面部分内容由 JS 动态插入（比如 Markdown 渲染后生成标题），必须等渲染完成再执行索引构建，不能放在
DOMContentLoaded里就完事 - 每次重建索引前，先清空旧
ul内容，否则重复点击会不断追加，出现双份条目 - 高亮当前章节需要监听
scroll事件，但不要用原生scroll—— 性能差且触发频繁；改用IntersectionObserver监听标题是否进入视口更稳定 - 动态索引需手动补全
id：若某h3没写id，脚本应自动生成（比如取文本去空格转 kebab-case），否则锚点无效
nav + 锚点仍能正常跳转——这是可访问性和降级能力的底线。 
