How to Add Comments in Markdown (That Never Render)

Quick answer

Markdown has no built-in comment syntax. Writers get around that with two tricks that reliably hide text from the rendered output. First, an HTML comment: <!-- this text is hidden -->. Second, a link-reference line: [//]: # (this text is hidden). Both leave a note in your source file that a reader never sees. CommonMark's spec never added a dedicated comment syntax — the format stays deliberately small — so both tricks work by repurposing rules built for something else entirely. Here's how each one works, where each breaks, and which to reach for.

Step-by-step

Method 1 — the HTML comment

Wrap the text you want hidden between <!-- and -->:

<!-- this text is hidden from the rendered page -->

This works because CommonMark and GitHub Flavored Markdown both pass raw HTML straight through to the renderer untouched, and browsers ignore standard HTML comments when rendering a page. The content between the delimiters never shows up on screen — only in the page's source. GitHub Docs confirms this directly: content inside an HTML comment stays hidden from the rendered Markdown.

The syntax has a few restrictions worth knowing. A comment can't start with > or ->, can't contain --> anywhere inside it, and can't nest — the first --> the parser finds closes the comment, even if you meant it as plain text. It can span multiple lines, though, which is handy for disabling an entire block without deleting it:

<!--
This whole paragraph, including the list below,
is disabled while I rewrite this section.

- old point one
- old point two
-->

Method 2 — the link-reference trick

The second method abuses a different rule. A line matching [label]: target gets parsed as a link-reference definition, and a link-reference definition produces no visible output on its own. Point the "target" at something harmless like #, and the whole line vanishes:

[//]: # (this text is hidden from the rendered page)

Any label works in place of // — [comment]: # (note to self) behaves the same way. Leave a blank line before it so the parser reads it as its own block, not part of the previous paragraph. It's the same reference-style construct behind building a table of contents with anchor links: Markdown reuses that "define something, render nothing" mechanic in more than one place.

Common problems and fixes

My HTML comment showed up in the exported file. Some Markdown-to-HTML and Markdown-to-LaTeX converters copy the comment's text straight into the generated output instead of stripping it — certain Pandoc and MacDown configurations do exactly this. If your export path leaks HTML comments, switch to the link-reference trick. It produces no output in any CommonMark-compliant renderer, export path included.

My comment broke the rest of the page. Check for a stray --> inside the comment body — that closes it early, and everything after gets treated as normal Markdown. In a link-reference comment, an unescaped bracket or parenthesis inside the hidden text can trip the parser too. See the backslash guide to escaping special characters in Markdown for the fix.

I need to hide a whole section, not just one line. Wrap the entire block — paragraph, list, or code fence — in a single multiline HTML comment instead of commenting it out line by line. Keeps the draft content intact and easy to restore later.

One thing both tricks share: hidden from the rendered page isn't the same as hidden from the file. An HTML comment still sits in the page's HTML source, and a link-reference comment still sits in the raw Markdown file. Anyone who views source or opens the file directly can read it. Neither is a place to put credentials or anything actually sensitive.

Doing this with Carets

A running "notes to self" file is exactly the kind of thing a fast, native Markdown editor should make easy — that's where Carets fits. Your files stay plain text, not a proprietary format, so an HTML comment or a link-reference line written today opens correctly in any editor or converter down the line, not just the one you wrote it in. Carets' syntax highlighting also makes a comment easy to spot at a glance against the surrounding prose, and files, projects, and tags give you a place to keep a draft-notes file next to the piece it belongs to instead of scattered across apps. Cleaning a draft up before it ships? A quick pass on keeping your Markdown consistent pairs well with clearing out old comments.

Carets is free to download on the App Store for iPhone, iPad, and Mac.

Frequently Asked Questions

Does Markdown have a built-in comment syntax?

No. CommonMark and GitHub Flavored Markdown never defined a native comment syntax — the spec's authors kept the grammar small on purpose. Everything people call a "Markdown comment" is really a side effect of another rule: raw HTML passthrough or link-reference parsing.

Will an HTML comment always stay hidden?

In a browser or any spec-compliant renderer, yes — the content between <!-- and --> is never displayed. But some Markdown-to-HTML or Markdown-to-LaTeX converters copy the comment straight into the generated file instead of stripping it, so don't assume it's safe across every export path.

Is an HTML comment safe for hiding sensitive information?

No. The comment is invisible on the rendered page, but it's still sitting in the page's HTML source — anyone who views source or inspects the page can read it. Treat it as hidden from readers, not hidden from anyone who looks.

What's the alternative if my converter leaks HTML comments?

Use the link-reference trick instead: a line like [//]: # (this is a comment) gets parsed as a link-reference definition, which produces no visible output in any CommonMark-compliant renderer. It survives converters that don't strip raw HTML.

Can I comment out a whole block of Markdown, not just one line?

Yes. HTML comments can span multiple lines, so wrapping a paragraph, list, or code fence between <!-- and --> disables the whole block without deleting it — useful for keeping a draft section around while you work on something else.

Conclusion

Reach for an HTML comment first. It's the more familiar syntax and works in nearly every renderer. Fall back to the link-reference trick only once you've confirmed your export path leaks HTML comments into the final file. Either way, the mechanic is worth remembering: Markdown hides text by reusing rules built for something else, not by giving comments a syntax of their own.