Comments in Markdown

Question

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.

Solution 1

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

Solution 2

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.

Solution 3

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

• No empty lines, using <> 13+, 15-
• Empty line before the comment, using <> 20+, 8-
• Empty lines around the comment, using <> 20+, 8-
• No empty lines, using # 13+ 1? 14-
• Empty line before the comment, using # 23+ 1? 4-
• Empty lines around the comment, using # 23+ 1? 4-
• HTML comment with 3 hyphens 1+ 2? 25- from the chl's answer (note that this is different syntax)

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)

Solution 4

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.

Solution 5

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

View more solutions

Comments

[David J.]

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.

[Ulysse BN]

Here is a benchmark of different comments type with different parsers on Babelmark.

[Donal Fellows]

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.

[cberzan]

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 ;)

[dkim]

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.

[chl]

@dkim Comments with triple dash are ignored and discarded from the HTML output. This is not the case with double-dashed comments which are inserted in the HTML file. This is still the case with the latest version of Pandoc (1.10).

[dkim]

@chl Strange. The development version (1.10) seems to work differently from the release versions that I experimented with. With Pandoc 1.9.4.2 and 1.9.1.1 in Ubuntu 12.10 and 12.04, triple-dashed comments are inserted into the HTML output like double-dashed comments.

[tripleee]

If the triple dash is significant then these are not "standard HTML" comments.

[Zenexer]

[//]: # "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.

[Daniel Buckmaster]

Note for Googlers: this unfortunately doesn't work in GitHub Markdown, and I ended up using Magnus's solution.

[Patrick Beeson]

This is not part of the standard Markdown syntax. The answer below is a better solution.

[Willem Van Onsem]

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.

[Eilon]

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.

[Keith Pinson]

@DanielBuckmaster Maybe you have a different definition of "work" than me (i.e. all I wanted was something that didn't show when rendered, for use with Gist-vim), or maybe they've made an update since you posted, but it worked for me on Gist.

[jomo]

It definitely is, but it's actually the only answer so far that always works on GitHub, e.g. in lists.

[Crissov]

# variant fails with s9e\TextFormatter (Fatdown/PHP) and cebe/markdown according to Babelmark. <> fails even in CommonMark.

[Shadowen]

@DanielBuckmaster I suggest this solution for GitHub Pages (Jekyll) users, since it's a real comment. It's more "correct", but syntax is much wordier. Depends on how much you like/dislike exploiting the parser/doing it the right way.

[Nick Volynkin]

To be most platform-independent it also needs an empty line before the comment. See the tests: stackoverflow.com/a/32190021/2790048

[John Mee]

Jinja2 = {# multiline comments here #}

[crypdick]

Can this be used for multiline comments?

[hobs]

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.

[d9k]

This doesn't work with bitbucket (sorry if I wrong and missed something)

[Troy Daniels]

It looks like s9e\TextFormatter works with # as of Jan 21, 2016. Cebe still does not handle it.

[joelostblom]

@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.

[joelostblom]

I actually switched to using yaml metablock for block comments. This works well in pandoc and gives nicer syntax highlighting in my environment. I put down the details in a separate answer.

[c24w]

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.

[MichaelChirico]

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!

[Cyker]

Fails with kramdown if the commented part includes table syntax (|...|...|).

[Karl Giesing]

Just FYI, but if you're creating a TOC using Pandoc, this will generate a warning about duplicate link references. (These are just warnings, the TOC will still be created.)

[Asclepius]

@chl If you start with three dashes, why end with only two? Why the inconsistency?

[eloyesp]

This is the result in babelmark

[Venryx]

Just wanted to note that none of the options listed in this answer worked for this library: github.com/rexxars/react-markdown However, I was able to get it working by replacing the parentheses with quotation marks. (as mentioned in the first comment, and the other answers)

[Ethan]

@Eilon also the accessibility for this would be terrible

[filotn]

If want to keep a url link as a comment in your github wiki (edit mode: markdown) for future use, the parentheses won't work. use simple or double quotes instead: [//]: # "[link](http://example.com)" --> OK [//]: # '[link](http://example.com)' --> OK [//]: # ( [link](http://example.com) ) -->NOK : will render like this //: # ( link ) in the browser. Generated html is <p>[//]: # ( <a href="http://example.com" rel="nofollow">link</a> )</p>

[Royi]

Strangely, if the comment contains (...) by itself it breaks it. At least on Visual Studio Code 1.19.

[Simon C.]

and thus for the vim users that want to comment all a file at once: %s/^\(.*\)$/[comment]: # (\1)/g

[Seamus]

This answer works on GitHub! The other answers don't work.

[jwm]

I tried this at daringfireball.net/projects/markdown/dingus and the comment blocks render as <p> blocks. I don't know if it's related to the SmartyPants plugin or not. Update: the problem seems to be multi-line comments

[T.C. Proctor]

What does it say about markdown that Bablemark2 exists?

[anapsix]

I often write the comment inside square brackets: [Comment test]::

[dogmatic69]

This no longer works on github as of 2019-03-08, it renders as is [](Comment text goes here)

[raphink]

This works with pandoc and commonmarker, even with two dashes instead of three

[teichert]

@anapsix: your solution ([this is a comment]::) works the best for me (e.g. disappears in preview mode of vscode even when there are spaces in the comment); do you want to post it as an answer and explain why it works?

[doak]

Tested both (<!--- and <!-- variant) with pandoc (v2.5), both end in HTML as comments and are not visible in rendered view. Furthermore current upstream instances of Gitlab as well as GitHub accepts these.

[doak]

This (tested first variant) works for pandoc as well as current online instances of Gitlab and GitHub.

[ceving]

I like this best, because it does not generate any output at all. For Bitbucket this prefix is sufficient: [#]: .

[markgalassi]

I'm not sure if Daniel's confirmation of html output is correct. I did that with an html output file and ran "pandoc --bibliography paper.bib -o paper.html paper.md" and the HTML showed the comment lines.

[aredridel]

Accessibility supporting engines will properly skip display: none text.

[Blaise]

If only GitHub matters, <!-- comment --> will do just fine.

[chris]

The approach with blank line followed by currently passes all 31 flavors (to steal a phrase from Baskin-Robbins) at Babelmark. I am not a Markdown maven, but I needed comments tonight to prevent performance issues with a Markdown preview window. If you copy the entire code box here into Babelmark, none of the comments even render in the HTML. This answer needs about 1,000 more upvotes.

[Xunnamius]

Thank you for this. This is the only answer that worked across environments. I hope people scroll!

[Ivan Mir]

Great find, this commenting style works correctly in 29 parsers from the 31 available here!

[Ivan Mir]

Answer by @anapsix below is 29+, 2- without an empty line after the comment.

[Nick Volynkin]

@IvanMir Thank you! It's time to update my answer, because a lot has changed since I wrote it.

[Jacob Lee]

Just seeking clarification. The literal "comment" occurring within the brackets doesn't have any special significance, correct? For example, if I wanted it to be [note]: # (my notes ...) this would work just was well, right?

[Clint Pachl]

With kramdown 2.3.0—using inline or block comments—the comment extension outputs XML comments: echo '{::comment}secret{:/comment}' | kramdown => <p><!-- secret --></p>

[CodeFinity]

Whenever I do 'command + /' in VS Code, it adds these style of comments, so 🏃🏾‍♂️with that. 😃

[Rico Picone]

PS there's nothing special about comment ... just don't let it be html or latex or whatever your target format is.

[Andrea]

Works fine on markdown extension for atom.io

[Brandon Stivers]

I love answers that stand the test of time. Was looking for a solution to GitHub that also works in VSCode via Markdown Preview Enhanced, and low and behold, the 10-year-old answer STILL works. And why did I need an answer for it? <!-- cSpell:disable -->

[Alexander Stohr]

Please be aware that HTML comments will be part of the HTML document - and thus can be viewed by anyone, e.g. via the right click browser option "view source".

[Mikko Rantalainen]

I would recommend [comment text here]:: if you cannot use HTML-like comments <!--- and -->. Note that some markdown engines have better compatibility with tripple dash for the opening tag which is allowed in HTML too – technically the comment text just starts with a dash.

[k_o_]

At least in my case this does not work within tables.

[Manicek]

This works perfectly for GitLab. You don't even need the empty line above