How to Add Comments in Markdown (Hide Text From Output)

Sometimes you want to leave a note in a Markdown file that readers never see. A reminder to update a figure, a draft paragraph you are not ready to publish, or instructions for a teammate. Markdown has no official comment syntax, but there are a few reliable techniques to hide text from the rendered output.

Quick Answer: To add a comment in Markdown, use an HTML comment: <!-- this text is hidden -->. It works in most Markdown renderers and keeps the text out of the visible page while leaving it in the source file. When HTML is stripped, a link label definition can serve as a fallback hidden note.

This guide covers the main methods, where each works, and which to reach for.

How Do You Write an HTML Comment in Markdown?

Because most Markdown renderers pass HTML through, the simplest comment is an HTML comment:

Visible paragraph that readers see.

<!-- This is a hidden note. It will not appear in the output. -->

Another visible paragraph.

Anything between <!-- and --> is omitted from the rendered page. You can use it inline or span it across multiple lines:

<!--
TODO: replace this section with the updated benchmark numbers
once the Q3 tests finish running.
-->

This is the method to reach for first. It is readable, widely supported, and clearly signals intent to anyone reading the source.

Where Do HTML Comments Work and Where Do They Fail?

HTML comments work wherever the renderer allows raw HTML, which is the large majority of tools, including GitHub, GitLab, and most static site generators.

They can fail in two situations:

• Sanitized environments that strip all HTML for security may remove comments along with everything else, though comments contain no visible content anyway.
• Non HTML output targets. When Markdown is converted to a format that does not use HTML comments, the behavior depends on the converter.

In practice, for documents headed to the web or a code host, HTML comments are dependable. You can confirm the behavior by rendering the file in a live editor like edtr.md and checking that the commented text never appears.

Is There a Comment Method Without HTML?

Yes. A lesser known trick uses Markdown’s link reference syntax. A link label definition that is never referenced produces no output:

[//]: # (This is a hidden comment using a link label.)

The [//]: defines a link label, and the # (...) part acts as the link target plus a title that never renders. Because nothing references the label, the whole line disappears from the output.

This method is useful when you want a comment that does not rely on HTML passthrough. It is less obvious to readers of the source, so HTML comments remain the clearer default.

When Should You Use Comments?

Comments earn their place in a few situations:

• Drafting. Park an unfinished paragraph in a comment instead of deleting it.
• Collaboration. Leave editorial notes for a reviewer that do not belong in the published text.
• Maintenance. Mark a section that needs updating with a TODO note.
• Templates. Explain how to fill in a template without those instructions showing up in the final document.

For larger team workflows, comments pair well with version control. Our guide on Markdown for team collaboration covers how teams keep shared documents clean.

A Quick Comparison

To decide which method to use:

• HTML comment clear, widely supported, the right default for most documents
• Link label trick handy when HTML is stripped or you want a non HTML option
• Plain deletion when the text truly has no future use, just remove it

Keep Your Notes Out of Sight

Hidden comments let you annotate your work without cluttering the page your readers see. Open edtr.md, add an HTML comment to a draft, and watch it stay invisible in the live preview while remaining in your source. It is a small technique that keeps your working notes and your published output cleanly separated.