Markdown comments
Markdown has no comment syntax. An HTML comment is the usual way to leave a note in the file that does not appear in the rendered page.
An abused link definition. It never matches a link, so nothing shows.
Why markdown has no comment of its own
Markdown was designed so the raw file reads as well as the rendered one. A comment is the opposite of that: text that is deliberately in the file and deliberately not part of the document. So there is no syntax for it, and every method below is a borrowing from somewhere else.
Some readers strip them, which is occasionally the point
Claude Code removes block-level HTML comments from a CLAUDE.md before the file reaches the model, so a note to your colleagues in one costs no context and is never read as an instruction. A comment inside a code block is kept, because there it is content rather than a note. That is a useful property to know about, and it is the exception: most renderers simply omit the comment from the output and leave it in the file.
What usually goes wrong
- Hidden is not private. The comment sits in the file in plain text, and anyone who opens the source or views the page source can read it.
- A comment inside a fenced code block is not a comment. It is code, and it renders.
- Some strict renderers escape HTML comments and print them. The link-definition trick survives those.
Where it behaves differently
It renders as written on GitHub, GitLab and VS Code preview. Everywhere else in this table it does something else, and that is worth reading before you paste.
| Platform | Behaviour |
|---|---|
| Obsidian | Also %% its own comment syntax %%. |
| Notion | Not supported. The syntax arrives as its own punctuation. |
| Discord | Not supported. The syntax arrives as its own punctuation. |
| Slack | Not supported. The syntax arrives as its own punctuation. |
For the .md file that arrives in Mail
A markdown file on a phone is the worst case: no editor, no preview, and a share sheet full of apps that want to import it into a library. The iPhone and iPad app opens it where it landed, renders it, and lets you edit and save it back.
For iPhone and iPad.