Markdown cheatsheet · Comments
How to comment in markdown
Markdown has no comment syntax of its own. But two tricks hide text from the rendered output: an HTML comment, or a link label that nothing ever uses.
HTML comments, the usual answer
Markdown passes raw HTML through, and an HTML comment is HTML that renders as nothing. Anything between <!-- and --> is dropped from the rendered output on GitHub and most other renderers.
Draft intro. <!-- rewrite this before publishing -->
Draft intro.
Comments can span multiple lines, but they do not nest: the first --> ends the comment. Avoid a bare -- inside the body too; it is invalid in XML and some parsers cut the comment short when they hit it.
The limits. A comment is hidden, not gone. It still sits in the source file, in Git history, and in anything that shows raw text: GitHub's Raw button, a code review diff, a downloaded .md. Never put secrets, credentials or private remarks about people in one.
The link-label trick
The paragraph above. [//]: # (This is a comment) The paragraph below.
The paragraph above.
The paragraph below.
That line is, technically, a link reference definition: a label (//), a destination (#), and a title (the part in parentheses). CommonMark says definitions produce no output, and since no link in the document ever uses the label, the line vanishes entirely, even from the generated HTML. Because it is pure markdown, it survives where raw HTML is disabled or stripped. Keep it on its own line with blank lines around it, and do not put unescaped parentheses inside the text.
App-specific comments
Obsidian has its own syntax: text wrapped in %% is a comment, visible only in editing view and hidden in reading view. It also works as a block across multiple lines.
This survives %%but this is hidden%% in Obsidian.
This survives in Obsidian.
It is an Obsidian extension, not markdown: GitHub and other renderers print the percent signs as ordinary text. Stick to HTML comments in files you plan to publish elsewhere. In maxdown, HTML comments disappear from the rendered view as you type; the raw syntax comes back when the cursor lands on the line, and Cmd+E switches the whole document to source mode.
Common questions
Can readers ever see my comments?
Yes. Anyone with the source file can read them: the raw file on GitHub, the repository history, an email attachment. Treat a markdown comment like a pencil note on a public draft, not a vault.
Why does my comment show as text?
Some renderers sanitize raw HTML by escaping it instead of dropping it (markdown-it does this unless you opt in with html: true), so the comment appears literally as <!-- ... -->. Use the link-label trick there; plain markdown gets past HTML sanitizers.