How to Add Comments in Markdown
Markdown has no native comment syntax, but HTML comments do the job: <!-- your note here --> is dropped from the rendered output on platforms that parse HTML. The text remains fully visible to anyone reading the raw source file.
Platform Support
Comments earn their keep as editorial machinery: TODO notes for future edits, explanations of why a section is worded a certain way, and instructions inside templates. GitHub issue and pull request templates lean on this heavily — the prompts you see when opening a new issue ("<!-- Describe the bug and include reproduction steps -->") are HTML comments that guide the author in the editor and vanish the moment the issue renders. Comments are also the cheapest way to temporarily remove a section: wrap it in comment markers instead of deleting it, and the content stays in the file and in version control.
A comment opens with <!-- and runs until the first -->, which means it can span as many lines as you like — blank lines, Markdown syntax, even code fences inside the comment are all dropped without being parsed. Two structural rules matter. Comments do not nest: the first --> ends the comment, so commenting out a region that already contains a comment leaves the tail rendering as broken text. And avoid double hyphens (--) inside the comment body — they are invalid in strict HTML, and some processors terminate the comment early when they see them.
Know where comments leak. Chat platforms do not parse HTML, so Discord and Slack display <!-- markers and all --> as literal message text. More importantly, "hidden" only means hidden from the rendered page: anyone can click Raw on GitHub, view a file in the repository, or read the document source. Depending on the pipeline, HTML comments can also pass straight through Markdown conversion into the published page's HTML, where view-source exposes them. Treat comments as invisible-by-default, not private — credentials, internal URLs, and candid notes about clients do not belong in them.
When a platform strips or escapes raw HTML entirely, there is a pure-Markdown alternative: the link-reference trick. A line like [//]: # (This is a comment) defines a link reference that nothing in the document ever uses, and CommonMark renderers discard unused definitions completely — unlike an HTML comment, it leaves no trace even in the generated HTML source. The label can be anything ([comment]: # (note) works too), but the line must start at the left margin with blank lines around it, and the parenthesized text cannot contain unescaped parentheses. It is less readable than an HTML comment, so reserve it for environments where <!-- --> fails.
Examples
<!-- This comment will not appear in the rendered output -->Hide notes in your source using HTML comments. The text is invisible in the rendered output.
<!--
TODO: add benchmark results
TODO: verify the install steps on Windows
-->Everything between the markers is dropped, including any Markdown syntax inside.
[//]: # (This line will not render, and leaves no trace in the output HTML)An unused link reference definition is silently discarded by CommonMark renderers.
<!-- Describe the bug and include reproduction steps -->GitHub issue and PR templates use comments for prompts that disappear when the text renders.
Common Mistakes
Putting secrets or internal notes in commentsKeep sensitive content out of the file entirelyComments are hidden from rendered output only — anyone viewing the raw file, the repository, or the generated page source can read them.
<!-- outer <!-- inner --> still outer -->One comment level only — close before opening anotherHTML comments do not nest. The first --> ends the comment, and everything after it renders as visible (and broken) text.
Pasting <!-- notes --> into Discord or SlackDelete editorial notes before pasting into chat appsChat platforms do not parse HTML, so the comment markers and the note text appear literally in the message.
Platform Notes
GitHub
Comments are hidden in rendered READMEs, issues, and PRs — issue and PR templates rely on them for instructions. The Raw view still shows them to everyone.
GitLab
HTML comments are hidden in rendered Markdown across repositories, issues, and merge requests, with the same raw-source visibility caveat as GitHub.
Obsidian
HTML comments are hidden in reading view. Obsidian also has its own %%comment%% syntax, which is Obsidian-only but works without HTML.
Discord
Not supported — messages do not parse HTML, so <!-- --> and the text inside appear literally. Just remove notes before sending.
Frequently Asked Questions
How do I write a comment in Markdown?
Use an HTML comment: <!-- your note -->. On platforms that parse HTML (GitHub, GitLab, Obsidian), the comment is dropped from the rendered output.
Can a Markdown comment span multiple lines?
Yes — everything from <!-- to the first --> is hidden, across as many lines as you need, including blank lines and unparsed Markdown syntax.
Are Markdown comments private?
No. They are hidden from the rendered page but fully visible in the raw source, and they can pass through into published HTML. Never put secrets in them.
What if my platform escapes HTML comments?
Use the link-reference trick — [//]: # (your comment) — which pure Markdown renderers discard entirely, or a platform-native syntax like Obsidian's %%comment%%.
Why is my comment showing in the output?
The platform does not parse HTML (chat apps like Discord and Slack), the closing --> is missing or malformed, or a nested comment ended the outer one early.