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

User · Accepted Answer

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

User · Answer

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  lt  gt   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  lt  gt  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  lt  gt  13   15- Empty line before the comment  using  lt  gt  20   8- Empty lines around the comment  using  lt  gt  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

User · Answer

lt  ---     -- gt     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

User · Answer

The following works very well   lt empty line gt   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   lt empty line gt   whatever     whatever  whatever  whatever      whatever   whatever

User · 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

User · Answer

This works on GitHub      Comment text goes here    The resulting HTML looks like    lt a href  Comment 20text 20goes 20here  gt  lt  a gt    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

User · Answer

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  lt span class  comment  gt NOT lt  span gt  support comments  appears as follows in a BROWSER  We do support comments

User · 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  lt Leader gt b  o lt Esc gt O    lt Esc gt  ji  lt Esc gt O--- lt Esc gt 2 lt down gt  nmap  lt Leader gt v  jddx kdd   I use   as my  lt Leader gt -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  lt number-of-paragraphs gt  lt name-of-macro gt   e g   3Q   The same works for uncommenting

User · Answer

You can try       Your comments go here however you cannot leave    a blank line so fill blank lines with    Something

User · Answer

I use standard HTML tags  like   lt  --- your comment goes here and here -- gt    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

User · Answer

Vim Instant-Markdown users need to use   lt  --- First comment line        NO BLANK LINES ARE ALLOWED      and try to avoid double minuses like this   --    last comment line  -- gt

User · Answer

Also see Critic Markup  supported by an increasing number of Markdown tools   http   criticmarkup com   Comment   gt  gt   lt  lt    Lorem ipsum dolor sit amet   gt  gt This is a comment lt  lt    Highlight Comment          gt  gt   lt  lt    Lorem ipsum dolor sit amet  consectetur adipiscing elit     Vestibulum at orci magna  Phasellus augue justo  sodales eu pulvinar ac  vulputate eget nulla      gt  gt confusing lt  lt   Mauris massa sem  tempor sed cursus et  semper tincidunt lacus

User · Answer

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

User · Answer

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

User · Answer

You can do this  YAML block          This is a   multiline   comment       I tried with latex output only  please confirm for others

User · Answer

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

[syntax] Comments in Markdown

Examples related to syntax

Examples related to comments

Examples related to markdown