How to Write Comments in Markdown
By the MDConverter team · Updated · 2 min read
Quick answer
The most widely supported way to comment in Markdown is an HTML comment: <!-- your note -->. It can span several lines and is hidden from the rendered page on GitHub, GitLab, VS Code and most site generators — but it stays in the generated HTML, so do not use it for secrets. Where HTML is stripped, the [//]: # (note) link-definition trick hides a single line, and Obsidian has its own %% comment %% syntax.
HTML comments (works almost everywhere)
Everything between <!-- and --> is left out of the rendered page.
Visible paragraph.
<!-- TODO: add the pricing table before launch -->
<!--
Multi-line comments work too.
None of this appears.
-->
Another visible paragraph.Visible paragraph.
Another visible paragraph.
Caveat: the comment is still in the HTML source of the page, so anyone who views the source can read it. Remove passwords, internal notes and personal data before publishing.
The link-definition trick
A reference-link definition that nothing uses is never rendered — and unlike an HTML comment, it does not reach the HTML output at all. Put it on its own line with a blank line above it.
Visible text.
[//]: # (This line is a comment and is not rendered.)
[comment]: <> (So is this one.)
More visible text.Visible text.
More visible text.
).Obsidian comments
Obsidian hides anything between double percent signs in reading view: %% this is a comment %%, inline or across several lines. Other apps show the %% text, so use HTML comments in files you publish elsewhere.
Useful things to put in comments
- TODO notes and review remarks while drafting
- Instructions for contributors (
<!-- Keep this list alphabetical -->) - Separators between two lists that would otherwise merge (an empty
<!-- -->between them) - Markers that tools read: TOC generators, linters (
<!-- markdownlint-disable MD013 -->) and GitHub issue templates all use HTML comments
Comments when converting
Markdown to Word and Markdown to plain text drop HTML comments, so internal notes do not end up in the document you send. Markdown to HTML keeps them as HTML comments — remove them first if the HTML will be published. Markdown to PowerPoint reads <!-- notes: … --> comments as speaker notes.
Comment support by app
| App | Supported | Notes |
|---|---|---|
| GitHub / GitLab | Yes | HTML comments and the [//]: # trick are hidden. |
| VS Code, MkDocs, Hugo, Jekyll | Yes | HTML comments hidden (but present in built HTML). |
| Obsidian | Yes | %% … %% and HTML comments are hidden in reading view. |
| Reddit, Discord, Slack | No | Comments are shown as text; do not paste notes into messages. |
Common mistakes and how to fix them
| Problem | Fix |
|---|---|
| The comment appears on the page | Check the closing --> and that there is no space in <!--. Some chat apps do not support comments at all. |
[//]: # comment is visible | It needs a blank line above it and must start at the beginning of the line. |
| A private note was published | HTML comments are in the page source. Delete sensitive notes before publishing rather than commenting them out. |
Tools for this
Frequently Asked Questions About Comments & hidden text
Comprehensive answers to common technical, formatting, security, and compatibility questions.
Related reading
- Markdown Escape Characters: How to Show *, _, # and | Literally — Show *, _, #, | and other symbols literally — with a free escape and unescape tool.
- Markdown Front Matter: YAML Metadata at the Top of a File — The --- YAML block at the top of a file: syntax, common fields and how tools use it.
- Markdown vs HTML: What Is the Difference? — How Markdown relates to HTML, what each can do, and when to mix them.