Markdown Comment — How to Add Hidden Comments in .md Files

Why Comments in Markdown?

Markdown has no official comment syntax, but you often need one. Comments let you leave notes in a file without showing them to readers. Typical uses:

• TODO notes for yourself or collaborators
• Draft text you are not ready to publish
• Documentation for people editing the file, such as why a section is written a certain way
• Hiding sections temporarily without deleting them

The tricks below all work by writing something the Markdown parser accepts but does not render. Keep in mind that the text is still in the source file, so anyone who opens the raw .md can read it.

Method 1: HTML Comments

Markdown allows inline HTML, and HTML has comments. Wrap your note in <!-- and -->. This is the most widely supported method and works in almost every Markdown processor.

Single-line comment

<!-- This is a comment -->

Comment between paragraphs

This paragraph is visible.

<!-- TODO: add a screenshot here -->

This paragraph is visible too.

The comment is passed through to the generated HTML, where it stays hidden in the browser but can be seen by anyone using “View Source”.

Method 2: Link Label Hack

Markdown supports link reference definitions, which look like [label]: url "title". They define a link that you can use elsewhere in the document. If you define one and never use it, the parser removes it from the output. That makes it a handy comment.

The convention is to use // as the label and # as the URL, with the comment as the title:

[//]: # (This is a comment)
[//]: # "This is also a comment"

Both the parenthesis form and the quoted form are valid link-reference titles. Unlike HTML comments, nothing reaches the HTML output, so the note does not show up even in “View Source”. This makes it more portable in processors that strip or escape raw HTML (for example, when HTML is disabled for security).

The definition must start on its own line, with a blank line before it if it follows a paragraph.

Method 3: Link Label with a Descriptive Name

The same trick works with any label, not just //. Using a readable name such as comment or todo makes notes easier to search for.

[comment]: # (This is a comment)
[todo]: # (Add a screenshot of the settings panel)

It behaves exactly like Method 2. Just make sure the label is unique if you plan to reference links elsewhere in the document — a repeated label is ignored by CommonMark (the first definition wins), which is harmless for comments but confusing for real links.

Multi-Line Comments

HTML comments can span as many lines as you like. Everything between <!-- and --> is hidden.

<!--
This is a multi-line comment.
Nothing in here will be rendered.
- Even lists
- or **formatting**
-->

Link-label comments only cover one line each. To write a multi-line note, stack several of them on consecutive lines:

[//]: # (First line of the note)
[//]: # (Second line of the note)
[//]: # (Third line of the note)

Comments in Different Contexts

Commenting out a section

To hide a whole section temporarily, wrap it in an HTML comment. Remove the markers to bring it back.

## Features

- Dark mode
<!--
- Cloud sync (not ready yet)
- Team sharing (not ready yet)
-->
- Fast preview

Inline comments inside a paragraph

Only HTML comments can sit in the middle of a sentence. Link-label comments must be on their own line, so they cannot be used inline.

This is visible <!-- but this is not --> and this is visible again.

Comments at the start of a file

You can put an HTML comment on the first line of a file, for example a license note or an editor hint. Do not confuse this with YAML front matter: front matter (the --- block) is metadata read by static site generators and some viewers, not a comment.

<!-- Last reviewed: 2026-10-13 -->

# Project Title

If you use front matter, it must stay at the very top of the file, so put the comment after it.

Platform Support

HTML comments are the safest choice. Link-label comments are also widely supported in CommonMark-based renderers.

Note: hidden does not mean private. On GitHub, HTML comments disappear in the rendered file but can be read in the raw view, the editor, and the commit diff. Slack and other chat tools that only support a small subset of Markdown will show the comment text as-is or ignore the formatting entirely. Rendering can vary between versions, so test on your target platform before relying on it.

Common Mistakes

Not closing an HTML comment

If you forget the closing -->, the parser treats everything after the opening <!-- as part of the comment. In many renderers, the rest of your document disappears.

<!-- This comment is never closed

## This heading will be swallowed
All of the text below it vanishes too.

Using // or # as comment markers

Markdown does not borrow comment markers from programming languages. A line starting with // is just text and will be shown. A line starting with # followed by a space is a heading, not a comment.

// my note
# my note

Spaces in the link-label syntax

The link-label hack is strict. The label must be in square brackets, followed immediately by a colon. A space before the colon, or a missing space after it, can turn the whole line into visible text.

[//]: # (note)
[//] : # (note)
[ // ]: # (note)
[//]:#(note)

Also avoid the sequence -- inside an HTML comment: the HTML spec discourages it, and some parsers handle it poorly. And never put passwords, API keys, or private information in a comment — it is still in the file.

FAQ

How do I add a comment in Markdown?

Use an HTML comment: <!-- your comment -->. It works in nearly every Markdown processor and can span multiple lines. The alternative is a link-label comment on its own line: [//]: # (your comment).

Are Markdown comments visible in the rendered output?

No. Both methods are hidden when the Markdown is rendered. They are still in the source file, so anyone who opens the raw .md (or uses “View Source” for HTML comments) can read them. Do not store secrets in comments.

What is the difference between HTML comments and link-label comments in Markdown?

HTML comments are passed through to the HTML output, can span multiple lines, and can be used inline in a paragraph, but they remain visible in the page source. Link-label comments are removed by the Markdown parser and never reach the HTML, but they must be on their own line and cover only one line each.

Preview Your Markdown with MDViewer

MDViewer is a native macOS app for reading and previewing Markdown files. Double-click any .md file in Finder and see it rendered instantly — check that your comments stay hidden, along with tables, code blocks, and more. Lite is free; Pro adds editing, Git history, and PDF export.

Requires macOS 13.0 or later. Intel and Apple Silicon.