Markdown 中的评论

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

---

这项小型研究证明并完善了the answer by Magnus

最独立于平台的语法是

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

这两个条件都很重要：

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

严格的 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/降价 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 处理器处理之前先被解析并删除。访问者在尝试从浏览器查看源代码时不会看到。

---

以下工作非常好

<empty line>
[whatever comment text]::

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

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

---

这适用于 GitHub：

[](Comment text goes here)

生成的 HTML 如下所示：

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

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

---

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

.comment { display: none; }

然后，以下增强MARKDOWN

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

在浏览器中显示如下

We do support comments

---

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.

---

<!--- ... --> 

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

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

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

---

将评论放在非评估、非回声的 R 块中怎么样？ IE，

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

似乎对我很有效。

---

披露：我写了插件。

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

---

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

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

---

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

[whatever]: text

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

{% comment %}
This is a long comment string 

Newline

Stuff
{% endcomment %}

---

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

从 html-comments cannot be nested 开始，我将 yaml 块注释与 html 内联注释结合使用。不幸的是，有 no way of block commenting within the 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)。同样适用于取消注释。

---

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

  - pymdownx.striphtml:
      strip_comments: true
      strip_js_on_attributes: false

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

<!-- this is a comment -->

将从 html 输出中删除。

---

你可以试试

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

---

您可以这样做（YAML 块）：

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

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

---

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

`here's a comment`{=comment}

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

---

我编写了一个小 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;
}

---

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

<span hidden> Some texts </span>

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

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

---