标题标签必须带唯一规范id，清洗为小写连字符格式，重复标题加序号后缀，空标题跳过；目录href须严格匹配id；目录从h2到h4自动生成并缩进；滚动定位用scrollIntoView并设scroll-behavior: smooth。
标题标签必须带唯一且规范的 id 属性
浏览器不会自动给 <h2>安装步骤</h2> 加 id，不手动或用脚本补上，目录链接点击后就找不到目标。id 值不能含空格、中文、标点或大写字母——这些会导致 a[href="#安装步骤"] 失效。推荐清洗规则：textContent.toLowerCase().replace(/[^a-z0-9]/g, '-').replace(/-+/g, '-')，例如“安装步骤”转为 install-steps。
重复标题（如多个“注意事项”）必须加序号后缀，避免 id 冲突：id="notes-1"、id="notes-2"。空标题或纯空白符的 <h3></h3> 要跳过，否则生成 id=""，触发控制台警告并中断逻辑。
目录项 href 必须严格匹配标题 id
目录里的每个链接，href 值要一字不差地等于对应标题的 id，前面加 # 即可。比如标题是 <h2 id="faq">常见问题</h2>，目录项就得写 <a href="#faq">常见问题</a>。大小写、连字符、顺序都不能错——#FAQ 或 #fa-q 都会跳转失败。
别用 class 名或文本内容硬编码链接。常见错误是写 <a href="#section2">第二章</a>，但标题实际是 <h2 id="chapter-two">第二章</h2>，结果点击 404。正确做法：让标题自己带 id，目录只读这个 id。
立即学习“前端免费学习笔记（深入）”；
层级结构要清晰，从 h2 开始纳入目录
主标题 <h1> 通常不放进阅读目录，它代表整篇文档，不是章节。目录应从 <h2> 开始收集，最多到 <h4> ——太浅（h5/h6）层级过深难导航，太深（h1）又破坏逻辑结构。
生成目录时，根据标签层级自动缩进更直观。例如 h2 项无缩进，h3 项缩进 1.5em，h4 项缩进 3em。用 CSS 的 margin-left: calc(var(--level) * 1.5em) 实现，不要用 JS 动态设 style。
滚动定位要平滑且精准
单纯靠 location.href = "#xxx" 会整页跳、有闪烁、不支持取消。推荐用 element.scrollIntoView({ behavior: 'smooth', block: 'start' })，它可控、可监听、不刷新 URL。
同时在 <html> 标签加 CSS：scroll-behavior: smooth；给目标标题加 tabindex="-1"，滚动后自动聚焦，方便键盘用户和屏幕阅读器识别当前章节。
注意移动端 Safari 对 behavior: 'smooth' 支持不稳定，可降级为 'auto'，或用 window.scrollTo 手动计算位置。
