协慌网

登录 贡献 社区

Markdown 中的评论

将注释存储在 markdown 文件中的语法是什么,例如文件顶部的 CVS $ Id $ 注释? 降价项目我什么都没发现。

答案

我相信所有先前提出的解决方案(除了需要特定实现的解决方案之外)导致注释包含在输出 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)

这两个条件都很重要:

  1. 使用# (而不是<>
  2. 在评论前用空行 。注释后的空行对结果没有影响。

严格的 Markdown 规范CommonMark只能按此语法使用(而不是使用<>和 / 或空行)

为了证明这一点,我们将使用由 John MacFarlane 编写的 Babelmark2。此工具检查 28 Markdown 实现中特定源代码的呈现。

+ - 通过了测试, - - 没有通过, ? - 留下一些未在渲染的 HTML 中显示的垃圾)。

这证明了上述陈述。

这些实现失败了所有 7 个测试。没有机会对它们使用带有渲染的排除注释。

  • cebe / markdown 1.1.0
  • cebe / markdown MarkdownExtra 1.1.0
  • cebe / markdown GFM 1.1.0
  • s9e \ TextFormatter(Fatdown / PHP)