Comments in Markdown
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.
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).
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.
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:
- Using
#(and not<>) - 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)
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.
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