Markdown Comments: 5 Proven Methods That Work (2026)

TL;DR: Markdown comments use HTML syntax (<!-- comment -->) to hide text from rendered output — but the text remains in the page source. For truly hidden comments, use the link reference hack [//]: # (comment), which strips text from all output. MDX files require JSX syntax {/* comment */} instead. Neither CommonMark nor original Markdown defines a native comment syntax.

Markdown has no comment syntax of its own. That single fact trips up thousands of developers every week, because every programming language they use has one — // in JavaScript, # in Python, /* */ in CSS. But Markdown is a formatting language, not a programming language, and the CommonMark specification (version 0.31.2) intentionally omits comments from its grammar. What it does offer is a pass-through for raw HTML, which means you can borrow HTML's <!-- --> comment syntax — with caveats that catch even experienced developers off guard.

This guide covers five proven methods for adding markdown comments: the universal HTML comment, the link reference hack, Obsidian's %% syntax, JSX comments for MDX, and template comments for static site generators. Each method has different visibility rules, parser support, and trade-offs. Pick the wrong one and your private TODO notes end up in the page source for anyone to read.

If you are new to Markdown syntax in general, start with the complete cheat sheet for the full picture. For specific formatting elements, see the text formatting guide or the code block guide.

How Do HTML Comments Work in Markdown?

HTML comments (<!-- -->) are the most widely supported method for adding markdown comments. They work in every CommonMark-compliant parser — GitHub, VS Code, Obsidian, Pandoc, kramdown, markdown-it, and Marked.js — because the CommonMark spec (Section 4.6, Type 2) treats them as raw HTML blocks that are passed through verbatim.

The syntax is identical to standard HTML:

<!-- This is a single-line comment -->

For multi-line markdown comments, open with <!-- and close with -->:

<!--
This comment spans
multiple lines and none of it
will appear in the rendered output.
-->

HTML comments work both as block-level elements (on their own lines) and inline within a paragraph:

This paragraph has <!-- a hidden note --> visible text on both sides.

Why HTML Comments Are Not Truly Invisible

The critical caveat: HTML comments are hidden from the rendered page but remain in the HTML source code. Anyone who right-clicks "View Page Source" or opens browser developer tools can read every word. This matters because developers routinely leave notes like <!-- TODO: fix the security bypass --> or <!-- Temporary hack, remove before launch --> in their Markdown files. Those notes ship directly into production HTML.

GitHub's code search does not index content inside HTML comments (GitHub Gist, Jonikarppinen), which means you cannot find them by searching — making them easy to forget and hard to audit.

When to Use HTML Comments

HTML comments are the right choice when:

• You need multi-line comment blocks
• The file is standard .md Markdown (not MDX)
• The commented text is not sensitive (no keys, no internal URLs, no harsh feedback)
• You want syntax that every team member already knows from HTML

They are the wrong choice when you need text stripped from all output — including page source. For that, use the link reference hack described in the next section.

What Is the Link Reference Comment Hack?

The link reference hack ([//]: #) is the only Markdown-native way to create comments that are completely stripped from rendered HTML output — the text does not appear in the page, the source code, or anywhere in the browser. It exploits Markdown's reference-style link syntax to create a link definition that is never referenced, so the parser silently discards it.

[//]: # (This comment is invisible everywhere)

Several syntax variants work identically:

[//]: # (Using parentheses)
[//]: # "Using double quotes"
[//]: # 'Using single quotes'
[comment]: # (Using a descriptive label)

The // label feels natural to developers because // is the single-line comment delimiter in JavaScript, C, Go, and dozens of other languages. The # is the shortest valid URL (a fragment identifier), and the parenthesized text is technically the link "title" attribute — repurposed here as the comment body.

Rules for Reliable Parsing

The link reference hack requires blank lines before and after the comment for consistent behavior across parsers (James Tharpe, It's FOSS). Without blank lines, some renderers fail to strip the text and instead display it as a broken paragraph or link:

Some paragraph text.
 
[//]: # (This works reliably with blank lines)
 
Next paragraph continues here.

This method is single-line only. Each comment line needs its own [//]: # prefix:

[//]: # (First comment line)
[//]: # (Second comment line)

HTML Comments vs. Link Reference: Which Should You Pick?

Use HTML comments for quick multi-line blocks where source visibility does not matter. Use the link reference hack when you need text to vanish completely — private review notes, draft content, or metadata that should never reach production.

How Do You Write Comments in MDX Files?

MDX files require JSX comment syntax: {/* comment */}. This is the only correct way to comment in MDX. HTML comments (<!-- -->) are deliberately unsupported — the MDX team confirmed this as an intentional design decision, not a bug.

{/* This comment works in MDX */}
 
<!-- This will BREAK in MDX -->

MDX is used by frameworks like Next.js, Gatsby, Astro, Storybook, and Docusaurus for .mdx files that combine Markdown with React components. The MDX team removed HTML comment support to make the boundary between Markdown content and JSX expressions unambiguous.

The Migration Trap: .md to .mdx

Moving files from .md to .mdx breaks every HTML comment in the document. In Gatsby specifically, HTML comments inside MDX files can leak into heading values and corrupt the table of contents. This is one of the most common migration issues when adopting MDX.

The fix is straightforward but tedious: find and replace every <!-- ... --> with {/* ... */} across all migrated files. If you use VS Code for Markdown editing, a project-wide search-and-replace handles this in seconds.

What Comment Syntax Does Obsidian Use?

Obsidian has its own proprietary comment syntax using double percent signs (%%). It supports both inline and block-level markdown comments:

This paragraph has %%an inline comment%% that is hidden in Reading mode.
 
%%
This is a block comment
that spans multiple lines.
%%

Obsidian comments are hidden in Reading and Preview modes but visible in Edit mode. They offer the cleanest syntax of any method — no angle brackets, no curly braces, just %%.

The Portability Problem

The %% syntax is Obsidian-only. No other Markdown parser recognizes it. If you open an Obsidian file in GitHub, VS Code, or any other renderer, the %% markers and comment text appear as literal visible text. For files that stay in a personal Obsidian vault, this is fine. For anything shared with collaborators or published to the web, use HTML comments or the link reference hack instead.

Obsidian also supports standard HTML comments (<!-- -->), which are hidden in preview mode and portable to other tools. If portability matters, stick with HTML comments even inside Obsidian.

How Do Static Site Generators Handle Markdown Comments?

Each static site generator has its own comment syntax that is stripped during the build process, producing cleaner output than HTML comments:

Hugo (Go Template Comments)

{{/* This comment is stripped during Hugo's build */}}

Hugo's Goldmark renderer escapes raw HTML by default, which means <!-- comments --> appear as visible text on the page unless you set unsafe = true in your Hugo config (W3Tutorials, 2024). Go template comments are the recommended alternative — they require no configuration and are stripped before any Markdown processing occurs.

Jekyll (Liquid Comment Tags)

{% comment %}
This content is hidden from Jekyll's output.
{% endcomment %}

Liquid comments are stripped before Markdown processing (Jekyll docs). The {% comment %} tag must be properly closed with {% endcomment %} — an unclosed tag causes a build failure.

Quick Reference: SSG Comment Syntax

Which Markdown Comment Method Should You Choose?

The right method depends on your toolchain, your privacy requirements, and whether the file will be shared outside your current environment. Here is a decision framework that covers the five methods:

For standard Markdown files (.md) on GitHub, GitLab, or VS Code: Use HTML comments (<!-- -->). They are universally supported, handle multi-line blocks, and every developer recognizes the syntax. Use the link reference hack ([//]: #) when you need text stripped from the HTML source as well.

For MDX files in Next.js, Gatsby, Astro, or Docusaurus: Use JSX comments ({/* */}). This is not optional — HTML comments are broken in MDX by design.

For Hugo sites: Use Go template comments ({{/* */}}). HTML comments require an unsafe config flag that most Hugo users leave disabled.

For Jekyll sites: Use Liquid comments ({% comment %}{% endcomment %}). HTML comments also work, but Liquid comments are stripped earlier in the pipeline.

For Obsidian-only vaults: Use %% for the cleanest syntax. Switch to <!-- --> the moment files leave Obsidian.

Markdown is used by 27.7% of developers as an async collaboration tool, ranking third after Jira (57.5%) and Confluence (35.3%) according to the Stack Overflow Developer Survey, 2024. With over 180 million developers on GitHub (GitHub Octoverse, 2025) writing Markdown daily, knowing the right comment syntax for your platform saves time and prevents information leaks.

What Are the Most Common Markdown Comment Mistakes?

Even developers who know the basic syntax fall into these traps. Each one has been confirmed through parser testing and community reports:

Putting Sensitive Data in HTML Comments

HTML comments stay in the page source. Credentials, internal URLs, harsh code review notes, and TODO items about security vulnerabilities all ship to production if left in <!-- --> blocks. Use [//]: # for anything you would not want a user to read.

Nesting HTML Comments

HTML does not support nested comments. This fails:

<!-- outer <!-- inner --> -->

The first --> closes the comment. The remaining --> renders as visible text. Use separate comment blocks instead.

Forgetting Blank Lines Around Link Reference Comments

The [//]: # hack requires a blank line before and after. Without them, some parsers render the comment text as a broken paragraph:

Some text.
[//]: # (This may not be stripped without blank lines)
More text.

Always add blank lines:

Some text.
 
[//]: # (This is reliably hidden)
 
More text.

Using HTML Comments in MDX

This is a breaking change that bites every team migrating from .md to .mdx. Convert all <!-- --> to {/* */} before switching file extensions. In Gatsby, unconverted HTML comments leak into heading values and table of contents.

Placing Comments Inside Markdown Structures

HTML comments inside lists, tables, or blockquotes can break formatting in some parsers. The CommonMark discussion forum documents cases where comments inside list items disrupt indentation. Test comment placement within complex structures before relying on it.

Practical Use Cases for Markdown Comments

Markdown comments are not just for hiding text — they serve specific workflow purposes that improve collaboration and document management:

• TODO markers: <!-- TODO: Add benchmark results after Q3 testing --> flags work that needs completing without cluttering the rendered document
• Draft content: Keep alternative wording or cut paragraphs in the file for reference during collaborative editing cycles
• Template placeholders: In documentation templates, comments guide authors on what to write: <!-- Describe the endpoint, including method, URL, and parameters -->
• Reviewer annotations: Team members leave feedback directly in the Markdown source without affecting the rendered output
• Conditional publishing: Comment out sections during review, then uncomment when ready to publish
• Deprecated content: Wrap old content in comments rather than deleting it, preserving history for reference

For a deeper look at what Markdown is and how it handles other formatting elements, the full syntax reference covers headings, lists, links, images, tables, and every other construct.

Preview Markdown Comments Instantly on macOS

Writing markdown comments is straightforward — verifying they are actually hidden requires a renderer. If you work on macOS and want to see exactly how your Markdown renders in real time, MacMD Viewer is a native macOS app that displays full CommonMark and GFM Markdown with live preview. Open any .md file and confirm your comments are hidden before pushing to GitHub or publishing to your site.

Download MacMD Viewer to preview Markdown files with full formatting on macOS — including comments, code blocks, tables, Mermaid diagrams, and math equations.

Frequently Asked Questions

Does Markdown have a native comment syntax?

No. The CommonMark specification and John Gruber's original Markdown (2004) define no comment syntax. HTML comments work because Markdown passes raw HTML through to the output, as documented in CommonMark Section 4.6. A community request to add comment syntax was closed without adding the feature to the spec.

How do you toggle markdown comments in VS Code?

Install the Markdown All in One extension, then press Cmd+/ (Mac) or Ctrl+/ (Windows/Linux) to toggle HTML comments on selected lines. Obsidian uses the same Cmd+/ shortcut for its %% comment syntax.

Can GitHub search find text inside HTML comments?

No. GitHub's code search does not index content within HTML comments (GitHub Gist reference). Commented-out text in READMEs, issues, and pull requests is invisible to search — making forgotten comments harder to audit.

What happens to HTML comments when converting Markdown to React?

It depends on the parser. Libraries like React Markdown may or may not pass HTML comments through depending on rehype plugin configuration. In MDX specifically, HTML comments cause build errors and must be replaced with {/* */} JSX syntax before migration.