Markdown FAQ: How do I create comments in Markdown? Especially comments that won’t appear in the generated output.
Part 1 of my answer is that technically there is no way — or at least no standard way — to create comments in Markdown documents, other than to use HTML comments like this:
<!--
this is a an html comment.
the bad part of this is that it will appear in
any document you generate from this markdown, such as if
you convert this markdown to HTML with MacDown or Pandoc.
-->
The bad part about using an HTML comment is that most Markdown-to-HTML conversion tools keep those comments in the output you generate. I know that Pandoc and MacDown will both include your comments in the HTML output they generate.
Solution: A trick to create Markdown comments
Part 2 of the answer is that a user on Stack Overflow came up with this way to create Markdown comments that won’t appear in generated output:
[//]: # (This syntax works like a comment, and won't appear in any output.)
[//]: # (It’s a little bizarre, but it works with MacDown and Pandoc.)
As they note on that SO page, this approach uses an “unintended side effect of the use of YAML for metadata, but it works.”
This syntax is ugly and I’ll never remember it, but I guess that’s what macros are for. I’ve read that some people have no idea why someone would want to create comments in Markdown text, and to that I reply, “Try writing a book.”
As a summary, I can confirm that this fake Markdown comment syntax works with both MacDown and Pandoc. When I put comments like this in my Markdown source, they do not end up in my generated HTML or LaTeX output, which is what I want.
