Markdown Comments: Syntax That Hides Text

Short answer: Markdown has no official comment syntax. Two workarounds hide text from the rendered output: an HTML comment, <!-- like this -->, and an unused link reference definition, [//]: # (like this). Both disappear in any CommonMark-compliant renderer, including GitHub. MDX is the exception: there you write {/* like this */}.

Here are both forms with copyable examples, how each one works under the spec, where each one breaks, and what a comment does and doesn't hide.

---

Option 1: HTML Comments

<!-- This note will not appear in the rendered document -->

# Release notes

<!--
TODO before publishing:
- check the version number
- add the migration section
-->

Version 2.0 adds offline mode.

This is the form most people reach for, and it is the one GitHub documents. GitHub's "Hiding content with comments" section says: "You can tell GitHub to hide content from the rendered Markdown by placing the content in an HTML comment."

Why it works

The CommonMark spec (version 0.31.2) defines HTML blocks, and a line that begins with <!-- starts one. The block ends on the line that contains -->. An HTML block "is treated as raw HTML (and will not be escaped in HTML output)", so the comment is passed through to the HTML, and the browser does not display HTML comments.

That has three practical results:

• Multi-line comments work. Everything from <!-- to the line containing --> is one block, so you can comment out a whole section.
• Inline comments work too. CommonMark also allows raw HTML inline, and an HTML comment is one of the allowed forms, so Ship on Friday <!-- or Monday? --> after review. renders as "Ship on Friday after review."
• The comment can still be in the HTML. A renderer that follows the spec passes the block through rather than removing it, so it can show up when someone views the page source in a browser. Some renderers drop comments entirely.

Where it breaks

• Indented by four spaces: the spec turns a line indented four spaces into a code block, so an indented <!-- foo --> is shown as literal text in a code block. Keep comments at the left margin.
• Inside a code block: a comment inside a fenced code block is just code and is displayed.
• In MDX: see below.

---

Option 2: The [//]: # Link Reference Trick

[//]: # (This is a comment and will not be rendered)

[//]: # "Double quotes work too"

[comment]: <> (So does an empty destination in angle brackets)

This looks odd, but it is plain CommonMark. A link reference definition has three parts: a label in brackets, a colon and a destination, and an optional title. In [//]: # (comment):

• [//] is the label. Any label works; // is popular because it reads like a code comment.
• # is the link destination.
• (comment) is the title. The spec allows a title in double quotes, single quotes, or "between matching parentheses".

The spec states that "a link reference definition does not correspond to a structural element of a document". It only supplies a URL and title to any reference link with the same label. If nothing in the document is written as [//], the definition is used by nothing and produces no output at all. Unlike an HTML comment, it does not appear in the HTML source.

Where it breaks

• Leave a blank line before it. The spec says reference definitions "are detected when a paragraph is closed", so put one on its own line after a blank line, not straight after a line of paragraph text.
• One line per comment. For long notes, write several definitions, one per line, or use an HTML comment.
• Don't reuse the label. If the document contains a reference link with the same label as your comment (for example [comment]), that link picks up the definition. A label nobody uses, like //, avoids this.

---

Side by Side

	<!-- ... -->	[//]: # (...)
Hidden in a CommonMark renderer	Yes	Yes
Documented by GitHub for hiding content	Yes	No (works because GFM is a strict superset of CommonMark)
Spans several lines	Yes	No, one definition per line
Works in the middle of a sentence	Yes	No, must be on its own line
Present in the HTML output	Often (CommonMark passes it through); some renderers drop it	No
In MDX files	Not valid, use {/* */}	Not covered by the MDX docs, use {/* */}

If you want a quick syntax reminder for the rest of markdown, the Markdown cheat sheet covers headings, links, tables and code blocks on one page.

---

MDX Is Different: Use {/* */}

MDX files (.mdx) mix markdown with JSX, and HTML comments do not work there. The MDX documentation says: "HTML syntax doesn't work in MDX as it's replaced by JSX", and recommends JavaScript comments in braces instead:

{/* A comment that MDX will not render */}

# My page

This works because MDX expressions "can be empty or contain just a comment". If you move content between .md and .mdx files, check your comments: an HTML comment that is hidden in a .md file is not valid MDX.

---

Comments Are Hidden, Not Secret

A markdown comment hides text from the rendered view. It does not protect it.

• Anyone who opens the .md file in a text editor sees every comment.
• Anyone who can see the file's source, its raw view or its version history can read the comments, even ones you have since deleted.
• A renderer that follows CommonMark passes an HTML comment into the page's HTML, where "View Source" in a browser shows it.

Use comments for notes to yourself and to other writers: TODOs, reasons for a decision, a section you've switched off for now. Never use them for passwords, API keys, or anything you wouldn't put in the visible text.

---

How OpenMark Shows Comments

We make OpenMark, a markdown viewer and editor for Mac with a reader for iPhone and iPad, so here is how it treats both forms. OpenMark's renderer leaves out HTML comments and link reference definitions, so neither form appears in the Document view, the Finder Quick Look preview, the iPhone and iPad reader, or PDF and HTML exports. On the Mac, switch to the Markdown view (⌘⇧M) to see and edit them in the source.

OpenMark opens .mdx files but does not run MDX, so a {/* ... */} comment is shown as ordinary text in the Document view.

If you just want to check how a file with comments renders without installing anything, paste it into the online Markdown viewer.

---

Quick Reference

<!-- Single-line HTML comment -->

<!--
Multi-line HTML comment.
Hidden until the closing marker.
-->

Text with an <!-- inline --> comment.

[//]: # (Link-reference comment: produces no output)

{/* MDX comment */}

Sources: CommonMark Spec 0.31.2 (HTML blocks, link reference definitions, raw HTML), GitHub Docs: Hiding content with comments, GitHub Flavored Markdown Spec, and MDX: What is MDX?. Last reviewed: 2026-10-28.