Markdown 注释生成器
写下备注、选择注释写法，即可复制一段留在源文件里、却不会呈现给读者的 Markdown。全部计算都在你的浏览器本地完成。
Markdown 中怎么写注释？
Markdown 本身没有注释语法，通用做法是借用 HTML 注释：`<!-- 备注内容 -->`。GitHub、GitLab、VS Code 等主流渲染器都会保留源文件中的这段文字，同时把它从渲染结果中剔除。单行备注也可以写成引用式的 `[//]: # (备注内容)`。
<!-- TODO：发布前重写这一节 -->
这段正文读者可以看到。注释在渲染后的页面上完全消失，只显示正文；而打开源文件的人依然能读到这条备注。
在线使用 Markdown 注释生成器
参数设置
输出结果
Markdown 注释语法详解
由于 CommonMark 从未定义注释标记，下面每一种写法本质上都是「利用渲染器本来就会丢弃的东西」。它们的差别在于兼容范围，以及在源码中是否显眼。
HTML 注释（推荐）
兼容性遥遥领先的写法。Markdown 会把原始 HTML 透传给渲染器，而渲染器会丢弃注释。GitHub、GitLab、VS Code、Obsidian、Jekyll、Hugo、Pandoc 以及几乎所有静态站点生成器都支持。
<!-- 文档组已于 2025-05-12 复核 -->
使用 npm 安装命令行工具。渲染结果：使用 npm 安装命令行工具。注释不会产生任何输出。
多行注释
同一对定界符可以跨任意多行。注意在结尾的 `-->` 与下一段之间留一个空行，否则解析器可能把它们当成同一个块。
<!--
v2 发布前待办：
- 补充鉴权流程说明
- 增加迁移指南
-->
## 快速开始渲染结果只有「快速开始」这个标题，定界符之间的每一行都被隐藏。
把整段内容注释掉
把现有 Markdown 包进 HTML 注释，就能在不删除的前提下隐藏它——这正是「怎么注释掉一段内容」的标准答案。唯一的限制：被隐藏的文字中不能出现连续两个连字符，否则注释会被提前闭合。
## 当前价格
<!--
## 旧版价格
已在 3.0 版本下线，保留在此仅供参考。
-->页面上只会出现「当前价格」标题；旧版价格仍留在文件中，但读者看不到。
引用式注释
本质是一条没有被引用的链接定义：解析器识别出这个标签，找不到任何地方引用它，于是不输出任何内容。它必须独占一行，且前面留有空行，否则会被当成普通段落文字原样输出。
[//]: # (内部备注：数据来自三季度导出文件)
营收环比增长 15%。
[//]: # "用双引号同样有效"只有营收那句话会被渲染，两行定义都会消失。
空链接注释
引用式写法的变体，把定义指向一个空目标。效果与引用式完全相同；标签可以是任意未被使用的字符串，有的团队用它来标注留言人。
[comment]: <> (草稿文案，暂不发布)
[review-sarah]: <> (这条结论需要和更新日志核对)
该 API 向后兼容。渲染结果：该 API 向后兼容。两条带标签的备注都被隐藏。
Obsidian 与 MDX 的专属注释
这两个生态各有自己的写法。Obsidian 会隐藏双百分号之间的所有内容；MDX v2 按 JSX 解析，HTML 注释在其中是语法错误，必须改用 JSX 表达式注释。
%% 仅 Obsidian 可用的注释，支持单行与多行 %%
{/* MDX / Docusaurus 注释 */}两行各自只在对应生态中被隐藏，换个环境就会原样显示——都不具备可移植性。
各平台对 Markdown 注释的支持
注释能否生效，取决于平台是否允许原始 HTML。会过滤 HTML 的聊天类应用根本没有注释机制，因此在依赖某种写法之前先对照下表确认。
| 平台 | 支持情况 | 说明 |
|---|---|---|
| GitHub / GitLab | 完全支持 | README、Issue、PR 和 Wiki 中 <!-- --> 均被隐藏，[//]: # 同样有效。 |
| VS Code | 完全支持 | Markdown 预览中不显示；选中文字后按 Ctrl+/ 可自动包上 <!-- -->。 |
| Obsidian | 完全支持 | 既支持 HTML 注释，也支持自有的 %% 注释 %% 语法。 |
| 部分支持 | 禁用原始 HTML，<!-- --> 会原样显示，请改用 [//]: # 写法。 | |
| Discord / Slack | 不支持 | 没有任何注释语法，定界符会作为可见文字直接发出去。 |
| Notion | 不支持 | 粘贴进去的注释语法会变成普通文字，请改用 Notion 自带的评论功能。 |
| MDX / Docusaurus | 部分支持 | MDX v2 不接受 <!-- -->，需要写成 JSX 形式 {/* 注释 */}。 |
如何在 Markdown 中添加注释
选择注释写法
没有特殊理由就直接用 HTML 注释——它是唯一一种几乎处处可用的写法。
输入备注内容
在注释文本框中写下提醒、待办或给协作者的留言，多行注释会保留换行。
复制 Markdown
点击复制按钮获取生成的语法，粘贴到 README、Issue 或文档文件中。
确认已被隐藏
提交或发布前切到预览标签页，确认这段注释不会产生任何可见内容。
常见问题
Markdown 有自己的注释语法吗？
没有。无论是最初的 Markdown 规范还是 CommonMark，都没有定义注释。现在通行的写法都属于变通：HTML 注释依靠渲染器会丢弃注释，引用式注释依靠一条没人引用的链接定义不产生任何输出。
怎么把一整段 Markdown 注释掉？
把这一段包进 HTML 注释即可：在它前面一行写 <!--，后面一行写 -->。内容仍保留在文件中，但不会被渲染。注意被隐藏的文字里不要出现连续两个连字符，严格的解析器会因此提前闭合注释。
GitHub 上的评论是用 Markdown 写的吗？
是的。GitHub 的 Issue 评论、Pull Request 评论、代码评审留言和 Discussions 全部使用 GitHub Flavored Markdown，标题、列表、表格、任务列表和代码块都可以正常使用。要在这些输入框里写隐藏注释，语法与 README 一样是 <!-- 备注 -->。
Markdown 支持多行注释吗？
支持，用 HTML 注释即可。在单独一行写 <!-- 开头，中间写任意多行内容，再在单独一行写 --> 结尾。引用式注释不能跨行，每一行都需要单独写一条定义。
注释内容在源码里是可见的吗？
是的。注释只是在渲染结果中被隐藏。任何人打开原始文件、在 GitHub 上查看 raw 视图或克隆仓库，都能读到这些内容。因此绝对不要把密钥或机密信息写进 Markdown 注释。
哪种注释写法兼容性最好？
HTML 注释。它在 GitHub、GitLab、VS Code、Obsidian、Pandoc、Jekyll、Hugo 以及绝大多数渲染器中都有效。对于会过滤原始 HTML 的平台（例如 Reddit），引用式注释是最好的备选。Obsidian 的 %% 语法和 MDX 的 JSX 注释都只在各自生态内可用。
为什么我写的引用式注释被原样显示出来了？
链接定义只有位于行首、且与前后段落之间有空行时才会被识别。如果 [//]: # (备注) 前面有缩进，或者紧贴在上一句话下面，解析器就会把它当成普通文字直接输出。
代码块里的注释语法会生效吗？
不会。Markdown 有意不解析围栏代码块和行内代码中的任何语法，定界符会原样显示。如果要给展示中的代码加注释，请使用该语言自己的注释符号，例如 JavaScript 的双斜杠或 Python 的井号。
怎样在 Markdown 注释里换行？
直接按回车即可。<!-- 与 --> 之间的所有内容都会被渲染器忽略，因此注释内部的换行、缩进和空行都不会影响输出，纯粹是为了让源码更易读。
搜索引擎能看到 Markdown 注释吗？
看不到。Markdown 编译成 HTML 时注释就被移除了，根本不会出现在实际返回的页面里，爬虫也就无从索引。直接写在已发布 HTML 文件中的注释则是另一回事：它会传输到浏览器，只是不显示出来。