技术文档网站需语义化html5结构+sticky导航+动态大纲+响应式折叠。用构建骨架，内标题须有id并设scroll-margin-top，右侧大纲js动态生成，移动端用折叠导航，补全scroll-behavior与焦点管理。
技术文档网站不是内容堆砌，而是信息架构 + 快速导航 + 可维护结构的组合。直接用 <div> 套 <code><div> 或硬塞 <code><table> 会迅速失控——尤其当文档层级变深、侧边栏需要自动高亮当前章节、移动端需折叠导航时。<h3>用语义化 HTML5 标签搭骨架，别碰 <code><div> 堆叠<p>文档网站的结构天然有逻辑：页眉含搜索与版本切换，左侧是可滚动的树状目录，中间是带锚点的正文，右侧可选“本页概览”或“编辑此页”按钮，页脚放许可证与贡献说明。这些不是视觉分区，而是语义角色。</p>
<ul>
<li>
<code><header></header> 放 logo、全局搜索框、<nav aria-label="main"></nav>（主导航）和版本下拉
<aside></aside> 包裹左侧导航，加 aria-labelledby 指向标题，方便屏幕阅读器识别“这是文档目录”<main></main> 必须唯一，且只包裹实际文档内容；所有 <h2></h2>–<h4></h4> 都应是它的直接或间接子元素，否则大纲错乱<main></main> 里嵌套 <section></section> 再包 <article></article> —— 文档页通常就一个逻辑主体，<section></section> 适合拆分“安装”“配置”“API”等大模块，不是每段都得套
position: sticky 实现左侧导航固定，但必须配 top 和容器约束
用户滚动时，左侧目录要始终可见，但不能挡住页眉或撑开页脚。靠 position: sticky 最轻量，但失效场景极多。
- 父容器（比如
<aside></aside>的直接父级）必须有明确高度，例如height: calc(100vh - 80px)（减去 header 高度） -
<aside></aside>自身设position: sticky; top: 80px，数值必须严格匹配 header 高度，否则会卡在页眉下面或遮住它 - 若目录项过多导致内部滚动，需给
<aside></aside>加overflow-y: auto，同时确保不触发transform或will-change—— 这俩会让 sticky 失效 - 不要对
<aside></aside>设height: 100%：百分比高度在无显式父高时计算为 0，sticky 直接不触发
右侧“本页大纲”用 document.querySelectorAll("h2, h3") 动态生成，别手写
技术文档的 <h2></h2> 和 <h3></h3> 是天然的导航节点。手动维护右侧大纲，等于每次改标题都要同步两处，必然脱节。
- 用 JS 在页面加载后遍历
main h2, main h3，提取textContent和id（若无id，自动生成如id="install"） - 生成的链接必须带
href="#install"，且对应标题要有相同id，否则点击无效 - 滚动监听时，用
getBoundingClientRect().top判断哪个标题进入视口，再高亮对应大纲项 —— 不要用offsetTop，它不响应 CSStransform或 margin collapse - 别忘了加
scroll-margin-top: 80px到h2, h3上，否则锚点跳转后标题会被 header 盖住
响应式折叠导航：用 details/summary，别写 JS 开关
移动端屏幕窄，左侧导航必须可收起。自己写 toggle 类、监听 click、操作 class，既冗余又易出 bug。
- 把整个左侧导航包进
<details></details>，<summary></summary>里放“目录”文字或图标 - CSS 中用
details[open] summary::marker { content: "▼"; }控制箭头，比 JS 切换 class 更可靠 - 关键点：
<details></details>默认是 inline 元素，需设display: block才能撑开宽度；且summary无法用flex对齐图标和文字，得用display: grid或绝对定位 - 如果需要默认展开（桌面端），加
open属性；移动端用媒体查询配合@media (max-width: 768px)强制details { display: block; }即可
最常被忽略的是 scroll-behavior 和 focus 管理：锚点跳转后，焦点没落到目标标题上，键盘用户无法继续阅读；scroll-behavior: smooth 在 Safari 旧版里不生效，得 fallback 到 JS element.scrollIntoView({ behavior: 'smooth' })。这些细节不处理，文档网站就只是“能看”，不是“好用”。
