文档侧边栏需语义结构（优先用nav而非aside）、CSS布局（flex/grid控制位置）与可访问性（aria-current、href锚点、焦点管理）三者齐备，缺一不可。
文档侧边栏（比如 Markdown 编辑器里的大纲栏、API 文档的目录导航）不是靠某个 HTML 标签自动渲染出来的，它需要语义结构 + 布局控制 + 可访问性补全三者齐备；用 aside 是合理起点，但只写它不会让内容“跑到右边”，真正起作用的是 CSS 的 display: flex 或 display: grid，以及对滚动行为的精细处理。
怎么用 aside 和 nav 选对语义容器
文档侧边栏本质是“服务于当前文档结构的导航辅助”，不是广告或延伸阅读——所以优先用 nav，不是 aside。只有当里面混有作者说明、术语注释等非导航内容时，才在 nav 内部嵌一个 aside。
-
nav包含ul+li+a是屏幕阅读器识别“导航区域”的最小可靠结构，不能省略ul - 如果大纲项来自 H2/H3 标签自动生成，必须为每个
a添加href指向对应id，否则键盘 Tab 无法跳转 - 避免把整个侧边栏塞进
aside然后加role="navigation"—— 这属于语义降级，nav原生支持且更轻量 - 服务端或构建时，当前激活的标题项应带
aria-current="page"，而不是仅靠 JS 动态加.active类
display: flex 下如何让大纲栏不挤压主编辑区
文档编辑器常见问题是：侧边栏宽度固定，但主编辑区文字撑破容器、换行失效、滚动错位。这不是 HTML 结构问题，而是 Flex 未切断默认伸缩行为。
- 父容器（如
.editor-layout）必须设display: flex，且不要加overflow: hidden—— 否则 iOS Safari 会截断position: sticky效果 - 大纲栏设
flex: 0 0 280px（不增长、不收缩、固定宽），比width: 280px更安全，防止内容挤压变形 - 主编辑区（
main或.editor-content）加flex: 1; min-width: 0;——min-width: 0是关键，否则长 URL 或无空格文本会强制撑开整行 - 别给
body加margin-left来避让侧边栏，这在缩放或 SSR 渲染时极易出错
为什么大纲栏滚动时“卡住不动”或“跳一下”
文档侧边栏常需随页面滚动保持可见，但 position: sticky 在真实场景中极易失效，根本原因不在属性本身，而在上下文约束被悄悄破坏。
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
立即学习“前端免费学习笔记（深入）”；
-
sticky失效最常见原因是父容器有transform、perspective或will-change—— 检查开发者工具 computed styles，临时移除疑似样式确认 - 确保
nav的直接父元素有min-height: 100vh，且没有overflow: hidden或contain: layout - iOS Safari 对
sticky的 top 偏移支持不稳定，建议用top: 1rem而非top: 0，并加-webkit-overflow-scrolling: touch到内部容器 - 若必须兼容老浏览器，改用
position: fixed，但要同步重置主内容的margin-left，且移动端收起时必须用width: 0; overflow: hidden;，不能只靠visibility: hidden
移动端大纲栏要不要隐藏？怎么藏才不伤体验
文档类应用在小屏下隐藏大纲栏，不是为了“省空间”，而是避免干扰核心阅读流；但隐藏方式直接影响可访问性和交互一致性。
- 真隐藏（
display: none）会切断键盘 Tab 顺序和屏幕阅读器流，除非你同时用aria-hidden="true"并手动管理焦点 - 推荐方案：用媒体查询切为垂直堆叠布局，
nav设order: -1放顶部，或order: 2放底部，保留 DOM 顺序 - 如果必须收起，用
.outline-collapsed { width: 0; overflow: hidden; transition: width 0.2s ease; }+.outline-collapsed + main { margin-left: 0; } - 收起按钮热区至少 44×44px，且必须带
aria-expanded和aria-controls="outline-nav"，否则视障用户无法感知状态
文档侧边栏最难的部分从来不是“怎么让它出现在右边”，而是滚动锚点是否精准、键盘导航是否连贯、屏幕阅读器能否正确播报层级、以及小屏下收起/展开的状态是否与焦点同步——这些细节没对齐，再漂亮的 CSS 也只是半成品。
