Markdown 语法 · 注释
Markdown 怎么加注释？
写不会渲染的备注
Markdown 没有自己的注释语法。但你常想要一条留在文件里、却不显示的备注:一个 TODO、给合作者的提醒、临时关掉的一段。诀窍是借用 HTML 注释:<!-- 备注 -->。
Markdown 直接放行 HTML,浏览器从不显示注释,所以它留在你的源码里、不进渲染页。这是全貌,含那个最大的注意点。
注释的几种写法
| 类型 | 怎么写 | 说明 |
|---|---|---|
| HTML 注释 | <!-- 备注 --> | 标准做法；渲染器把它藏起来 |
| 多行 | 用 <!-- 开头，--> 结尾，中间全藏 | 一条注释跨多行 |
| 链接引用技巧 | [//]: # (备注) | 在更多处理器里渲染成无；略隐晦 |
| 代码块里 | 原样显示 | 代码块不藏这些标记 |
放到上下文里是这样,中间那段不会到达读者:
大家都会读到的可见文字。
<!-- 这条备注不会渲染。
它可以跨好几行。 -->
更多可见文字。最大的注意点：它不是真的隐藏
注释不渲染,但它不是秘密。它明晃晃地待在 .md 文件里,谁打开源码都看得到。用它记备注和 TODO,绝不放密码、token、或任何你不想被读者发现的东西。对页面隐藏 ≠ 对文件隐藏。
什么时候注释反而显示出来
- safe-mode 渲染器:有的 Markdown 处理器为安全会转义或删掉原始 HTML,这会让你的注释显示成文字、或整个消失。它不听话,通常就是这个原因。
- 代码里:在代码块或行内代码里,标记是字面的、会显示出来。那正是代码块的用意,属于预期。
- 不用 HTML 的替代:如果 HTML 注释在你的环境不管用,试链接引用技巧
[//]: # (备注)。它在更多处理器里渲染成无,代价是更难读。
注释在哪儿好用
注释在长文档里最值:半成品段落旁的一个 TODO、README 里解释某个决定的备注、或你留给未来自己的提醒。它们跟着文件走,上下文就在你需要的地方,又不弄乱读者看到的内容。还不熟语法?看 Markdown 怎么写。
用 NoteLoom 看两面
注释有意思的地方在于:它在源码里、却不在输出里,而 NoteLoom 让你两面都看得到。它是个在浏览器里读写本地 .md 文件的编辑器:source 视图里,你的注释就待在文件里;reading 视图里,它掉出去,像渲染器那样。
先说清边界:NoteLoom 没有任何 AI。它不会替你写或管理备注。它只渲染和存回你本地的文件,写这件事在你手里。
用起来:用 Chrome / Edge / Arc 打开 app.noteloom.cc,挂载一个本地文件夹,在 source 和 reading 视图之间切换。直接存回本地,不上云、不用账号。
FAQ
Markdown 里怎么加注释？
Markdown 没有自己的注释，所以借用 HTML 注释：<!-- 你的备注 -->。Markdown 直接放行 HTML、浏览器从不显示注释，所以它不出现在渲染结果里。
Markdown 注释能跨多行吗？
能。开头 <!-- 和结尾 --> 之间的一切都藏起来，想跨几行都行。从第一个标记到最后一个标记算一条注释。
Markdown 注释是真的隐藏吗？
对读源文件的人不是。它不进渲染结果，但就明晃晃地待在 .md 源码里，谁打开源码都看得到。别把密码、token 或任何不想被读者发现的东西放进注释。
我的注释为什么显示成文字了？
两个常见原因。有的 Markdown 处理器跑在 safe mode、会转义或删掉原始 HTML，注释就显示出来或消失。还有在代码块里，标记是字面的、会显示。到你真正用的渲染器里测一下。
有不用 HTML 的注释办法吗？
常见技巧是一个没用到的链接引用：[//]: # (你的备注)。它在比 HTML 注释更多的处理器里渲染成无，代价是读起来隐晦点。两个都行，看你的渲染器认哪个。
NoteLoom 能让我看到两面吗？
能。在 NoteLoom 的 source 视图里，你看到注释就待在文件里；在 reading 视图里它掉出去，像渲染器处理的那样。它没有任何 AI：只渲染和存回你本地的 .md。
手机或 Safari 能用 NoteLoom 弄吗？
目前不行。NoteLoom 依赖浏览器的 File System Access API，当前支持 Chrome、Edge、Arc 这类 Chromium 系桌面浏览器；Firefox、Safari 和手机端暂不支持。
注释在源码里、输出里就没了
用 Chrome / Edge / Arc 打开 NoteLoom,挂载一个本地文件夹,在 source 视图(注释在)和 reading 视图(注释没了)之间切换。直接存回本地,不用装软件,也不用注册账号。
打开 NoteLoom 试试