Comments in Markdown

1671
votes

How do you write a comment in Markdown, i.e. text that is not rendered in the HTML output? I found nothing on the Markdown project.

20
syntaxcommentsmarkdown
Reading between the lines, it seems that you want to attach metadata to your Markdown. For that reason, I'd suggest using a preprocessor that lets you add a header. For one example, see Jekyll's Front Matter. For another example, see how Basho uses Middleman for their documentation. (Note: This is not a direct answer to the question, which is why I'm sharing it as a comment.) – David J.
See also how MultiMarkdown supports metadata. – David J.
Here is a benchmark of different comments type with different parsers on Babelmark. – Ulysse BN
None of the answers on this page work consistently with all parsers. It's the ones that blithely show the contents of <!-- … --> that really leave me aggrieved. – Donal Fellows

20 Answers

1754
votes

I believe that all the previously proposed solutions (apart from those that require specific implementations) result in the comments being included in the output HTML, even if they are not displayed.

If you want a comment that is strictly for yourself (readers of the converted document should not be able to see it, even with "view source") you could (ab)use the link labels (for use with reference style links) that are available in the core Markdown specification:

http://daringfireball.net/projects/markdown/syntax#link

That is:

[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.)

Or you could go further:

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

To improve platform compatibility (and to save one keystroke) it is also possible to use # (which is a legitimate hyperlink target) instead of <>:

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

For maximum portability it is important to insert a blank line before and after this type of comments, because some Markdown parsers do not work correctly when definitions brush up against regular text. The most recent research with Babelmark shows that blank lines before and after are both important. Some parsers will output the comment if there is no blank line before, and some parsers will exclude the following line if there is no blank line after.

In general, this approach should work with most Markdown parsers, since it's part of the core specification. (even if the behavior when multiple links are defined, or when a link is defined but never used, is not strictly specified).

1177
votes

I use standard HTML tags, like

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

Note the triple dash. The advantage is that it works with pandoc when generating TeX or HTML output. More information is available on the pandoc-discuss group.

241
votes

This small research proves and refines the answer by Magnus

The most platform-independent syntax is

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

Both conditions are important:

  1. Using # (and not <>)
  2. With an empty line before the comment. Empty line after the comment has no impact on the result.

The strict Markdown specification CommonMark only works as intended with this syntax (and not with <> and/or an empty line)

To prove this we shall use the Babelmark2, written by John MacFarlane. This tool checks the rendering of particular source code in 28 Markdown implementations.

(+ — passed the test, - — didn't pass, ? — leaves some garbage which is not shown in rendered HTML).

This proves the statements above.

These implementations fail all 7 tests. There's no chance to use excluded-on-render comments with them.

  • cebe/markdown 1.1.0
  • cebe/markdown MarkdownExtra 1.1.0
  • cebe/markdown GFM 1.1.0
  • s9e\TextFormatter (Fatdown/PHP)
61
votes

If you are using Jekyll or octopress following will also work.

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

The Liquid tags {% comment %} are parsed first and removed before the MarkDown processor even gets to it. Visitors will not see when they try to view source from their browser.

30
votes

This works on GitHub:

[](Comment text goes here)

The resulting HTML looks like:

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

Which is basically an empty link. Obviously you can read that in the source of the rendered text, but you can do that on GitHub anyway.

28
votes

An alternative is to put comments within stylized HTML tags. This way, you can toggle their visibility as needed. For example, define a comment class in your CSS stylesheet.

.comment { display: none; }

Then, the following enhanced MARKDOWN

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

appears as follows in a BROWSER

We do support comments

23
votes

Vim Instant-Markdown users need to use

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

Also see Critic Markup, supported by an increasing number of Markdown tools.

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.
19
votes

The following works very well

<empty line>
[whatever comment text]::

that method takes advantage of syntax to create links via reference
since link reference created with [1]: http://example.org will not be rendered, likewise any of the following will not be rendered as well

<empty line>
[whatever]::
[whatever]:whatever
[whatever]: :
[whatever]: whatever
18
votes
<!--- ... -->

Does not work in Pandoc Markdown (Pandoc 1.12.2.1). Comments still appeared in html. The following did work:

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

Then use the +footnote extension. It is essentially a footnote that never gets referenced.

15
votes

How about putting the comments in a non-eval, non-echo R block? i.e.,

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

Seems to work well for me.

12
votes

Disclosure: I wrote the plugin.

Since the question doesn't specify a specific markdown implementation I'd like to mention the Comments Plugin for python-markdown, which implements the same pandoc commenting style mentioned above.

7
votes

kramdown—the Ruby-based markdown engine that is the default for Jekyll and thus GitHub Pages—has built-in comment support through its extension syntax:

{::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{:/}

This has the benefit of allowing in-line comments, but the downside of not being portable to other Markdown engines.

5
votes

For pandoc, a good way to block comment is to use a yaml metablock, as suggested by the pandoc author. I have noticed that this gives more proper syntax highlighting of the comments compared to many of the other proposed solutions, at least in my environment (vim, vim-pandoc, and vim-pandoc-syntax).

I use yaml block comments in combination with html-inline comments, since html-comments cannot be nested. Unfortunately, there is no way of block commenting within the yaml metablock, so every line has to be commented individually. Fortunately, there should only be one line in a softwrapped paragraph.

In my ~/.vimrc, I have set up custom shortcuts for block comments:

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

I use , as my <Leader>-key, so ,b and ,v comment and uncomment a paragraph, respectively. If I need to comment multiple paragraphs, I map j,b to a macro (usually Q) and run <number-of-paragraphs><name-of-macro> (e.g. (3Q). The same works for uncommenting.

4
votes

You can try 

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

You can do this (YAML block):

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

I tried with latex output only, please confirm for others.

1
votes

When using mkdocs, add in your mkdocs.yml:

  - pymdownx.striphtml:
      strip_comments: true
      strip_js_on_attributes: false

Then normal html comments in any markdown file, as

<!-- this is a comment -->

will be stripped from the html output.

1
votes

I wrote a little awk program to filter out between #omitbegin and #omitend markers that I add to my text. I use awk to pipe its output to a temp file that pandoc can then process. Like so:

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

Here is omit filter.awk:

/#omitbegin/ {
    insideOmit = 1;
}

! insideOmit {
    print $0
}

/#omitend/ {
    insideOmit = 0;
}
0
votes

For Pandoc Markdown, I use backticks with comment as the language like the inline "code" syntax

`here's a comment`{=comment}

This is automatically filtered out in all outputs. It's just overloading their code syntax and also works for code blocks for multiline comments. I haven't tried, but I'm guessing this doesn't work for non-Pandoc Markdown.

0
votes

This Markdown comment will be not rendered on a GitHub Pages site with Jekyll

[whatever]: text