Markdown 中的评论

Question

您如何在 Markdown 中编写评论，即未在 HTML 输出中呈现的文本？ 我在Markdown 项目上一无所获。

Answer 1

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

Answer 2

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

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

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

Answer 3

这项小型研究证明并完善了 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/降价 1.1.0
• cebe/markdown MarkdownExtra 1.1.0
• cebe/markdown GFM 1.1.0
• s9e\\TextFormatter (Fatdown/PHP)

Answer 4

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

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

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

Answer 5

这适用于 GitHub：

[](Comment text goes here)

生成的 HTML 如下所示：

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

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

Answer 6

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

.comment { display: none; }

那么，下面增强的MARKDOWN

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

在浏览器中显示如下

We do support comments

Answer 7

Vim Instant-Markdown用户需要使用

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

Answer 8

以下工作非常好

<empty line>
[whatever comment text]::

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

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

Answer 9

另请参阅 Critic Markup，由越来越多的 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.

Answer 10

<!--- ... --> 

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

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

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

Answer 11

把评论放在一个非评估、非回显的 R 块中怎么样？ 即，

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

似乎对我来说效果很好。

Answer 12

披露：我编写了插件。

由于问题没有指定特定的降价实现，我想提到python-markdown的注释插件，它实现了与上述相同的 pandoc 注释样式。

Answer 13

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

Answer 14

对于 pandoc，阻止评论的一个好方法是使用 yaml 元区块， 正如 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> -key，所以,b和,v注释和取消注释一个段落。 如果我需要评论多个段落，我将j,b映射到一个宏（通常是Q ）并运行<number-of-paragraphs><name-of-macro> （例如（ 3Q ）。同样适用于取消注释。

Answer 15

你可以试试

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

Answer 16

您可以这样做（YAML 块）：

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

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

Answer 17

当使用mkdocs ，加在你mkdocs.yml ：

  - pymdownx.striphtml:
      strip_comments: true
      strip_js_on_attributes: false

然后在任何降价文件中使用普通的 html 注释，如

<!-- this is a comment -->

将从 html 输出中删除。

Answer 18

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

Answer 19

Github README.md或Stackoverflow的答案

对于Github README或Stackoverflow答案，我使用＃作为内联注释。

例：

# clone the remote repository to your local machine

npm clone https://github.com/chebaby/echebaby.git

# change directory

cd echebaby

# install dependencies

yarn install

Answer 20

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

`here's a comment`{=comment}

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

Answer 21

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

[whatever]: text

Answer 22

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

<span hidden> Some texts </span>

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

警告：作为常识，不要在您的源代码中包含个人信息。

Answer 23

Pandoc 有一个选项--strip-comments可以从 HTML 输出中删除所有<!-- normal html comments --> 。

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