Markdown中的评论

在批注文件中存储评论的语法是什么,例如文件顶部的CVS $ Id $ comment? 我在减价项目中找不到任何东西。


我相信所有先前提出的解决方案(除那些需要特定实现的解决方案外)都会导致评论被包含在输出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讨论组的更多信息。


这个小小的研究证明和改进了Magnus的答案

最平台独立的语法是

(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-
  • 带3个连字符的HTML评论1+ 2? 25-来自chl的答案(注意这是不同的语法)
  • 这证明了上面的陈述。

    这些实现失败了所有7个测试。 没有机会使用排除在渲染评论与他们。

  • cebe / markdown 1.1.0
  • cebe / markdown MarkdownExtra 1.1.0
  • cebe / markdown GFM 1.1.0
  • s9e TextFormatter(Fatdown / PHP)
  • 链接地址: http://www.djcxy.com/p/449.html

    上一篇: Comments in Markdown

    下一篇: How do I list all files of a directory?