Basic Syntax
The comment can appear anywhere in a markdown document — inline within a paragraph or as its own block-level element:
Here is some visible text. Back to visible text.
Multi-Line Comments
Comments can span multiple lines:
Everything between is hidden, regardless of how many lines or how much content is between them.
Why Markdown Has No Native Comment Syntax
The CommonMark specification — the standard that most markdown renderers follow — does not define a comment syntax. This is a deliberate design choice: markdown was originally conceived as a writing format, not a programming language.
The HTML comment () is the universally accepted workaround because:
1. Most markdown renderers process the document as HTML at some point
2. HTML comments are part of the HTML spec and stripped from rendered output
3. All major markdown tools honor them
Platform-by-Platform Breakdown
GitHub and GitLab
HTML comments are fully supported and completely hidden from rendered output. Use them for metadata, notes to collaborators, and draft sections in README files or documentation.
Obsidian
HTML comments work in Obsidian and are hidden in the preview. Obsidian also has its own native comment syntax: %% comment %%. These Obsidian-native comments are hidden in preview but are NOT standard markdown — they'll show as literal %% characters in other renderers.
Best practice: Use for cross-platform compatibility; use %% %% only for Obsidian-specific metadata you never want in other contexts.
Notion
HTML comments are not officially supported in Notion's markdown import. They may render as literal text including the characters, depending on the Notion version.
Discord
Discord ignores HTML entirely. An HTML comment in a Discord message renders as the literal text . Discord has no comment equivalent.
Slack
Same as Discord — HTML is not rendered in Slack. The comment syntax will appear as literal characters in Slack messages.
MarkdownTools (Export)
MarkdownTools strips HTML comments from both PDF and HTML exports. They won't appear in your exported documents.
Use Cases
TODO Notes
Embed work notes directly in the markdown source without polluting the rendered output.
Draft Sections
Keep unfinished or not-yet-ready content in the file without publishing it.
Disabling Sections Temporarily
Sometimes you want to hide a section rather than delete it — maybe it's outdated but you might need it again:
Collaboration Notes
When multiple people edit the same markdown file (documentation, shared notes), comments let you leave instructions without them appearing in the output:
Page Metadata
Some static site generators use HTML comments to embed metadata in markdown files. The comment is invisible to readers but machine-readable for the build system.
Common Mistakes
Comments in Discord or Slack
If you paste markdown with HTML comments into Discord or Slack, the comment markers appear as literal text. Remove comments before sharing in those contexts.
Unclosed Comment
Nesting Comments
HTML comments cannot be nested: outer --> is invalid HTML. The comment ends at the first --> it encounters.
Using -- Inside Comments
HTML comments cannot contain -- inside them (it's invalid HTML). Write or rephrase to avoid double hyphens in comment text.
Obsidian %% Comment Syntax
Obsidian adds its own comment delimiter: %% anything here %%. This works in Obsidian's editor and preview but is Obsidian-proprietary — other renderers will show the %% characters literally.
Use HTML comments () when your markdown needs to be portable. Use %% %% only for pure Obsidian vaults where portability doesn't matter.
Full reference: Markdown Comments.
Ready to put this into practice? Paste your markdown into the free MarkdownTools PDF exporter or HTML converter — no signup required.