题 Markdown中的评论


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


957
2018-01-28 00:18


起源


在行之间阅读,似乎您想要将元数据附加到Markdown。出于这个原因,我建议使用一个允许你添加标题的预处理器。举个例子,见 杰基尔的前线问题。再举一个例子,看看如何 Basho使用Middleman作为他们的文档。 (注意:这不是问题的直接答案,这就是我将其作为评论分享的原因。) - David J.
另见 MultiMarkdown支持元数据。 - David J.
以下是使用不同解析器的不同注释类型的基准 Babelmark。 - Ulysse BN


答案:


我相信所有先前提出的解决方案(除了需要特定实现的解决方案之外)导致注释包含在输出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解析器,因为它是核心规范的一部分。 (即使定义了多个链接时的行为,或者定义了链接但从未使用过时,也没有严格指定)。


994
2018-01-02 15:18



[//]: # "Comment" 和 [//]: # (Comment) 似乎可以在更广泛的实现上工作,因为 # 是一个有效的相对URI。例如,GitHub拒绝接受 <>,整条线变得可见。值得注意的是,链接标签通常需要通过空行与其他内容分开。 - Zenexer
要最平台独立,在评论之前还需要一个空行。看测试: stackoverflow.com/a/32190021/2790048 - Nick Volynkin
这可以用于多行评论吗? - crypdick
@RovingRichard是的,至少在Pandoc中,如果注释块中没有空行(单行换行正常),这适用于多行注释。我使用Magnus的方法进行块注释,使用chl的HTML方法进行内联注释(尽管通常只有2个破折号)。这样我就可以阻止注释掉已包含内联HTML注释的段落。 - Joel Ostblom
仅供参考,但如果您使用Pandoc创建TOC,则会生成有关重复链接引用的警告。 (这些只是警告,TOC仍然会被创建。) - Karl Giesing


我使用标准的HTML标签,比如

<!---
your comment goes here
and here
-->

请注意三重破折号。它的优点是可以使用 pandoc 生成TeX或HTML输出时。有关更多信息,请访问 pandoc-讨论 组。


783
2018-01-28 15:36



如果我理解正确,那么三重破折号会产生 pandoc 在解析markdown文件时忽略该注释。但是如果你使用另一个降价引擎,评论将显示在生成的HTML中(因此可以通过“查看源”显示)。所以你必须小心你在评论中提出的内容;) - cberzan
你能解释一下Pandoc如何处理三重破折号与双重破折号的区别吗?当我试验它们时,它们似乎以同样的方式处理。也, Pandoc用户指南 只是说“原始HTML在HTML,S5,Slidy,Slideous,DZSlides,EPUB,Markdown和Textile输出中保持不变,并在其他格式中被抑制。”三重破折号似乎没有比双重破折号更高的特权。 - dkim
如果三重破折号很重要,那么这些不是“标准HTML”评论。 - tripleee
对于Google员工的注意事项:遗憾的是,这在GitHub Markdown中无效,我最终使用了Magnus的解决方案。 - Daniel Buckmaster
在2016年2月,这适用于github。 - ac_fire


这项小型研究证明并得到了改进 马格努斯的答案

与平台无关的语法最多

(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)

117
2017-08-24 19:17



优秀,全面的测试工具!看起来你是对的 #  适用于所有人,但GFM 和 <>  适用于GFM 但不是其他几个人。太糟糕的GFM既是一个角落,也是一个角落 非常 流行的味道。 - hobs
它看起来像s9e \ TextFormatter #  截至2016年1月21日.Cebe仍然没有处理它。 - Troy Daniels
奇怪的是,如果评论包含 (...) 它本身就打破了它。至少在Visual Studio Code 1.19上。 - Royi
因此对于想要一次评论所有文件的vim用户: %s/^\(.*\)$/[comment]: # (\1)/g - Simon C.
@Ulysse感谢您的贡献。 ) - Nick Volynkin


如果你正在使用Jekyll或octopress,也可以使用。

{% comment %} 
    These commments will not include inside the source.
{% endcomment %}

液体标签 {% comment %} 首先解析并删除MarkDown处理器甚至到达它之前。访问者在尝试从浏览器中查看源时将看不到。


42
2018-04-05 02:57



Jinja2 = {# 多行评论在这里 #} - John Mee


另一种方法是将注释放在程式化的HTML标记中。这样,您可以根据需要切换其可见性。例如,在CSS样式表中定义注释类。

.comment { display: none; }

然后,增强MARKDOWN以下

We do <span class="comment">NOT</span> support comments

在BROWSER中显示如下

We do support comments


33
2018-02-22 18:11



复制/粘贴可能最终会复制“已注释”的文本以及常规文本,因此在使用时请小心。对于复制文本块的人来说,它很容易产生意想不到的结果。 - Eilon
@Eilon对此的可访问性也很糟糕 - Ethan


这适用于GitHub:

[](Comment text goes here)

生成的HTML看起来像:

<a href="Comment%20text%20goes%20here"></a>

这基本上是一个空链接。显然你可以在渲染文本的源代码中读到它,但无论如何你都可以在GitHub上做到这一点。


25
2018-04-19 00:19



它肯定是,但它实际上是迄今为止唯一可以在GitHub上运行的答案,例如在列表中。 - jomo
@ chl的答案适用于列表之外的GitHub。 - Slipp D. Thompson
我到达了同样的解决方案。这是我唯一能够进行在线评论的人,例如: some text [](hidden text) blah blah。 - c24w


另请参阅批评标记,由越来越多的Markdown工具提供支持。

http://criticmarkup.com/

Comment {>> <<}

Lorem ipsum dolor sit amet.{>>This is a comment<<}

Highlight+Comment {== ==}{>> <<}

Lorem ipsum dolor sit amet, consectetur adipiscing elit. {==Vestibulum at orci magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget nulla.==}{>>confusing<<} Mauris massa sem, tempor sed cursus et, semper tincidunt lacus.

15
2018-03-31 11:17



我认为这种“伪”标准的一个问题是它们不可移植。在某些网站上,这些将完美,而在其他网站上则不会。 - Willem Van Onsem


如何将注释放在非eval,非echo R块中?即,

```{r echo=FALSE, eval=FALSE}
All the comments!
```

似乎对我有用。


11
2017-11-23 03:19



此外,随意做的事情 cat("# Some Header") 在“注释掉”的代码块和使用中 results = "asis",您可以在代码中添加整个注释掉的部分,可以通过切换打开/关闭 eval = FALSE,因为R评估是在pandoc编译之前完成的。谢谢你的想法! - MichaelChirico


披露:我写了插件。

由于问题没有指定具体的降价实现,我想提一下 评论插件 对于 蟒蛇 - 降价,它实现了上面提到的相同的pandoc评论风格。


10
2017-08-22 10:00





<!--- ... --> 

在Pandoc Markdown(Pandoc 1.12.2.1)中不起作用。评论仍然出现在HTML中。以下工作:

Blank line
[^Comment]:  Text that will not appear in html source
Blank line

然后使用+脚注扩展名。它本质上是一个永远不会被引用的脚注。


9
2018-02-23 16:13



你需要编辑你的答案:“上面的标记选项”是这个网站上的移动目标。 - erreka


VIM 即时减价 用户需要使用

<!---
First comment line...
//
_NO_BLANK_LINES_ARE_ALLOWED_
//
_and_try_to_avoid_double_minuses_like_this_: --
//
last comment line.
-->

8
2017-11-01 18:47