Markdown 注释怎么写：隐藏编辑备注但别泄露信息

直接答案：优先使用 HTML 注释

在备注前写 `<!--`，结束处写 `-->`。支持 HTML 注释的 Markdown 渲染器会保留源码，但不会把中间内容显示为正文。

这不是 Markdown 自己定义的独立注释语法，而是嵌入 Markdown 的 HTML。发布平台如果禁用了原始 HTML，可能会显示符号、转义内容或直接移除它。

# 发布说明

<!-- 上线前核对版本号。 -->

2.4 版本已经发布。

发布说明

2.4 版本已经发布。

看不见不代表别人读不到

注释仍是 `.md` 文件的一部分。别人可以打开原始文本、查看 Git 仓库源码、下载文件或翻阅历史记录。

适合写进注释的是“发布前复查日期”“替换临时截图”这类编辑任务。API 密钥、密码、客户信息、未公开数据都不应该出现。

• 可以：检查这张表的总数。
• 可以：正式发布前换掉占位图片。
• 不可以：密码、令牌、身份证号、客户联系方式。
• 确实需要保密的内容应从文件和相关历史中移除。

单行和多行注释怎么写

短备注可以写在同一行。内容较多时，把开始标记和结束标记分别放在前后两行即可。

不要漏掉 `-->`。结束标记缺失时，后面的正文也可能被当作 HTML 块的一部分，具体表现还会因渲染器而异。

<!--
发布前检查：
- 外链是否有效
- 表格数字是否一致
- 图片是否有 alt
-->

兼容的预览不会显示这三项，但它们仍存在于源文件中。

GitHub README 里的注释仍能在源码中看到

GitHub 官方文档明确把 HTML 注释作为“从渲染后的 Markdown 中隐藏内容”的方式。用户切换到 Code 视图后，仍然能读到 `README.md` 里的备注。

因此它可以提醒贡献者同步命令或补充文档，却不能承担保密作用。公开仓库里只写你愿意让所有访问者看到的内容。

## 安装

<!-- package.json 变化后同步更新这条命令。 -->

```sh
npm install
```

渲染页面不显示提醒；Code 视图仍然显示。

• GitHub 文档：使用注释隐藏内容

Obsidian 的 `%%` 不是通用 Markdown

Obsidian 支持 `%% 备注 %%`，也支持把多行内容放在一对 `%%` 之间。编辑时可见，阅读视图中隐藏。

这是 Obsidian 扩展。把同一个文件放进 GitHub、其他编辑器或 CMS 后，百分号和备注可能都会显示。需要跨平台使用时，HTML 注释通常更稳妥，但仍要在最终平台测试。

方案已经完成。%%请小李再核对一次预算。%%

Obsidian 阅读视图会隐藏；普通 Markdown 渲染器不一定认识。

• Obsidian 帮助：注释

代码块中的注释符号会原样显示

围栏代码块的任务就是保留字符。把 `<!-- -->` 放进去，渲染结果会显示这段 HTML 示例，而不是把它隐藏。

代码围栏后的 `html` 只负责语法高亮，不会让代码块内部再次执行 Markdown 或 HTML 注释规则。

```html
<!-- 这行会作为代码显示。 -->
<p>示例</p>
```

可以看到完整的 HTML 代码块。

为什么换个平台结果就不同

CommonMark 把 HTML 注释归入原始 HTML，但应用可以出于安全原因禁用或清理原始 HTML。转换器也可能在导出 HTML、DOCX 或 PDF 时去掉注释。

本地预览只能证明当前渲染器的行为。真正发布前，还要检查 GitHub、CMS、静态站点生成器或目标文件里的结果。

发布前按这四步检查

注释的价值是帮助编辑，不是长期堆积。保留真正对下一位编辑者有用的背景，其余内容在问题解决后删除。

1. 确认最终发布平台先明确文件会进入 GitHub、Obsidian、CMS 还是其他渲染器。
2. 只写无敏感信息的备注假设任何拿到源文件的人都能读到它。
3. 检查源码、预览和下载文件不能只看其中一种呈现。
4. 删除已经完成的提醒避免旧注释给后续维护者造成误解。

• CommonMark：HTML 块
• CommonMark：原始 HTML

相关工具