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

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

最不依赖平台的语法是

(empty line)
[comment]: # (This actually is the most platform independent comment)

这两个条件都很重要：

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

严格的Markdown规范CommonMark仅在使用此语法时才有效（而不是<>和/或空行）

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

（+-通过了测试，--没有通过，?-留下了一些垃圾，这些垃圾在呈现的HTML中未显示）。

• 没有空行，请使用<> 13 +，15-
• 注释前的空行，使用<> 20 +，8
• 注释周围的空行，使用<> 20 +，8
• 没有空行，使用# 13 + 1？14-
• 注释前的空行，使用 # 23 + 1？4
• 用# 23 + 1 注释周围的空行？4
• 带3个连字符 1+ 2的HTML注释？25-来自chl的答案 （请注意，这是不同的语法）

这证明了以上陈述。

这些实现未通过所有7个测试。没有机会与它们一起使用排除渲染的注释。

• cebe / markdown 1.1.0
• cebe / markdown MarkdownExtra 1.1.0
• cebe / markdown GFM 1.1.0
• s9e \ TextFormatter（Fatdown / PHP）

如果您使用的是Jekyll或octopress，则也可以使用以下方法。

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

首先对Liquid标签{% comment %}进行解析，然后在MarkDown处理器到达之前将其删除。访问者尝试从浏览器查看源时将看不到。

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

.comment { display: none; }

然后，以下增强了MARKDOWN

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

在浏览器中显示如下

We do support comments

这适用于GitHub：

[](Comment text goes here)

生成的HTML看起来像：

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

这基本上是一个空链接。显然，您可以在渲染文本的源代码中阅读它，但是无论如何都可以在GitHub上进行阅读。

Vim Instant-Markdown用户需要使用

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

另请参阅由越来越多的Markdown工具支持的Critic Markup。

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.

如何将注释放在非评估，非回应R块中？即

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

似乎对我来说很好。

披露：我写了插件。

由于问题未指定特定的markdown实现，因此我想提及python-markdown的评论插件，该插件实现了与上述相同的pandoc评论样式。

<!--- ... --> 

在Pandoc Markdown（Pandoc 1.12.2.1）中不起作用。注释仍出现在html中。以下工作：

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

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

以下效果很好

<empty line>
[whatever comment text]::

该方法利用语法来通过引用创建链接，
因为[1]: http://example.org将不会呈现使用创建的链接引用，同样，以下任何内容也不会呈现

<empty line>
[whatever]::
[whatever]:whatever
[whatever]: :
[whatever]: whatever

对于pandoc，阻止注释的一种好方法是使用yaml metablock，如pandoc作者所建议。我注意到，这使评论的更适当的语法高亮相对于很多其他提出的解决方案，至少在我的环境（vim，vim-pandoc，和vim-pandoc-syntax）。

我将yaml块注释与html-inline注释结合使用，因为html-comments不能嵌套。不幸的是，在yaml metablock中没有块注释的方法，因此每一行都必须单独注释。幸运的是，在软包装的段落中应该只有一行。

在我的中~/.vimrc，我为块注释设置了自定义快捷方式：

nmap <Leader>b }o<Esc>O...<Esc>{ji#<Esc>O---<Esc>2<down>
nmap <Leader>v {jddx}kdd

我用,我的<Leader>-键，所以,b和,v分别评论并取消一个段落。如果我需要注释多个段落，我会映射j,b到一个宏（通常是Q）并运行<number-of-paragraphs><name-of-macro>（例如（3Q）。

kramdown —一种基于Ruby的markdown引擎，是Jekyll以及GitHub Pages的默认引擎—通过其扩展语法内置了注释支持：

{::comment}
This text is completely ignored by kramdown - a comment in the text.
{:/comment}

Do you see {::comment}this text{:/comment}?
{::comment}some other comment{:/}

这样做的好处是允许在线注释，但不利之处是无法移植到其他Markdown引擎中。

你可以试试

[](
Your comments go here however you cannot leave
// a blank line so fill blank lines with
//
Something
)

您可以执行以下操作（YAML块）：

~~~
# This is a
# multiline
# comment
...

我仅尝试使用乳胶输出，请为其他人确认。