html中唯一合法注释是，必须独立于标签外，禁止嵌套或含--和>；所谓“旁注”实为css模拟或编辑器渲染，浏览器原生不支持。
HTML里没有“旁注标签”，只有<!-- -->注释语法
很多人搜“旁注”“文本旁注”，其实是把“给HTML代码加说明”理解成了类似Word里的批注。但HTML规范中根本不存在<aside></aside>以外的“旁注标签”，更没有能浮在文字右侧显示说明的原生机制。所有开发者看到的“旁注效果”，要么是CSS定位模拟，要么是编辑器插件渲染，浏览器本身从不渲染任何注释内容。
真正能写进源码、被所有浏览器一致忽略的，只有<!-- -->这一种注释方式。它不参与DOM构建，不触发重排，也不影响语义——只存在于源文件里，供人阅读。
注释必须写在标签外部，否则会破坏HTML结构
把<!-- -->塞进标签内部（比如<p class="<!-- 注释 -->text"></p>）是高频致错操作。浏览器解析器遇到<!--时会立刻切换到注释状态，直到下一个-->；一旦位置错，后续属性或闭合标签就可能被吞掉，导致整段DOM消失或错位。
- ✅ 正确：独立成行，放在
<header></header>之前或之后 - ✅ 正确：包裹一整块代码，如
<!-- <nav>...</nav> --> - ❌ 错误：写在开始标签内，如
<div>class="wrap"><li>❌ 错误：写在<code><script></script>或<style></style>标签内部（应改用//或/* */） - ⚠️ 禁止：
<!-- 外层<!-- 内层 -->文字 --> - ⚠️ 禁止：
<!-- 启用--自动保存 --> - ✅ 替代：
<!-- 启用——自动保存（中文破折号） --> - ✅ 替代：
<!-- 启用-auto-save（用短横+字母分隔） -->
<!-- -->不能嵌套，且禁用--和>组合
注释解析器见到第一个-->就立即结束，不管后面还有没有未闭合的<!--。所谓“嵌套”只是视觉假象，实际会导致后续内容裸露渲染——轻则页面出现外层继续 -->这种乱码，重则JS报Uncaught SyntaxError。
同样，注释正文里出现--（两个连续短横）也会被当作结束信号提前截断。例如<!-- 配置项：启用--自动保存 -->，其中--自动保存 -->会被跳过，后面的内容直接暴露。
用注释标记区块比“旁注”更实用
与其纠结怎么让注释显示在文本旁边，不如用<!-- -->清晰划分结构区域。这是团队协作中最常被验证有效的做法，比如：
<!-- 主体内容区开始 --><main class="content"></main><article><h2>标题</h2>
<p>正文</p></article><!-- 主体内容区结束 -->
VS Code等编辑器能自动折叠这类注释块，<!-- TODO: 补充表单验证逻辑 -->还能被插件识别为待办事项。比起虚构的“旁注”，这种写法不依赖任何运行时支持，从源码到部署全程稳定。
真正容易被忽略的是：注释里写的任何东西，用户点右键→“查看网页源代码”就能全看到。别放密钥、路径、内部接口地址——它不是安全屏障，只是协作便签。
