Markdown中的注释方法

Markdown中的注释方法

技术背景

在Markdown文档编写过程中，我们有时需要添加一些注释，这些注释仅供自己查看，不希望在转换后的文档中显示。然而，很多已有的注释解决方案会使注释包含在输出的HTML中，即便它们不显示。因此，找到一种严格仅为自己所用，读者无法看到（甚至通过“查看源代码”也不行）的注释方法是很有必要的。

实现步骤

利用链接标签

在Markdown核心规范中，可以利用链接标签来实现注释，例如：

1
2
3
[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.)

或者简化为：

1
[//]: <> (This is also a comment.)

为了提高平台兼容性，还可以用 # 代替 <>：

1
[//]: # (This may be the most platform independent comment)

需要注意的是，在这种注释前后插入空行很重要，因为有些Markdown解析器在定义与常规文本相邻时无法正确工作。

标准HTML标签

使用标准HTML标签进行注释：

1
2
3
4
<!---
your comment goes here
and here
-->

这种方式在使用pandoc生成TeX或HTML输出时有效。

Jekyll或Octopress

在Jekyll或Octopress中，可以使用Liquid标签：

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

Liquid标签会在Markdown处理器处理之前被解析并移除。

GitHub

在GitHub上可以使用：

1
[](Comment text goes here)

这会生成一个空链接，虽然在源代码中可见，但在GitHub上也能接受。

利用CSS隐藏注释

在CSS样式表中定义一个注释类：

1
.comment { display: none; }

然后在Markdown中使用：

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

在浏览器中，注释部分将不会显示。

Vim Instant - Markdown

Vim Instant - Markdown 用户需要使用：

1
2
3
4
5
6
7
8
9
<!---
First comment line...
//
_NO_BLANK_LINES_ARE_ALLOWED_
//
_and_try_to_avoid_double_minuses_like_this_: --
//
last comment line.
-->

Pandoc Markdown

  • 使用YAML元块进行块注释：
    1
    2
    3
    ---
    # This is a comment
    ---
  • 使用反引号加 comment 语言：
    1
    `here's a comment`{=comment}

kramdown

在kramdown（Jekyll和GitHub Pages的默认Markdown引擎）中，可以使用其扩展语法：

1
2
3
{::comment}
This text is completely ignored by kramdown - a comment in the text.
{:/comment}

核心代码

最具平台独立性的注释语法

1
2
(空行)
[comment]: # (This actually is the most platform independent comment)

多种注释示例汇总

1
2
3
4
[comment]: # (这是一个注释)
<!--- 这是一个HTML注释 -->
{% comment %} 这是Jekyll的Liquid注释 {% endcomment %}
{::comment} 这是kramdown的注释 {:/comment}

最佳实践

  • 对于通用Markdown文档，推荐使用 [//]: # (comment) 这种方式，它在大多数解析器中都能正常工作。
  • 在使用Jekyll或Octopress时，优先使用Liquid标签 {% comment %}，因为它能确保注释不被包含在输出中。
  • 当使用pandoc时，YAML元块和反引号加 comment 语言的方式是很好的选择。

常见问题

注释仍显示在输出中

  • 可能是解析器不支持所使用的注释语法，尝试更换为更通用的注释方式。
  • 检查注释前后是否缺少必要的空行，有些解析器需要空行才能正确处理注释。

不同解析器对注释的处理不一致

  • 由于Markdown没有严格统一的标准，不同解析器可能有不同的行为。可以使用像 Babelmark 这样的工具来测试注释在不同解析器中的表现，选择最适合的注释语法。