Markdown 中的评论答案

【问题标题】：Comments in MarkdownMarkdown 中的评论
【发布时间】：2011-06-16 22:41:35
【问题描述】：

如何在 Markdown 中编写注释，即未在 HTML 输出中呈现的文本？我在Markdown project 上一无所获。

【问题讨论】：

字里行间阅读，您似乎想将元数据附加到您的 Markdown 中。出于这个原因，我建议使用允许您添加标题的预处理器。例如，请参阅Jekyll's Front Matter。再举一个例子，看看Basho uses Middleman for their documentation。（注意：这不是问题的直接答案，这就是我将其作为评论分享的原因。）
另请参阅MultiMarkdown supports metadata。
这里是在Babelmark上使用不同解析器的不同cmets类型的基准测试。
None 此页面上的答案与所有解析器一致。是那些愉快地展示内容的人，真的让我很委屈。

【解决方案1】：

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

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

注意三个破折号。优点是它在生成 TeX 或 HTML 输出时可以与 pandoc 一起使用。更多信息请访问pandoc-discuss 群组。

【讨论】：

如果我理解正确，三个破折号会使 pandoc 在解析 markdown 文件时忽略注释。但是，如果您使用另一个降价引擎，评论将显示在生成的 HTML 中（因此在“查看源代码”中可见）。所以你必须小心你在评论中的内容；）
你能解释一下 Pandoc 如何区别对待三连线和双连线吗？当我对它们进行实验时，它们似乎以相同的方式处理。此外，the Pandoc user's guide 只是说“原始 HTML 在 HTML、S5、Slidy、Slideous、DZSlides、EPUB、Markdown 和 Textile 输出中以不变的方式传递，并在其他格式中被抑制。”三重破折号似乎没有比双破折号更高的特权。
@dkim 带有三重破折号的注释将被忽略并从 HTML 输出中丢弃。插入 HTML 文件的双虚线 cmets 不是这种情况。最新版本的 Pandoc (1.10) 仍然是这种情况。
如果三个破折号很重要，那么这些不是“标准 HTML”cmets。
Google 员工注意事项：不幸的是，这在 GitHub Markdown 中不起作用，我最终使用了 Magnus 的解决方案。

【解决方案2】：

另一种方法是将 cmets 放在风格化的 HTML 标记中。这样，您可以根据需要切换它们的可见性。例如，在您的 CSS 样式表中定义一个注释类。

.comment { display: none; }

那么，下面的增强型MARKDOWN

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

在浏览器中显示如下

We do support comments

【讨论】：

复制/粘贴最终可能会复制“注释”文本以及常规文本，因此在使用时要小心。对于复制文本块的人来说，它很容易产生意想不到的结果。
@Eilon 的可访问性也很糟糕
辅助功能支持引擎将正确跳过显示：无文本。

【解决方案3】：

披露：我编写了插件。

由于问题没有指定具体的降价实现，我想提一下python-markdown 的Comments Plugin，它实现了上述相同的pandoc 评论风格。

【讨论】：

【解决方案4】：

我相信所有先前提出的解决方案（除了那些需要特定实现的解决方案）都会导致 cmets 包含在输出 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)

为了获得最大的可移植性，在这种类型的 cmets 之前和之后插入一个空行很重要，因为当定义与常规文本发生冲突时，一些 Markdown 解析器无法正常工作。 Babelmark 的最新研究表明，前后空白行都很重要。有的解析器如果前面没有空行就会输出注释，有的解析器如果后面没有空行就会排除下一行。

一般来说，这种方法应该适用于大多数 Markdown 解析器，因为它是核心规范的一部分。（即使定义了多个链接，或者定义了一个链接但从未使用过的行为，也没有严格规定）。

【讨论】：

[//]: # "Comment" 和 [//]: # (Comment) 似乎适用于更广泛的实现，因为# 是一个有效的相对 URI。例如，GitHub 拒绝 <>，整行变得可见。还值得注意的是，链接标签通常需要用空行与其他内容隔开。
为了最独立于平台，它还需要在注释前有一个空行。查看测试：stackoverflow.com/a/32190021/2790048
这可以用于多行 cmets 吗？
@RovingRichard 是的，至少在 Pandoc 中，如果注释块中没有空行（单行换行符很好），这适用于多行 cmets。我对块 cmets 使用 Magnus 的方法，对内联 cmets 使用 chl 的 HTML 方法（尽管通常只有 2 个破折号）。这样我可以阻止注释掉已经包含内联 HTML cmets 的段落。
我经常把评论写在方括号里：[Comment test]::

【解决方案5】：

另见评论家标记，越来越多的 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.

【讨论】：

我认为这种“伪”标准的问题之一是它们不可移植。在某些网站上，这些可以完美运行，而在其他网站上则不会。

【解决方案6】：

如果您使用 Jekyll 或 octopress，则以下操作也可以。

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

Liquid 标签{% comment %} 在 MarkDown 处理器处理之前首先被解析并删除。访问者在尝试从浏览器查看源代码时不会看到。

【讨论】：

Jinja2 = {# multiline cmets 这里#}

【解决方案7】：

这适用于 GitHub：

[](Comment text goes here)

生成的 HTML 如下所示：

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

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

【讨论】：

绝对是，但它实际上是迄今为止唯一在 GitHub 上始终有效的答案，例如在列表中。
我得到了相同的解决方案。这是我唯一可以为在线 cmets 工作的，例如some text [](hidden text) blah blah.
自 2019-03-08 起，这不再适用于 github，它按原样呈现 [](Comment text goes here)
如果只有 GitHub 很重要， 就可以了。

【解决方案8】：

这个小研究证明和提炼the answer by Magnus

最独立于平台的语法是

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

这两个条件都很重要：

使用#（而不是<>）
评论前有一个空行。注释后的空行对结果没有影响。

严格的 Markdown 规范 CommonMark 仅适用于此语法（而不适用于 <> 和/或空行）

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

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

No empty lines, using <> 13+, 15-
Empty line before the comment, using <> 20+, 8-
Empty lines around the comment, using <> 20+, 8-
No empty lines, using # 13+ 1？ 14-
Empty line before the comment, using # 23+ 1？ 4-
Empty lines around the comment, using # 23+ 1？ 4-
HTML comment with 3 hyphens1+2？ 25- 来自chl's answer （注意这是不同的语法）

这证明了上面的陈述。

这些实现未通过所有 7 项测试。没有机会与它们一起使用 exclude-on-render cmets。

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

【讨论】：

优秀、全面的测试工具！看起来你是对的 # works for all but GFM 和 <> works for GFM 但不是其他几个。太糟糕了，GFM 既是一种极端情况，也是一种非常流行的风格。
截至 2016 年 1 月 21 日，s9e\TextFormatter 似乎与 # 一起工作。Cebe 仍然无法处理它。
奇怪的是，如果评论本身包含(...) 它会破坏它。至少在 Visual Studio Code 1.19 上。
因此对于想要一次评论所有文件的 vim 用户：%s/^$.*$$/[comment]: # (\1)/g
Answer by @anapsix 下面是29+, 2-，注释后没有空行。

【解决方案9】：

如何将 cmets 放在一个非 eval、非回显的 R 块中？即，

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

似乎对我很有效。

【讨论】：

另外，您可以随意在“注释掉”代码块中执行cat("# Some Header") 之类的操作并使用results = "asis"，您可以将整个注释掉的部分添加到您的代码中，这些部分可以翻转通过切换eval = FALSE 打开/关闭，因为 R 评估是在 pandoc 编译之前完成的。感谢您的想法！

【解决方案10】：

你可以试试

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

【讨论】：

【解决方案11】：

<!--- ... -->

在 Pandoc Markdown (Pandoc 1.12.2.1) 中不起作用。评论仍然出现在 html 中。以下确实有效：

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

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

【讨论】：

我最喜欢这个，因为它根本不会产生任何输出。对于 Bitbucket，这个前缀就足够了：[#]: .
在 atom.io 的 markdown 扩展上工作正常

【解决方案12】：

对于 pandoc，阻止评论的一个好方法是使用 yaml 元块，as suggested by the pandoc author。我注意到，与许多其他建议的解决方案相比，这提供了更正确的 cmets 语法突出显示，至少在我的环境中（vim、vim-pandoc 和 vim-pandoc-syntax）。

我将 yaml 块 cmets 与 html-inline cmets 结合使用，因为 html-comments cannot be nested。不幸的是，有no way of block commenting within the yaml metablock，所以每一行都必须单独注释。幸运的是，软包装段落中应该只有一行。

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

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

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

【讨论】：

【解决方案13】：

vimInstant-Markdown用户需要使用

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

【讨论】：

【解决方案14】：

kramdown——基于 Ruby 的降价引擎，是 Jekyll 和 GitHub Pages 的默认引擎——has built-in comment support through its extension syntax：

{::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{:/}

这样做的好处是允许内联 cmets，但缺点是不能移植到其他 Markdown 引擎。

【讨论】：

使用 kramdown 2.3.0——使用内联或块 cmets——注释扩展输出 XML cmets：echo '{::comment}secret{:/comment}' | kramdown =>

【解决方案15】：

你可以这样做（YAML 块）：

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

我只尝试了乳胶输出，请确认其他人。

【讨论】：

我不确定丹尼尔对html输出的确认是否正确。我使用 html 输出文件执行此操作并运行“pandoc --bibliography paper.bib -o paper.html paper.md”，HTML 显示了注释行。

【解决方案16】：

下面的效果很好

<empty line>
[whatever comment text]::

该方法利用syntax to create links via reference
由于使用[1]: http://example.org 创建的链接引用不会被渲染，同样以下任何内容也不会被渲染

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

【讨论】：

这个（经过测试的第一个变体）适用于 pandoc 以及 Gitlab 和 GitHub 的当前在线实例。
在 Babelmark 中，带有空行的方法目前通过了所有 31 种风格（从 Baskin-Robbins 那里窃取了一个短语）。我不是 Markdown 专家，但今晚我需要 cmets 来防止 Markdown 预览窗口出现性能问题。如果将此处的整个代码框复制到 Babelmark 中，则任何 cmets 都不会呈现在 HTML 中。这个答案还需要大约 1,000 个赞。
谢谢你。这是跨环境工作的唯一答案。我希望人们滚动！
很棒的发现，这种评论风格在来自31 available here的29个解析器中都能正常工作！

【解决方案17】：

使用mkdocs时，请添加您的mkdocs.yml：

  - pymdownx.striphtml:
      strip_comments: true
      strip_js_on_attributes: false

然后在任何markdown文件中正常的html cmets，如

<!-- this is a comment -->

将从 html 输出中删除。

【讨论】：

【解决方案18】：

对于 Pandoc Markdown，我使用带有 comment 的反引号作为内联“代码”语法的语言

`here's a comment`{=comment}

这会在所有输出中自动过滤掉。它只是重载了它们的代码语法，也适用于多行 cmets 的代码块。我没试过，但我猜这不适用于非 Pandoc Markdown。

【讨论】：

PS comment 没有什么特别之处......只是不要让它成为 html 或 latex 或任何你的目标格式。

【解决方案19】：

我编写了一个小 awk 程序来过滤掉我添加到文本中的 #omitbegin 和 #omitend 标记。我使用 awk 将其输出通过管道传输到 pandoc 可以处理的临时文件。像这样：

awk -f omitfilter.awk aim2_article.md >aim2_article_tmp.md

pandoc --pdf-engine=xelatex --lua-filter=pagebreak.lua --filter pandoc-crossref --citeproc aim2_article_tmp.md -o aim2_article.pdf

这里是omit filter.awk：

/#omitbegin/ {
    insideOmit = 1;
}

! insideOmit {
    print $0
}

/#omitend/ {
    insideOmit = 0;
}

【讨论】：

【解决方案20】：

此 Markdown 评论不会在带有 Jekyll 的 GitHub Pages 网站上呈现

[whatever]: text

因为 Jekyll 使用 Liquid 模板语言来处理模板，所以这个 Liquid 评论也不会在 Jekyll 的 GitHub Pages 网站上呈现

{% comment %}
This is a long comment string 

Newline

Stuff
{% endcomment %}

【讨论】：