Markdown中的评论

 2019-12-25 22:29

遇到的问题:

在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组。

解决方案三

这项小型研究证明并完善了Magnus的答案

最不依赖平台的语法是

 (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)
阅读 622 次发布于 2019年12月25日
推荐阅读
为什么处理排序数组要比处理未排序数组快?

这是一段C ++代码,显示了一些非常特殊的行为。 出于某些奇怪的原因,奇迹般地对数据进行排序使代码快了将近六倍: #include #include #include int main() { // Generate data const unsigned arraySize = 32768; int da...

2019-12-20 阅读 10

如何撤消Git中的最新本地提交?

我不小心将错误的文件提交给Git ,但是我还没有将提交推送到服务器。 如何撤消本地存储库中的那些提交?

2019-12-20 阅读 12

如何在本地和远程删除Git分支?

我想在本地和远程删除分支。 尝试删除远程分支失败 $ git branch -d remotes/origin/bugfix error: branch 'remotes/origin/bugfix' not found. $ git branch -d origin/bugfix error: branch 'origin/bugfix' not found. $ git branch ...

2019-12-20 阅读 9

'git pull'和'git fetch'有什么区别?

主持人注意:鉴于此问题已经发布了67个答案 (其中一些已删除),请在发布另一个问题之前考虑您是否正在贡献新内容 。 git pull和git fetch什么区别?

2019-12-20 阅读 8

什么是正确的JSON内容类型?

我一直在弄乱JSON一段时间,只是将其作为文本推出,并没有伤害任何人(据我所知),但是我想正确地做事。 我已经看到许多所谓的JSON内容类型的“标准”: application/json application/x-javascript text/javascript text/x-javascript text/x-json 但是哪一个是正确的,还是最好的? 我发现在它们之间存在安全性和浏览...

2019-12-20 阅读 10

目录