如何在Markdown中编写注释,即HTML输出中未呈现的文本?我在Markdown项目中没有发现任何东西。
当前回答
使用mkdocs时,添加mkdocs.yml:
- pymdownx.striphtml:
strip_comments: true
strip_js_on_attributes: false
然后在任何markdown文件中使用普通的html注释,如
<!-- this is a comment -->
将从html输出中删除。
其他回答
这项小型研究证明并完善了马格努斯的答案
最独立于平台的语法是
(empty line)
[comment]: # (This actually is the most platform independent comment)
这两个条件都很重要:
使用#(而不是<>)注释前有空行。注释后的空行对结果没有影响。
严格的Markdown规范CommonMark仅适用于此语法(而不适用于<>和/或空行)
为了证明这一点,我们将使用Alexandre Mutel的Babelmark I。该工具检查大量Markdown实现上特定源代码的呈现。
(+-通过了测试,--没有通过,?-留下一些垃圾,这些垃圾在呈现的HTML中没有显示)。
无空行,使用<>13+15-注释前空行,使用<>20+,8-注释周围的空行,使用<>20+,8-没有空行,使用#13+1?14-注释前空行,使用#23+1?4-注释周围的空行,使用#23+1?4-带有3个连字符1+2的HTML注释?25-来自chl的答案(注意这是不同的语法)
这证明了上述陈述。
这些实现未通过所有7项测试。没有机会对它们使用excluded on render注释。
cebe/markdown 1.1.0cebe/markdown markdown额外1.1.0cebe/markdown GFM 1.1.0s9e\TextFormatter(Fatdown/PHP)
对于PandocMarkdown,我使用带有注释的反引号作为内联“代码”语法的语言
`here's a comment`{=comment}
这将在所有输出中自动过滤掉。它只是重载它们的代码语法,也适用于多行注释的代码块。我还没有尝试过,但我猜这对非潘多克·马克顿来说不起作用。
我相信,所有先前提出的解决方案(除了那些需要特定实现的解决方案)都会导致注释包含在输出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解析器,因为它是核心规范的一部分。(即使定义了多个链接时的行为,或定义了链接但从未使用时的行为也未严格指定)。
对于pandoc,一个阻止评论的好方法是使用yaml元块,正如pandoc作者所建议的那样。我注意到,至少在我的环境中(vim、vim-pandoc和vim-pandocsyntax),与许多其他建议的解决方案相比,这为注释提供了更恰当的语法高亮显示。
我将yaml块注释与html内联注释结合使用,因为html注释不能嵌套。不幸的是,在yaml元块中没有块注释的方法,所以每一行都必须单独注释。幸运的是,软包装的段落中应该只有一行。
在我的~/.vimrc中,我为块注释设置了自定义快捷方式:
nmap <Leader>b }o<Esc>O...<Esc>{ji#<Esc>O---<Esc>2<down>
nmap <Leader>v {jddx}kdd
我分别使用so、b和v注释和取消注释段落,作为我的<Leader>键。如果我需要注释多个段落,我将j,b映射到一个宏(通常为Q),然后运行<段落数><宏名>(例如(3Q)。这同样适用于取消注释。
将注释放在非eval、非echo R块中怎么样?即。,
```{r echo=FALSE, eval=FALSE}
All the comments!
```
对我来说似乎很好。