The quick answer: Use HTML comment syntax — <!-- your comment --> — to hide text from the rendered output. Content inside these markers is invisible to readers but remains in the source file.
Basic Syntax
<!-- This is a comment. It will not appear in the rendered output. -->
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. <!-- This part is hidden. --> Back to visible text.
Multi-Line Comments
Comments can span multiple lines:
<!--
This is a multi-line comment.
Everything between the markers is hidden.
Including this line.
-->
Everything between <!-- and --> 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:
- Most markdown renderers process the document as HTML at some point
- HTML comments are part of the HTML spec and stripped from rendered output
- 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 <!-- and --> characters, depending on the Notion version.
Discord
Discord ignores HTML entirely. An HTML comment in a Discord message renders as the literal text <!-- comment -->. 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
<!-- TODO: Add diagram for the architecture section -->
Embed work notes directly in the markdown source without polluting the rendered output.
Draft Sections
<!--
## Future Plans
- Feature X
- Feature Y (not ready to announce)
-->
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:
<!-- Temporarily hiding this section until the API is updated
## API v1 Reference
...
-->
Collaboration Notes
When multiple people edit the same markdown file (documentation, shared notes), comments let you leave instructions without them appearing in the output:
<!-- Review needed: @alice please verify this section is still accurate -->
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
<!-- This comment was never closed
An unclosed HTML comment hides everything from the opening marker to the end of the document (or until another --> appears later). Always close your comments.
Nesting Comments
HTML comments cannot be nested: <!-- outer <!-- inner --> 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 <!— using em dash instead —> 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.