Markdown中的评论

如何在Markdown中编写注释，即未在超文本标记语言输出中呈现的文本？我在Markdown项目上什么也没找到。

840521 次浏览
小开

我用标准的超文本标记语言比如

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

注意三重划线。优点是它在生成TeX或超文本标记语言输出时与pandoc一起使用。有关泛泛讨论组的更多信息。

小开

另一种选择是将注释放在风格化的超文本标记语言中。这样，您就可以根据需要切换它们的可见性。例如，在CSS样式表中定义一个注释类。

.comment { display: none; }

然后，以下增强标记

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

在浏览器中显示如下

We do support comments

小开

披露：我写了插件。

由于问题没有指定特定的Markdown实现，我想提到python-markdown@李小加的评论插件，它实现了上面提到的相同的pandoc注释样式。

小开
最佳答案

我相信所有之前提出的解决方案（除了那些需要特定实现的解决方案）都会导致注释包含在输出超文本标记语言中，即使它们没有显示。

如果你想要一个严格为自己准备的注释（转换文档的读者不应该看到它，即使使用“视图源”），你可以（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解析器，因为它是核心规范的一部分（即使定义了多个链接或定义了一个链接但从未使用时的行为没有严格指定）。

小开

另请参阅由越来越多的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.
小开

如果您使用的是Jekyll或octopress以下也将工作。

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

液体标签{% comment %}首先被解析并在MarkDown处理器到达它之前被删除。当访问者试图从浏览器查看源代码时，他们不会看到。

小开

这在GitHub上工作：

[](Comment text goes here)

生成的超文本标记语言如下所示：

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

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

小开

这个小研究证明并改进了答案来自Magnus

最独立于平台的语法是

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

这两个条件都很重要：

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

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

为了证明这一点，我们将使用由约翰·麦克法兰编写的Babelmark 2。该工具检查28个Markdown实现中特定源代码的呈现。

（+-通过了测试，--没有通过，?-留下了一些未在呈现的超文本标记语言中显示的垃圾）。

这证明了上面的陈述。

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

  • CEBE/Markdown 1.1.0
  • cebe/Markdown Markdown Extra 1.1.0/1.0/1.0/1.0/1.0/1.0/1.0/1.0/1.0/1.0/1.0/1.0
  • CEBE/Markdown GFM 1.1.0
  • s9e\文本格式（Fatdown/PHP）
小开

如何将注释放在一个非价钱，非回声R块中？即，

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

似乎对我工作得很好。

小开

你可以试试 

[](Your comments go here however you cannot leave// a blank line so fill blank lines with//Something)
小开 
<!--- ... -->

在Pandoc Markdown（Pandoc1.12.2.1）中不起作用。注释仍然出现在html中。以下确实有效：

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

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

小开

对于pandoc，阻止注释的一个好方法是使用yaml元块，正如pandoc作者所说。我注意到，与许多其他建议的解决方案相比，这为注释提供了更合适的语法突出显示，至少在我的环境中（vim、vim-pandoc和vim-pandoc-syntax）。

从html注释不能嵌套开始，我将yaml块注释与html-inline注释结合使用。不幸的是，有没有办法在yaml元区块中阻止评论，所以每一行都必须单独注释。幸运的是，软包段落中应该只有一行。

在我的~/.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）。取消注释的效果相同。

小开

Vim即时降价用户需要使用

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

Kramdown-Jekyll和GitHub Pages的默认基于Ruby的降价引擎-通过其扩展语法内置了注释支持：

{::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引擎。

小开

你可以这样做（YAML块）：

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

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

小开

下面的效果很好

<empty line>[whatever comment text]::

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

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

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

  - pymdownx.striphtml:strip_comments: truestrip_js_on_attributes: false

然后在任何Markdown文件中正常的html注释，如

<!-- this is a comment -->

将从html输出中删除。

小开

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

`here's a comment`{=comment}

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

小开

我写了一个小awk程序来过滤我添加到文本中的#omitstart和#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;}
小开

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

[whatever]: text

而且由于Jekyll使用Liquid模板语言来处理模板，因此此Liquid注释不会在使用Jekyll的GitHub Pages网站上呈现

{% comment %}This is a long comment string
Newline
Stuff{% endcomment %}
小开

如果它在VS Code中，那么还有另一个不错的选择：

<span hidden> Some texts </span>

这比将语法高亮保留在编辑区域的“超文本标记语言注释标记”具有优势，并且能够为语义标记添加属性，例如<span notice hidden>。

注意：作为常识，请勿在源代码中包含个人信息。

小开

Pandoc有一个选项--strip-comments，它将从超文本标记语言输出中删除所有<!-- normal html comments -->。

https://pandoc.org/MANUAL.html#general-writer-options


提交答案