How to Make Code Comments in Markdown

October 26, 2017

How to Comment a Markdown File

Markdown doesn’t include specific syntax for comments, but there is a workaround using the reference style links syntax. Using this syntax, the comments will not be output to the resulting HTML.

Here are a few examples:

    []: # (This is a comment)
    []: # "And this is a comment"
    []: # 'Also this is a comment'
    [//]: # (Yet another comment)
    [comment]: # (Still another comment)

Each of these lines works the same way:

While this is the best approach that I’m aware of, it doesn’t allow multi-line comments and each comment must appear on it’s own line.

I personally prefer to use [//]: # since, as a software developer, I tend to associate // with comment syntax.

Adding HTML Comments in Markdown

If you’d like for your comments to show up in the HTML output, a simple modified HTML comment syntaxt will work:

<!--- This is an HTML comment in Markdown -->

Unlike a “normal” HTML comment which opens with <!-- (two dashes), an HTML comment in Markdown opens with <!--- (three dashes). Some Markdown parsers support two-dash HTML comments, but the three-dash version is more universally compatible.