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.

Territorial

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

See also how MultiMarkdown supports metadata. – Dilisio

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

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. – Drain

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

Bezoar

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

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

To be most platform-independent it also needs an empty line before the comment. See the tests: https://mcmap.net/q/44961/-comments-in-markdown – Lathan

Can this be used for multiline comments? – Patrilineage

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

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. – Unstable

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

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

This is the result in babelmark – Estren

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) – Colbycolbye

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> – Pumping

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 – Ibex

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

@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? – God

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

In Rstudio if you want to add more than one coment without a warning on knitting, I had to enumerate the comments [//1]: # (all the text) – Buckskin

I agree that [this is a comment]:: works best for me, especially if you have rounded brackets ` ()` in your comment: brackets don't work with GitHub Markdown and [//]: # (This may be the most platform independent comment), you'd have to quote them and this becomes ugly. – Dillon

as of 2023-03-31, tested these on gatsby with "@mdx-js/react": "^2.3.0", "gatsby-plugin-mdx": "^5.8.0" , none of these syntax worked. both are shown even in the rendered page. – Ouellette

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

Dimitry

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

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. – Workmanlike

@Workmanlike 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). – Dimitry

@Dimitry 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. – Workmanlike

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

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

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

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

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

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

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

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

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

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. – Criminality

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

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 --> – Metacarpal

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". – Marlborough

Answer 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 Babelmark I, by Alexandre Mutel. This tool checks the rendering of particular source code on a large number of 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)

Lathan

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. – Altercate

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

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

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

What does it say about markdown that Bablemark2 exists? – Tahitian

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

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

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? – Ironing

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

A note for Jupyter IPython Notebook users: from this, comments in Markdown cells require (a) blank line before the comment; (b) the parenthesis or quotes around the comment: (comment) or "comment"; (c) no exclamation mark is required before [//] (or [comment]); (d) the colon is required. i.e., [//]: # (comment). If you get it right, all text after [//]: will turn red. – Paleography

@JacobLee It does have significance. This hack is taking advantage of link reference definition syntax and the fact that LRDs don't themselves render as anything. But if a reference link occurs anywhere in the doc with the same text as link label, it results in a link being rendered, which you don't want for a comment. So it's much safer to use [//] than [comment]. – Trichomoniasis

Please mention, that within the comment text, no brackets (( )) can be used, however { } or [ ] is ok. – Conceit

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

Dale

Jinja2 = {# multiline comments here #} – Rebak

This works for me. Thanks. I use jekyll – Giffin

Answer 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
[whatever]: # whatever with spaces

Macintosh

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

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. – Toxicosis

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

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

2022 now. Testing in VSCode with side by side md viewer, this does not allow spaces between words. '[whatever]: whatever' works but '[whatever]: whatever foo' does not. If I add the '#' then it allows spaces. '[whatever]: # whatever foo bar' works. – Masha

Adding a url to the whatever comment makes it appear in vscode preview. So I'm just using the html standard <!-- reference: https://www.example.com --> – Jugglery

Answer 6

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.

Hammad

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

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. – Cherriecherrita

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

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

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. – Ivanovo

Answer 7

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

Schaefer

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. – Tema

@Tema also the accessibility for this would be terrible – Quiver

Accessibility supporting engines will properly skip display: none text. – Unpredictable

Answer 8

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

Allelomorph

Answer 9

<!--- ... --> 

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.

Rosaline

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

Works fine on markdown extension for atom.io – Civilization

Answer 10

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.

Slung

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. – Stocktaking

Answer 11

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.

Coulter

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! – Taintless

Answer 12

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.

Ratal

Answer 13

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.

Brython

Answer 14

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.

Sacellum

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

Answer 15

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

[whatever]: text

And because Jekyll uses the Liquid templating language to process templates, also this Liquid comment will be not rendered on a GitHub Pages site with Jekyll

{% comment %}
This is a long comment string 

Newline

Stuff
{% endcomment %}

Outlier

Answer 16

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.

Unstable

Answer 17

You can try

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

Sestertium

Answer 18

You can do this (YAML block):

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

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

Celebrated

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. – Floorman

Answer 19

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.

Codger

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

Answer 20

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

Caw

Answer 21

Pandoc has an option --strip-comments that will remove all <!-- normal html comments --> from the HTML output.

https://pandoc.org/MANUAL.html#general-writer-options

Felipe

Worked great for me, thank you. One can equivalently add strip-comments: true in the YAML header. – Vic

Answer 22

If it's in VS Code, then there's another good option:

<span hidden> Some texts </span>

This has the advantage over the "HTML comment tag" of keeping syntax highlighting in the editing area, plus the ability to add attributes for semantic markup, like <span notice hidden>.

Caution: As a matter of common sense, do not include personal information in your source code.

Prospectus

Answer 23

Edit -> Toggle Line Comment Cntrl+/

Mirthamirthful

Answer 24

Some Markdown Editors support: <!--COMMENT-->

Cystitis

The second-rated answer from over 12 years ago already says this. Please don't repeat answers. – Collett