API文档应一级划分功能域，二级用封装单接口，避免嵌套过深；示例与错误码用折叠，警告信息用标注，导航须含真实链接。
用 <section></section> 划分 API 模块时，别套嵌太深
API 文档里常见把每个接口塞进一个 <section></section>，但容易忽略语义层级：如果整个文档是“用户管理 API”，那顶层 <section></section> 应该对应“用户管理”这个逻辑模块，而不是每个 GET /users 都独立一层。嵌套超过三层（比如 <section></section> → <section></section> → <section></section>）会让屏幕阅读器混乱，也削弱了大纲生成效果。
实操建议：
- 一级
<section></section>对应功能域（如“认证”“订单”“Webhook”） - 二级用
<article></article>包裹单个接口（它语义更准：一个可独立分发、复用的 API 单元） - 避免在
<section></section>里再套<section></section>来描述请求体字段——改用<dl></dl>或带role="region"的<div> <h3> <code><details></details>+<summary></summary>适合折叠示例和错误码API 文档里大量请求/响应示例会拉长页面，但全收起来又影响快速扫描。原生
<details></details>是轻量解法，比 JS 折叠更可靠，且支持键盘展开（Enter或Space）。注意点：
立即学习“前端免费学习笔记（深入）”；
-
<summary></summary>里别放复杂 HTML；纯文本最稳，比如<summary>curl 示例</summary> - 默认展开用
open属性：<details open></details>，但别对所有示例都加——首屏关键示例开，其余关 - 错误码表格建议每个
<tr> 外包一层 <code><details></details>，方便逐条展开看详情，而非整表滚动<details> <summary>200 OK 响应示例</summary> <pre class="brush:php;toolbar:false;">{"id": 123, "email": "user@example.com"}<aside></aside>放警告、兼容性说明，别放核心参数表<aside></aside>的语义是“与主内容相关但可独立存在”的旁注，适合放Deprecated标记、Rate limit: 100/min、或仅企业版支持这类补充信息。但它不是侧边栏容器——别用它来布局参数列表或请求头表格。常见误用：
- 把
Query Parameters表格塞进<aside></aside>→ 应该用<section></section>或直接<table>，它是接口定义的主干部分 <li>多个 <code><aside></aside>堆在一起 → 合并成一个，用<h4></h4>分段，否则辅助技术会当成多个离散提示 - 没配
aria-label→ 加上，比如<aside aria-label="兼容性说明"></aside>，不然读屏软件只报“aside” - 每个菜单项必须是
<a href="#users">用户 API</a>或指向独立页面的链接 - 锚点链接要确保目标元素有
id，且不重复（<section id="users"></section>） - 如果目录是 JS 动态加载的，得手动补
role="navigation"并保证焦点管理，原生<nav></nav>更省事
用
<nav></nav>做 API 目录时，必须含真实链接很多文档站把左侧导航写成
<nav><ul><li>用户 API</li></ul></nav>，但<li>里没<a></a>——这违反<nav></nav>的语义要求（必须是导航到其他资源的链接集合）。结果是：大纲工具识别失败，键盘用户无法用Tab跳转，SEO 也丢权重。正确做法：
<section></section>和<article></article>的混用边界：一个接口的全部信息（请求、响应、参数、示例）是一个<article></article>；而“用户相关接口”这个集合才是<section></section>。错位一两次看不出问题，整站批量套错，后续做自动化大纲提取或无障碍审计就会卡住。 - 把
-
