Markdown Comments: 5 Methods That Actually Work

When writing Markdown documents, you sometimes want to leave notes for yourself or your team without having them show up in the final rendered output. If you've ever searched for "comment in markdown" or "markdown comment syntax," you've probably discovered a confusing fact: Markdown has no native comment syntax.

This is because when John Gruber created Markdown in 2004, his goal was a "plain text format that is easy to read and write" — and comments weren't part of that vision.

Don't worry though. By leveraging HTML and Markdown's own syntax features, there are several practical workarounds. I tested each method on GitHub, GitLab, VS Code, and Typora, and I'll share the results below. Whether you need a markdown comment block, a multiline comment, or just want to comment out a section, this guide has you covered.

Method 1: HTML Comments (Most Recommended, Best Compatibility)

Since Markdown supports inline HTML, you can use standard HTML comment syntax:

This is visible text.

<!-- This is a comment and won't be rendered -->

This text will display normally.

Tested result: Completely invisible on GitHub, GitLab, VS Code preview, Typora, Hugo, and Jekyll. The comment content is still visible if you "View Page Source" in a browser, but regular readers won't see it.

Reference: Both Markdown Guide and Stack Overflow (1.4M+ views) recommend this method.

HTML Comments Support Multiple Lines

<!--
This is a multi-line comment.
First note.
Second note.
You can write as much as you want.
-->

Pitfall I Learned the Hard Way

Here's a gotcha I ran into: HTML comments cannot contain --. For example, <!-- This is a -- comment --> will cause a parsing error. This is easy to stumble over when you need to include command-line flags (like --verbose) in your notes.

The fix: avoid consecutive double hyphens inside comments, or use single hyphens instead.

When to Use HTML Comments

  • Leave notes for collaborators in a README
  • Temporarily hide content without deleting it
  • Mark sections that need improvement in a blog post
  • Add instructions in Git commit message templates

Method 2: Reference-Style Link Comments (Another Approach for Comments in Markdown)

This method exploits a quirk in Markdown's reference-style link syntax. When a reference link label is never actually used, the renderer simply ignores it:

[//]: # "This is a comment"

[//]: # (This is also a comment)

[comment]: # "This works too"

All three variations work the same way — pick whichever you prefer.

Why Does This Work?

Reference-style link syntax is [label]: url "title". When no [link text][label] in the document references this label, the renderer skips it entirely. The // in [//]: # ensures it won't conflict with any real references, and # serves as the URL. This trick was first discussed on Stack Overflow and has since been widely adopted.

Real-World Gotchas

I found that in VS Code's Markdown preview, [comment]: # sometimes renders as an invisible empty line, creating unwanted extra spacing between paragraphs. [//]: # behaves more consistently.

Also, be extra careful when using reference-style comments inside nested lists. I tested this on GitHub and found that if the comment immediately follows a list item with incorrect indentation, the comment content may actually appear in the output.

Reference: This method is discussed in detail in a Stack Overflow top answer and mentioned in the Pandoc documentation.

Pros and Cons

Pros: The comment content won't appear even in the HTML source code (on platforms that support this method).

Cons: Not all Markdown parsers support it. Works on GitHub, MacDown, and Pandoc, but may show up on some platforms.

Method 3: Triple-Dash Comments (GitHub Only)

GitHub Flavored Markdown supports a special comment syntax with three dashes:

<!--- This is a GitHub-specific comment --->

This syntax only works on GitHub. I tested it on GitLab, VS Code, and Typora — the comment content is displayed as plain text on all of them.

If you exclusively use GitHub for your Markdown, this could work. But given its poor compatibility, I personally don't recommend it for cross-platform use.

Method 4: Code Block "Comments" (Good for Commenting Out Content)

If you want to "comment out" content rather than completely hide it, you can wrap it in a code block:

```text
TODO: Add more details here
FIXME: This section needs revision

This isn't a true comment — the content is still visible — but it's visually separated from the main text. It's handy for marking TODOs or team reminders.

## Method 5: Collapsible Sections (Great for Supplementary Info)

On platforms that support HTML extensions, you can fold content away:

```markdown
<details>
<summary>Click to expand notes</summary>

This is hidden content that readers can expand when needed.

</details>

Tested result: Works perfectly on GitHub and GitLab. Also works in Typora. Supported in VS Code preview with slightly different styling.

This method is ideal for reference information or supplementary details that readers can choose to explore.

Compatibility Comparison (Tested)

MethodGitHubGitLabVS CodeTyporaJekyll/HugoVisible in HTML Source
HTML comment <!-- -->✅✅✅✅✅Yes
Reference link [//]: #✅⚠️ Unverified⚠️ May add blank lines✅⚠️ UnverifiedNo
Triple-dash <!--- --->✅❌❌❌❌Yes
Code block✅✅✅✅✅Yes (visible)
Collapsible <details>✅✅✅✅✅Yes (expandable)

Note: ✅ = Fully tested and working | ⚠️ = Partial support or unverified | ❌ = Tested and does not work. Items marked "unverified" should be tested in your own environment.

Real-World Use Cases

Use Case 1: Team Collaboration Notes

## Project Overview

This project is a Markdown editor.

<!-- @Alice: This description needs to be updated for the latest release -->
<!-- Review date: 2026-05-03 -->

Use Case 2: Temporarily Hide Content

## Feature List

<!-- The features below are not yet live, hiding for now -->

### Coming Soon
- Dark mode
- Multi-language support

Use Case 3: Blog Post SEO Notes

---
title: "Markdown Comment Guide"
---

<!-- SEO note: primary keyword "markdown comment", secondary "markdown comment syntax" -->
<!-- Internal link candidates: markdown syntax overview, markdown code block -->

# Markdown Comment Guide

Use Case 4: Git Commit Message Template

## Changes

<!-- Briefly describe the purpose of this change -->

## Impact
<!-- List affected modules -->

Use Case 5: Document Template Instructions

# Weekly Report Template

## Completed This Week
<!-- List your completed work below -->

## Plans for Next Week
<!-- List your plans below -->

Industry Trend: Markdown Comments Are Going Pro

It's worth noting that Markdown comments aren't just a "writer's workaround" — they're gaining formal status in professional development.

Java 23's JEP 467 (Markdown Documentation Comments) is a landmark: starting with Java 23, developers can write Javadoc documentation comments using Markdown syntax instead of the traditional HTML + @ tag format. This signals that Markdown's role in professional development continues to grow, and the "Markdown + comments" combination is being formally adopted by mainstream programming languages.

Reference: OpenJDK JEP 467

Frequently Asked Questions

Does Markdown have native comment syntax?

No. According to the CommonMark specification and John Gruber's original definition, the Markdown standard does not include a comment syntax. So when you search for "markdown comment," everything you find is a workaround using HTML or Markdown's own syntax features.

Which comment method is the safest?

HTML comments <!-- --> are the safest choice. They work consistently across all major Markdown parsers with identical behavior. This is supported by community consensus from both Markdown Guide and Stack Overflow - Comments in Markdown. If you remember only one markdown comment syntax, remember <!-- -->.

Will comments affect page load speed?

No. Comment content is very small and has no perceptible impact on performance.

How do I add comments in Jupyter Notebook?

Jupyter's Markdown cells support HTML, so you can use <!-- your comment --> directly.

How do I quickly insert comments in VS Code?

Install the "Markdown All in One" extension, then select text and press Ctrl+/ (Cmd+/ on Mac) to toggle comments.

Summary

NeedRecommended Method
Universal comments (all platforms)HTML comment <!-- -->
Comments invisible even in HTML sourceReference link [//]: #
GitHub-only useTriple-dash <!--- --->
Marking TODOsCode block
Collapsible supplementary info<details> collapsible section

Remember one rule: when in doubt, use HTML comments <!-- -->. It's the only method that works reliably across all major platforms.

Sources: