Markdown 注释：5 种方法完全指南
在编写 Markdown 文档时，你可能想留一些备注给自己或团队成员，但又不想让这些内容出现在最终显示的结果中。很多开发者搜索 "comment in markdown" 或 "markdown comment syntax" 时，会发现一个让人困惑的事实：Markdown 本身没有原生注释语法。
这是因为在 John Gruber 2004 年设计 Markdown 时，他的目标是创造一种"易读易写的纯文本格式"，注释（comment）并不在这个设计目标内。
不过不用担心，通过利用 HTML 和 Markdown 自身的语法特性，我们有好几种实用的变通方案。我在 GitHub、GitLab、VS Code 和 Typora 上逐一测试过这些方法，下面把实测结果和使用经验分享给你。无论你是想了解 markdown comment block（块注释）、multiline comment（多行注释），还是想 comment out（注释掉）某段内容，这篇文章都能帮到你。
方法一：HTML 注释（最推荐，兼容性最好）
Markdown 支持内联 HTML，所以可以直接使用 HTML 的注释语法：
这是一段正常显示的文字。
<!-- 这是一条注释，不会在渲染结果中显示 -->
这段文字会正常显示。实测结果： 在 GitHub、GitLab、VS Code 预览、Typora、Hugo、Jekyll 上均完全不可见。注释内容在浏览器中通过"查看页面源码"仍然能看到，但普通读者不会注意到。
参考：Markdown Guide 和 Stack Overflow（140万+ 浏览量）均推荐此方法。
HTML 注释支持多行
<!--
这是一段多行注释。
第一行备注。
第二行备注。
可以写很多内容。
-->踩坑经验
我在实际使用中遇到过一个问题：HTML 注释内不能包含 --。比如 <!-- 这是一段 -- 注释 --> 会导致解析错误。这在需要写命令行参数（如 --verbose）的备注时容易中招。
解决方法：避免在注释中使用连续两个短横线，或者用单短横线替代。
适用场景
- 在 README 中给合作者留备注
- 暂时隐藏某段内容但不想删除
- 在博客文章中标记待完善的部分
- 在 Git 提交信息模板中添加填写说明
方法二：引用式链接注释（comments in markdown 的另一种思路）
这个方法利用了 Markdown 引用式链接（reference-style links）的语法特性。当引用的链接标签没有被实际使用时，解析器会忽略它：
[//]: # "这是一条注释"
[//]: # (这也是一条注释)
[comment]: # "这同样是注释"三种写法效果一样，选择你喜欢的一种就行。
为什么这能生效？
引用式链接的语法是 [label]: url "title"。当这个 label 没有被文档中的任何 [label][link] 引用时，渲染器会跳过它。[//]: # 中的 // 确保不会与正常引用冲突，# 作为 URL。这个技巧最早在 Stack Overflow 上被讨论，后来被广泛采用。
实测踩坑
我在 VS Code 的 Markdown 预览中发现，[comment]: # 有时会渲染为一个不可见的空行，导致段落间距变大。而 [//]: # 的表现更稳定。
另外，在嵌套列表中使用引用式注释时要格外小心。我实测在 GitHub 上，如果注释紧跟在列表项后面且缩进不对，注释内容可能会被显示出来。
参考：这个方法在 Stack Overflow 高赞回答 中有详细讨论，在 Pandoc 文档 中也有提及。
优缺点
优点： 注释内容连 HTML 源码中也不会出现（在支持此方法的平台上）。
缺点： 并非所有 Markdown 解析器都支持。在 GitHub、MacDown、Pandoc 上可用，但在某些平台上可能会显示出来。
方法三：三横线注释（仅限 GitHub）
GitHub Flavored Markdown 支持一种特殊的注释语法：
<!--- 这是 GitHub 专用注释 --->这个写法只在 GitHub 上有效。我实测在 GitLab、VS Code、Typora 上均无法正常工作——注释内容会被直接显示出来。
如果你只在 GitHub 上使用 Markdown，可以考虑这种方式。但由于兼容性太差，我个人不推荐在跨平台场景中使用。
方法四：用代码块"注释"（适合 markdown comment out 场景）
如果你想把某段内容"注释掉"（comment out）而不是完全隐藏，可以用代码块把它标记出来：
```text
TODO: 这里需要补充更多内容
FIXME: 这段逻辑需要修改
这不算真正的注释——内容会显示出来，但至少能和正文区分开。适合用来标记待办事项或团队协作中的提醒。
## 方法五：折叠区域（适合放补充信息）
在支持 HTML 扩展的平台上，可以把内容折叠起来：
```markdown
<details>
<summary>点击展开备注</summary>
这里是备注内容，默认是折叠隐藏的。
</details>实测结果： 在 GitHub、GitLab 上完美支持。在 Typora 中也支持。VS Code 预览中支持但样式略有差异。
这个方法适合放一些参考信息或补充说明，读者需要时可以主动展开。
各方法兼容性对比（实测验证）
| 方法 | GitHub | GitLab | VS Code | Typora | Jekyll/Hugo | HTML源码可见 |
|---|---|---|---|---|---|---|
HTML 注释 <!-- --> | ✅ | ✅ | ✅ | ✅ | ✅ | 是 |
引用式链接 [//]: # | ✅ | ⚠️ 待验证 | ⚠️ 可能产生空行 | ✅ | ⚠️ 待验证 | 否 |
三横线 <!--- ---> | ✅ | ❌ | ❌ | ❌ | ❌ | 是 |
| 代码块 | ✅ | ✅ | ✅ | ✅ | ✅ | 是（可见） |
折叠区域 <details> | ✅ | ✅ | ✅ | ✅ | ✅ | 是（可展开） |
说明：✅ = 实测完全支持 | ⚠️ = 部分支持或待验证 | ❌ = 实测不支持。标注"待验证"的项目建议你在自己的环境中测试确认。
实际使用场景
场景一：团队协作留备注
## 项目简介
本项目是一个 Markdown 编辑器。
<!-- @张三: 这里的描述需要根据最新版本更新 -->
<!-- 审核日期: 2026-05-03 -->场景二：暂时隐藏内容
## 功能列表
<!-- 以下功能暂未上线，先隐藏 -->
### 即将推出
- 暗色模式
- 多语言支持场景三：博客文章 SEO 备注
---
title: "Markdown 注释指南"
---
<!-- SEO 备注：主关键词 "markdown comment"，次关键词 "markdown 注释语法" -->
<!-- 内链候选：markdown 语法总览、markdown 代码块 -->
# Markdown 注释指南场景四：Git 提交信息模板
## 变更说明
<!-- 请简要描述本次变更的目的 -->
## 影响范围
<!-- 列出受影响的功能模块 -->场景五：文档模板说明
# 周报模板
## 本周完成
<!-- 在下方列出本周完成的主要工作 -->
## 下周计划
<!-- 在下方列出下周计划 -->行业动态：Markdown 注释正在走向专业化
值得注意的是，Markdown 注释不仅仅是"文档写作者的变通技巧"，在专业开发领域也在获得正式地位。
Java 23 的 JEP 467（Markdown Documentation Comments）是一个标志性进展：从 Java 23 开始，开发者可以在 Javadoc 文档注释中使用 Markdown 语法，替代传统的 HTML + @ 标签写法。这说明 Markdown 在专业开发中的地位在持续提升，"Markdown + 注释"这个组合正在被主流编程语言正式采纳。
常见问题
Markdown 有原生的注释语法吗？
没有。根据 CommonMark 规范和 John Gruber 的原始定义，Markdown 标准中不包含 comment（注释）语法。所以当你搜索 "markdown comment" 时，找到的都是变通方案。所有方法都是利用 HTML 或 Markdown 自身语法特性实现的。
哪种注释方法最安全？
HTML 注释 <!-- --> 是最安全的选择。它在所有主流 Markdown 解析器中都能正常工作，行为一致。来自 Markdown Guide 和 Stack Overflow - Comments in Markdown 的社区共识也支持这个结论。如果你只记住一个 markdown comment syntax，就记住 <!-- -->。
注释会影响页面加载速度吗？
不会。注释内容非常短小，对性能没有任何可感知的影响。
在 Jupyter Notebook 中怎么写注释？
Jupyter 的 Markdown 单元格支持 HTML，直接使用 <!-- 注释内容 --> 即可。
在 VS Code 中如何快速插入注释？
安装 "Markdown All in One" 扩展后，选中文字按 Ctrl+/（Mac 上 Cmd+/）可以快速切换注释。
总结
| 需求 | 推荐方法 |
|---|---|
| 通用注释（所有平台） | HTML 注释 <!-- --> |
| 注释在 HTML 中也不可见 | 引用式链接 [//]: # |
| 仅在 GitHub 使用 | 三横线 <!--- ---> |
| 标记待办事项 | 代码块 |
| 可折叠的补充信息 | <details> 折叠区域 |
记住一个原则：不确定用哪种时，选 HTML 注释 <!-- --> 就对了。 它是唯一在所有主流平台上都可靠工作的方案。
参考来源：
- Markdown Guide - Hacks（Markdown 社区权威参考）
- Stack Overflow - Comments in Markdown（140万+ 浏览量，26个回答）
- GitHub Gist - How to comment out stuff（GitHub 场景实测）
- OpenJDK JEP 467（Java 23 Markdown 文档注释）