Markdown Comment Generator
Write a note, pick a comment style, and copy Markdown that stays in your source file but never reaches the reader. Everything runs locally in your browser.
How do you write a comment in Markdown?
Markdown has no comment syntax of its own, so use an HTML comment: `<!-- your note -->`. Every major processor, including GitHub, GitLab and VS Code, keeps it in the source file and strips it from the rendered output. For a single line, the reference-style form `[//]: # (note)` works too.
<!-- TODO: rewrite this section before release -->
This paragraph is visible to readers.The comment vanishes from the rendered page; only the paragraph is displayed. The note stays in the raw Markdown for anyone editing the file.
Try the Markdown Comment Generator
Settings
Output
Markdown comment syntax explained
Because CommonMark never defined a comment token, every method below is a workaround that exploits something the renderer already throws away. They differ in how widely they are supported and in how visible they are in the raw source.
HTML comments (recommended)
The most portable option by a wide margin. Markdown passes raw HTML through to the renderer, and the renderer discards comments. Works in GitHub, GitLab, VS Code, Obsidian, Jekyll, Hugo, Pandoc and virtually every static site generator.
<!-- Reviewed by the docs team on 2025-05-12 -->
Install the CLI with npm.Renders as: Install the CLI with npm. The comment produces no output at all.
Multi-line comments
The same delimiters span as many lines as you need. Keep a blank line between the closing `-->` and the following paragraph so the parser does not treat them as one block.
<!--
TODO before v2:
- document the auth flow
- add a migration guide
-->
## Getting startedRenders as: a Getting started heading. Every line inside the delimiters is hidden.
Commenting out a block of Markdown
Wrapping existing Markdown in an HTML comment hides it without deleting it — the usual answer to “how do I comment out a section”. The one rule: the hidden text must not contain a double hyphen, which would close the comment early.
## Current pricing
<!--
## Legacy pricing
Removed in the 3.0 release, kept here for reference.
-->Only the Current pricing heading is rendered. The legacy section stays in the file but is invisible to readers.
Reference-style comments
An unused link definition. The parser recognises the label, finds nothing referencing it, and outputs nothing. It must sit on its own line with a blank line before it, otherwise it is treated as ordinary paragraph text.
[//]: # (Internal note: numbers come from the Q3 export)
Revenue grew 15% quarter over quarter.
[//]: # "Double quotes work as well"Only the revenue sentence is rendered. Both definition lines disappear.
Empty link comments
A variation that points the definition at an empty destination. Functionally the same as the reference style; the label can be any unused string, which some teams use to tag the comment's author.
[comment]: <> (Draft copy, do not publish)
[review-sarah]: <> (Check this claim against the changelog)
The API is backwards compatible.Renders as: The API is backwards compatible. Both labelled notes are hidden.
Obsidian and MDX comments
Two ecosystems ship their own syntax. Obsidian hides anything between double percent signs. MDX v2 parses JSX, where HTML comments are a syntax error, so you need a JSX expression comment instead.
%% Obsidian-only comment, single or multi-line %%
{/* MDX / Docusaurus comment */}Each line is hidden in its own ecosystem, and printed literally in the other — neither is portable.
Where Markdown comments work
Comment support tracks whether a platform allows raw HTML. Chat apps that strip HTML have no comment mechanism at all, so check this table before you rely on one.
| Platform | Support | Notes |
|---|---|---|
| GitHub / GitLab | Full | <!-- --> is hidden in READMEs, issues, PRs and wikis. [//]: # also works. |
| VS Code | Full | Hidden in the Markdown preview. Ctrl+/ inserts <!-- --> around the selection. |
| Obsidian | Full | Supports HTML comments plus its own %% comment %% syntax. |
| Partial | Raw HTML is disabled, so <!-- --> shows literally. Use [//]: # instead. | |
| Discord / Slack | None | No comment syntax exists; the delimiters are posted as visible text. |
| Notion | None | Pasted comment syntax becomes plain text. Use Notion's own comment feature. |
| MDX / Docusaurus | Partial | MDX v2 rejects <!-- -->. Use the JSX form {/* comment */}. |
How to add a comment in Markdown
Choose a comment method
Start with HTML comments unless you have a reason not to — they are the only form that works nearly everywhere.
Write the note
Type the reminder, TODO or reviewer note into the comment box. Line breaks are preserved for multi-line comments.
Copy the Markdown
Use the copy button to grab the generated syntax and paste it into your README, issue or documentation file.
Confirm it is hidden
Open the preview tab to verify the comment produces no visible output before you commit or publish.
Frequently Asked Questions
Does Markdown have a comment syntax?
No. Neither the original Markdown specification nor CommonMark defines a comment. Every approach in use is a workaround: HTML comments rely on the renderer discarding them, and reference-style comments rely on an unused link definition producing no output.
How do I comment out a section in Markdown?
Wrap the section in an HTML comment: put <!-- on the line before it and --> on the line after it. The content stays in the file but is not rendered. Make sure the hidden text contains no double hyphen, because that can close the comment early in strict parsers.
Are GitHub comments Markdown?
Yes. Issue comments, pull request comments, review comments and discussions on GitHub are all written in GitHub Flavored Markdown, so headings, lists, tables, task lists and code fences all work. Hidden comments inside those boxes use the same <!-- note --> syntax as READMEs.
Can I write multi-line comments in Markdown?
Yes, with HTML comments. Open with <!-- on its own line, write as many lines as you need, and close with --> on its own line. Reference-style comments do not span lines; each line needs its own definition.
Are Markdown comments visible in the source code?
Yes. Comments are hidden only in the rendered output. Anyone who opens the raw file, views it on GitHub in raw mode, or clones the repository can read them. Never put credentials or confidential information in a Markdown comment.
Which Markdown comment method has the best compatibility?
HTML comments. They work in GitHub, GitLab, VS Code, Obsidian, Pandoc, Jekyll, Hugo and most other processors. Reference-style comments are the best fallback for platforms that strip raw HTML, such as Reddit. Obsidian's %% syntax and MDX's JSX comments are ecosystem-specific.
Why is my reference-style comment showing up as text?
Link definitions are only recognised at the start of a line with a blank line separating them from surrounding paragraphs. If [//]: # (note) is indented, or sits directly under a sentence, the parser reads it as ordinary text and prints it.
Do comments work inside code blocks?
No. Markdown deliberately does not process any syntax inside fenced code blocks or inline code spans, so the delimiters appear literally. To comment code that you are displaying, use the comment syntax of that language, such as two slashes for JavaScript or a hash for Python.
How do I add a line break inside a Markdown comment?
Just press Enter. Everything between <!-- and --> is ignored by the renderer, so line breaks, indentation and blank lines inside the comment have no effect on the output and are purely for readability in the source.
Do search engines see Markdown comments?
No. The comment is removed when Markdown is compiled to HTML, so it never reaches the served page and crawlers cannot index it. An HTML comment written directly into a published HTML file is a different case: it is delivered to the browser, just not displayed.