我相信所有先前提出的解决方案(除了需要特定实现的解决方案之外)导致注释包含在输出 HTML 中,即使它们未被显示。
如果你想要一个严格意义上的评论(转换文档的读者不应该看到它,即使使用 “查看源”)你可以(ab)使用链接标签(用于参考样式链接)可用于 Markdown 核心规范:
http://daringfireball.net/projects/markdown/syntax#link
那是:
[comment]: <> (This is a comment, it will not be included)
[comment]: <> (in the output file unless you use it in)
[comment]: <> (a reference style link.)
或者你可以走得更远:
[//]: <> (This is also a comment.)
为了提高平台兼容性(并保存一次击键),还可以使用#
(这是一个合法的超链接目标)而不是<>
:
[//]: # (This may be the most platform independent comment)
为了获得最大的可移植性,在此类注释之前和之后插入一个空行很重要,因为当定义与常规文本相比时,某些 Markdown 解析器无法正常工作。 Babelmark 最近的研究表明,前后的空白线都很重要。如果之前没有空行,一些解析器将输出注释,并且如果之后没有空行,则一些解析器将排除以下行。
通常,这种方法应该适用于大多数 Markdown 解析器,因为它是核心规范的一部分。 (即使定义了多个链接时的行为,或者定义了链接但从未使用过时,也未严格指定)。
我使用标准的 HTML 标签
<!---
your comment goes here
and here
-->
请注意三重破折号。优点是它在生成 TeX 或 HTML 输出时与pandoc一起使用。有关pandoc-discuss组的更多信息,请参阅 。
这项小型研究证明并改进了马格努斯的答案
与平台无关的语法最多
(empty line)
[comment]: # (This actually is the most platform independent comment)
这两个条件都很重要:
#
(而不是<>
) 严格的 Markdown 规范CommonMark只能按此语法使用(而不是使用<>
和 / 或空行)
为了证明这一点,我们将使用由 John MacFarlane 编写的 Babelmark2。此工具检查 28 Markdown 实现中特定源代码的呈现。
( +
- 通过了测试, -
- 没有通过, ?
- 留下一些未在渲染的 HTML 中显示的垃圾)。
<>
13 +,15- <>
20 +,8- <>
20 +,8- #
13+ 1? 14- #
23 + 1? 4- #
23 + 1? 4- 这证明了上述陈述。
这些实现失败了所有 7 个测试。没有机会对它们使用带有渲染的排除注释。