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 中的垃圾)。

这证明了以上陈述。

这些实现未通过所有 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 上进行阅读。

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

Vim Instant-Markdown用户需要使用

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

如何将评论放在非评估,非回应 R 块中?即

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

似乎对我来说很好。

披露:我写了插件。

由于问题未指定特定的 markdown 实现,因此我想提及python-markdownComments Plugin ,它实现了与上述相同的 pandoc 评论风格。