MarkdownForge

Markdown comments

Markdown has no comment syntax, but an HTML comment <!-- like this --> is hidden in almost every renderer.

Visible paragraph.

<!-- This note is hidden in the output. -->

[//]: # (This is hidden too, using an unused link label.)

Another visible paragraph.

HTML comments

<!-- note --> works in GitHub, GitLab, most static site generators and this site’s editor. It can span multiple lines. Leave a blank line before and after so it is treated as its own block.

The link-label trick

[//]: # (comment) is a reference-link definition with label // and URL #. Definitions never render, so the text disappears, and unlike an HTML comment it is not passed into the HTML at all. It must be on its own line with a blank line before it.

Hidden is not secret

HTML comments are removed from the rendered view but stay in the page’s HTML source on most sites, and everything stays in the .md file. Never put passwords or private notes in comments.

Where comments are used

  • Markers for generated content, such as <!-- toc --> that the formatter uses to update a table of contents.
  • Instructions in issue and pull-request templates.
  • Notes to co-authors in docs.

Quick answers

How do I comment in Markdown?
Use an HTML comment: <!-- your note -->.
Are Markdown comments visible to readers?
Not in the rendered page, but they are in the source file and usually in the page’s HTML source.