关于语法：Markdown中的注释


Comments in Markdown

在标记文件中存储注释的语法是什么，例如文件顶部的cvs$id$注释？我在减价项目上什么也没发现。

相关讨论

我相信所有先前提出的解决方案(除了那些需要特定实现的解决方案)都会导致注释包含在输出HTML中，即使它们没有显示出来。

如果您想要一条严格属于自己的评论(转换文档的读者不应该看到它，即使有"查看源")，您可以(ab)使用核心降价规范中提供的链接标签(用于参考样式链接)：

http://daringfireball.net/projects/markdown/syntax_link

即：

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)

为了实现最大的可移植性，在这种类型的注释前后插入一行空行是很重要的，因为当定义与常规文本冲突时，一些标记解析器无法正常工作。最近对babelmark的研究表明，前后空白行都很重要。如果前面没有空行，一些解析器将输出注释；如果后面没有空行，一些解析器将排除下面的行。

一般来说，这种方法应该适用于大多数降价解析器，因为它是核心规范的一部分。(即使定义了多个链接，或定义了但从未使用的链接时的行为也没有严格指定)。

相关讨论

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

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

注意三个破折号。其优点是在生成tex或html输出时与pandoc一起工作。更多信息可从Pandoc讨论小组获得。

相关讨论

这项小型研究证明并完善了马格纳斯的答案。

最独立于平台的语法是

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

这两个条件都很重要：

  • 使用#(而不是<>)
  • 注释前有空行。注释后的空行对结果没有影响。

    • 严格的降价规范commonmark只适用于此语法(而不适用于<>和/或空行)。

    为了证明这一点，我们将使用约翰·麦克法兰写的《巴别尔马克2》。此工具检查28个降价实现中特定源代码的呈现。

    (+通过了测试，-没有通过，?留下了一些垃圾，这些垃圾在呈现的HTML中没有显示出来)。

    • 无空行，使用<>13+，15-
    • 注释前空行，使用<>20+，8-
    • 在注释周围空行，使用<>20+，8-
    • 没有空行，使用#13+1？14
    • 注释前空行，使用#23+1？4
    • 使用#23+1，在注释周围空行？4
    • 带3个连字符的HTML注释1+2？25-从chl的答案(注意这是不同的语法)

    这证明了上述说法。

    这些实现未能通过所有7个测试。没有机会在呈现评论时使用排除项。

    • CEBE/降价1.1.0
    • CEBE/降价额外1.1.0
    • CEBE/降价gfm 1.1.0
    • s9e extformater(fatdown/php)
    相关讨论

    如果您使用的是Jekyll或Octopress，下面的方法也会有效。

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

    液体标签{% comment %}首先被解析，在降价处理器到达之前被移除。访问者试图从浏览器查看源代码时将看不到。

    相关讨论

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

    .comment { display: none; }

    然后，以下增强的降价

    We do NOT support comments

    在浏览器中显示如下

    We do support comments

    相关讨论

    这在Github上工作：

    1
    [](Comment text goes here)

    生成的HTML如下所示：

    1
     

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

    相关讨论

    另请参见批评家标记，由越来越多的降价工具支持。

    http://criticmarkup.com网站/

    1
    2
    3
    4
    5
    6
    7
    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即时降价用户需要使用

    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.
    -->
    相关讨论

    将注释放在非eval、非echo r块中如何？即。，

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

    对我来说似乎很管用。

    相关讨论

    披露：我写了插件。

    由于这个问题没有指定特定的markdown实现，我想介绍一下python markdown的comments插件，它实现了上面提到的相同的pandoc注释样式。

    1
    <!--- ... -->

    不适用于PanDoc Markdown(PanDoc 1.12.2.1)。注释仍然显示在HTML中。以下确实有效：

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

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

    对于Pandoc来说，阻止评论的一个好方法是使用yaml元块，正如Pandoc作者建议的那样。我注意到，与许多其他建议的解决方案相比，至少在我的环境中(vim、vim-pandoc和vim-pandoc-syntax中)，这提供了更恰当的语法强调注释。

    我将yaml block comments与html inline comments结合使用，因为html comments不能嵌套。不幸的是，在yaml元块中没有阻止注释的方法，因此每行都必须单独注释。幸运的是，软件段落中应该只有一行。

    在我的~/.vimrc中，我为块注释设置了自定义快捷方式：

    1
    2
    nmap <Leader>b }o<Esc>O...<Esc>{ji#<Esc>O---<Esc>2<down>
    nmap <Leader>v {jddx}kdd

    我用,作为我的键，所以,b和,v分别注释和取消注释一段。如果需要注释多个段落，我将j,b映射到宏(通常是Q)并运行(例如(3Q)。同样适用于取消注释。

    kramdown基于ruby的markdown引擎是jekyll的默认引擎，因此github页面通过其扩展语法提供了内置的注释支持：

    1
    2
    3
    4
    5
    6
    {::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{:/}

    这样做的好处是允许在线评论，但缺点是不能移植到其他降价引擎。

    你可以试试

    1
    2
    3
    4
    5
    6
    [](
    Your comments go here however you cannot leave
    // a blank line so fill blank lines with
    //
    Something
    )
    相关讨论

    github readme.md或stackoverflow答案

    对于Github自述或StackOverflow答案，我使用 作为内联注释。

    例子：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    # clone the remote repository to your local machine

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

    # change directory

    cd echebaby

    # install dependencies

    yarn install

    您可以这样做(yaml block)：

    1
    2
    3
    4
    5
    ---
    # This is a
    # multiline
    # comment
    ...

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