What is the syntax for storing a comment in a markdown file, e.g. a CVS $Id$ comment at the top of the file? I found nothing on the markdown project.

share|improve this question
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. Nov 26 '14 at 16:58
See also how MultiMarkdown supports metadata. – David J. Nov 26 '14 at 17:05

14 Answers 14

up vote 792 down vote accepted

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:


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)

It may also be prudent to insert a blank line before and after this type of comments, because some Markdown parsers may not like link definitions brushing up against regular text.

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

share|improve this answer
[//]: # "Comment" and [//]: # (Comment) seem to work on a wider variety of implementations, because # is a valid relative URI. GitHub, for example, rejects <>, and the entire line becomes visible. It's also worth noting that link labels often need to be separated from other content by a blank line. – Zenexer Mar 5 '14 at 0:17
# variant fails with s9e\TextFormatter (Fatdown/PHP) and cebe/markdown according to Babelmark. <> fails even in CommonMark. – Crissov Jun 10 '15 at 19:49
To be most platform-independent it also needs an empty line before the comment. See the tests: stackoverflow.com/a/32190021/2790048 – Nick Volynkin Aug 24 '15 at 19:18
Can this be used for multiline comments? – crypdick Nov 13 '15 at 21:53
@RovingRichard Yes, at least in Pandoc this works for multiline comments if there are no blank lines in the commented block (single line breaks are fine). I use Magnus' approach for block comments and chl's HTML approach for inline comments (although usually only 2 dashes). This way I can block comment out paragraphs already containing inline HTML comments. – Joel Ostblom Mar 2 '16 at 19:21

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.

share|improve this answer
If I understand correctly, the triple dash makes pandoc ignore the comment when it parses the markdown file. But if you use another markdown engine, the comment WILL show up in the generated HTML (and thus be visible with "view source"). So you have to be careful what you put in that comment ;) – cberzan Nov 2 '12 at 6:24
Can you explain how Pandoc treat the triple dashes differently from the double one? When I experimented with them, they appeared to be dealt in the same way. Also, the Pandoc user's guide just says "The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous, DZSlides, EPUB, Markdown, and Textile output, and suppressed in other formats." The triple dashes does not seem to have any higher privilege than the double ones. – dkim Nov 19 '12 at 23:41
If the triple dash is significant then these are not "standard HTML" comments. – tripleee Apr 2 '13 at 4:17
Note for Googlers: this unfortunately doesn't work in GitHub Markdown, and I ended up using Magnus's solution. – Daniel Buckmaster Sep 12 '14 at 3:05
In Feb 2016, this does work with github. – ac_fire Feb 19 '16 at 2:34

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 6 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)
share|improve this answer
Excellent, thorough testing tool! It looks like you're right that # works for all but GFM and <> works for GFM but not a couple others. Too bad GFM is both a corner case and also a very popular flavor. – hobs Nov 24 '15 at 0:26
It looks like s9e\TextFormatter works with # as of Jan 21, 2016. Cebe still does not handle it. – Troy Daniels Jan 21 '16 at 20:22

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.

share|improve this answer
Jinja2 = {# multiline comments here #} – John Mee Sep 30 '15 at 23:45
Looks ugly, but works - top! – polym Dec 2 '15 at 15:02

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

share|improve this answer
Copy/paste will likely end up copying the "commented" text as well as the regular text so be careful when using this. It could easily produce unexpected results for someone copying a block of text. – Eilon Nov 3 '14 at 23:31
@Eilon also the accessibility for this would be terrible – Booligoosh Oct 3 at 4:54

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.

share|improve this answer
It definitely is, but it's actually the only answer so far that always works on GitHub, e.g. in lists. – jomo Apr 19 '15 at 21:56
@chl's answer works on GitHub outside of lists. – Slipp D. Thompson Apr 19 '15 at 22:34
I arrived at the same solution. It's the only one I can get working for in-line comments, e.g. some text [](hidden text) blah blah. – c24w Jun 28 '16 at 21:45

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


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.
share|improve this answer
I think one of the problems with such "pseudo"-standards is that they are not portable. On some websites, these will work perfect, on others, they won't. – Willem Van Onsem Oct 3 '14 at 11:08

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.

share|improve this answer

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.

share|improve this answer
Also, feel free to do things like cat("# Some Header") within the "commented-out" code blocks and use results = "asis", and you can add whole commented-out sections to your code that can be flipped on/off by toggling eval = FALSE, since the R evaluation is done before the pandoc compilation. Thanks for the idea! – MichaelChirico Oct 7 '16 at 4:13
<!--- ... --> 

Does not work in Pandoc Markdown (Pandoc 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.

share|improve this answer
you need to edit your answer: "the markup options above" is a moving target on this website. – erreka Feb 24 '16 at 21:58

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:

This text is completely ignored by kramdown - a comment in the text.

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.

share|improve this answer

Vim Instant-Markdown users need to use

First comment line...
_and_try_to_avoid_double_minuses_like_this_: --
last comment line.
share|improve this answer

You can try

Your comments go here however you cannot leave
// a blank line so fill blank lines with
share|improve this answer

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.

share|improve this answer

protected by Community Apr 2 at 18:27

Thank you for your interest in this question. Because it has attracted low-quality or spam answers that had to be removed, posting an answer now requires 10 reputation on this site (the association bonus does not count).

Would you like to answer one of these unanswered questions instead?

Not the answer you're looking for? Browse other questions tagged or ask your own question.