Markdown 注释：HTML 注释与 [//]: # 写法
Markdown 自己没有注释语法，只能借用别的。最常见的是 HTML 注释 <!-- 备注 -->，单独占一行，前后各空一行，它不会出现在渲染结果里，却仍然留在源文件、导出的 HTML 文件和「查看源代码」里。另一种是链接引用定义 [//]: # (备注)，它在 HTML 里什么也不输出，连源码里都没有。妙言 V4.5.0 在预览和 PDF 导出里会把两种都隐藏，导出 HTML 时 HTML 注释会原样留在文件里。两种都不是私密的，密码和令牌千万别写进去。
两种写法
可见的段落。
<!-- 一行的注释。 -->
<!--
多行的注释。
这里的 Markdown 不会被解析：
- **不会加粗**
-->
[//]: # (不会在 HTML 里留下任何东西的注释。)
又是可见的段落。
HTML 写法之所以成立，是因为原始 HTML 本来就是 Markdown 的一部分。CommonMark 把以 <!-- 开头的行当作 HTML 块的开始，遇到第一个含有 --> 的行才结束，中间的内容原样透传，里面的空行也不会提前结束，所以多行注释里可以放列表和空行。在段落中间，Hello <!-- aside --> world 被当作行内原始 HTML，仍然留在行内。
引用写法是另一套机制。CommonMark 定义的链接引用定义是方括号里的标签、冒号、目的地和可选的标题，标题可以用引号或圆括号，定义本身不渲染任何东西，所以 // 只是个标签，# 是目的地，你的注释是标题，[//]: <> (text) 和 [note]: # "text" 效果相同。标题可以跨多行，但不能含空行，定义也不能打断段落，前面要留一个空行。在妙言 V4.5.0 自带的 cmark-gfm 0.29.0.gfm.3 里，Para 后面紧跟 [//]: # (x)，这条定义会被当成普通文字打印出来。
两种写法各留下什么
| HTML 注释 | [//]: # (text) |
|
|---|---|---|
| 渲染后的页面 | 隐藏 | 隐藏 |
| HTML 源码 | 有 | 没有 |
| 渲染器剥掉原始 HTML 时 | 失效 | 仍然有效 |
| 内容是否按 Markdown 解析 | 否 | 否 |
HTML 注释会进入生成的 HTML，任何人对你的笔记生成的页面点「查看源代码」都能读到。会剥掉原始 HTML 的渲染器，会把它换成 <!-- raw HTML omitted --> 这样的占位符，内容就没了。引用写法什么也不留，但它只是一种约定，不是功能，笔记里别处如果写了 [//]，那段文字会变成指向 # 的链接，同一个标签的第二条定义会被忽略，所以 // 只用一次，或者给每条注释一个不重复的标签。
GitHub 文档记录了 HTML 写法，说放进 HTML 注释的内容会从渲染后的 Markdown 里隐藏，原始文件和编辑页里仍然看得到，能读这个仓库的人就能读到它。
哪里会漏出来
- 代码。 围栏代码块和行内代码里的
<!-- -->会按字面显示，因为那里面什么都不解析，想展示一个注释就是这样写的。 - 没有闭合的注释。 块开头的
<!--没有-->，会把文档后面的所有内容吞进 HTML 块，浏览器就把它们全部隐藏。 - 嵌套。 注释在第一个
-->处结束，一个块里含有第二个注释时，内层-->之后的leaked text会出现在页面上，后面还跟着一个多余的-->，要去掉里面那层注释标记，不要嵌套。 - 闭合符后面的文字。 像
<!-- c --> **text**这样的一行，整行都属于 HTML 块，所以**text**不会加粗，注释要单独占一行。 - 四个空格。 空行之后缩进的
<!-- c -->是代码块，会被打印出来。 - Front matter。 妙言只在笔记以
---开头时才隐藏那个块，上面放一条注释，这个块就变成一条分隔线加一个标题，注释要放在结尾的---下面，规则见 front matter 一文。
表格单元格和标题里可以放行内注释，列表项里把注释缩进到项目文字的位置也可以。
妙言 V4.5.0 怎么处理
妙言用 cmark-gfm 渲染 Markdown，并打开了原始 HTML 选项（CMARK_OPT_UNSAFE），所以注释会作为真正的 HTML 注释进入预览，网页视图不会把它画出来。这同一个渲染器给预览、PDF 导出、HTML 导出和「拷贝HTML」供稿，预览和 PDF 导出里看不到注释文字，因为 PDF 是印出来的预览。「文件」「导出」「HTML」会重新渲染笔记，把 HTML 存到下载目录，这条路径上没有哪一步会去掉注释，所以文件里有。用分享菜单里的「拷贝HTML」复制，也是同样渲染整篇笔记文字，注释包含在内。
编辑区的高亮对注释没有规则，V4.5.0 也没有注释的格式菜单命令或斜杠快捷输入，标记要自己敲。因为源文件里留着它们，在所有笔记里搜 TODO 或者 <!-- 都能找到，这也是用注释而不是直接删掉一行的主要理由，grep -rn "<!--" notes/ 可以把它们全列出来。
注释还是 front matter
两者在渲染结果里都是隐藏的，在文件里都读得到，区别在谁来使用它们。Front matter 是 Jekyll、Hugo 这类生成器会读取的元数据，比如标题、日期或 draft 标记，注释则是所有工具都忽略的。构建要用的字段放 front matter，给自己或编辑的备注放注释，草稿标记还能做注释做不到的事，生成器可以把这个页面排除在站点之外。一段内容如果不能发布，就挪到另一篇笔记里，不要藏在注释里。
别把秘密写进注释
注释是你可能会同步、提交或导出的文件里的纯文本，笔记文件夹可能经过 iCloud 云盘、Dropbox 或 git，参见 同步笔记，导出的 HTML 页面会把注释带给收到它的人。内容敏感的话，就不要放进任何你要分享或发布的笔记。
常见问题
Markdown 有官方的注释语法吗？
没有，CommonMark 和 GFM 都没有定义。HTML 注释是 Markdown 透传的原始 HTML，[//]: # (text) 是被借用成约定的链接引用定义。
该用哪一种？
HTML 注释用得更广，也支持多行。输出必须保持干净，或者渲染器会剥掉原始 HTML 时，用引用写法。
注释会在 GitHub 上显示吗？
渲染后的页面里不会，但原始文件和编辑页里看得到。