100% private — everything runs in your browser
Markdown Comment
Write <!-- a note --> into your Markdown and it stays in the source but vanishes from the page. Edit hidden markdown comment examples live and see both sides at once.
MD Viewer Team
Visible text
A markdown comment is an HTML comment repurposed: you write <!-- your note --> in the Markdown source, and renderers hide it from the final page while keeping it in the file. The playground above shows both halves of that behavior side by side — the source pane contains the markdown comment, the preview pane does not. Edit the text inside the markers and watch the hidden text change without ever appearing in the rendered output.
Writers use a markdown comment for the things a file needs but a page must not show: review notes, TODOs, instructions for future editors, sections commented out during a rewrite, or reminders like which front-matter fields a template accepts. Because the markdown comment is plain text in the file, it survives version control, diffs, grep, and search — it is a note to collaborators, not to the renderer.
Two honest caveats come with the technique. First, a markdown comment is not private: anyone who opens the raw file or views page source sees it, so never put secrets, credentials, or unreleased announcements inside one. Second, renderers that strip all HTML will strip the comment along with it — harmless, but the note disappears earlier than expected. The examples below cover both block and inline comment forms.
Markdown comment syntax reference
| You type | What happens |
|---|---|
| <!-- note --> | A markdown comment on its own line — hidden in preview |
| Text <!-- note --> text | An inline comment hidden between visible words |
| <!-- line one line two --> | A multi-line comment spanning several source lines |
| <!-- **draft** --> | Formatting inside the comment is also hidden |
| <!-- (no closing marker) | Broken comment — the rest of the file may disappear |
How to write a markdown comment
- 1
Open with <!--
Place the opening marker where the hidden content begins — at the start of a line for a block markdown comment, or mid-sentence for an inline note.
- 2
Write your note
Anything between the markers is part of the markdown comment: plain text, Markdown formatting, even draft paragraphs. None of it renders.
- 3
Close with -->
The closing marker is mandatory. An unterminated markdown comment swallows every character after it, which is the most common way comments break a page.
- 4
Check the preview
The source pane keeps your note visible; the preview shows it gone. That split view is exactly how the markdown comment behaves in real documentation pipelines.
What a markdown comment is good for
The strongest use of a markdown comment is editorial: leaving instructions where they are needed. A template can carry <!-- Fill in the API key field below --> above each section; a changelog can keep <!-- entry drafted, pending legal review --> next to an unpublished item; a long README can comment out an obsolete section instead of deleting history. Because the text stays in the file, git blame attributes it and future editors can simply delete the markers to restore the content.
The second family of uses is structural. Commenting out a broken code fence while debugging documentation, hiding a draft table until numbers are confirmed, or marking where a generated table of contents will be inserted — all are natural markdown comment jobs. What a comment must never be is a security mechanism: the content ships inside the public file, so treat every markdown comment as published text that happens to be polite enough not to render.
Markdown comment mistakes
<!-- unterminated note
<!-- terminated note -->
A comment that never closes hides everything after it — sometimes the entire rest of the file. Always close the markdown comment.
<!--> tricky marker -->
<!-- plain note -->
Placing > immediately after <!-- ends the comment instantly and leaks the rest as visible text. Keep a space after the opening marker.
Storing API keys in comments
Keeping secrets out of Markdown entirely
A markdown comment is visible to anyone reading the raw file. Never treat it as encryption or access control.
Comments stay in your downloaded file
Copying or downloading from this page preserves the markdown comment byte-for-byte. Only the rendered output hides it — the file you save is identical to the file you opened.
Markdown comment etiquette in shared files
In a shared repository, a markdown comment is a message to the next editor, so write it for them: date it, initial it, and say what should happen next. <!-- TODO(mia): confirm pricing before Q3 launch --> outlives <!-- check this --> by a year. When the task is done, delete the whole markdown comment rather than editing it into a tombstone — history belongs to version control, not to accumulating comment sediment.
Agree on comment conventions with your team the same way you agree on heading levels. A useful split is <!-- NOTE: --> for durable context, <!-- TODO: --> for open work, and <!-- FIXME: --> for known defects in the document itself. Consistent prefixes make every markdown comment greppable, so cleanup day is a search command instead of an archaeology project.
Frequently asked questions
Sources and spec citations
“Comments must start with the four character sequence U+003C LESS-THAN SIGN, U+0021 EXCLAMATION MARK, U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS (<!--).”
“Raw HTML (and thus, HTML comments) is passed through unaltered — but the rendered output is the browser’s decision.”