Markdown comments are hidden notes that you can add to a Markdown file without displaying them in the rendered document.

Since Markdown does not include a built-in comment feature, most people use HTML comments instead.

For example:

<!-- This is a hidden comment -->

When the Markdown file is rendered, the comment is not displayed to readers.

This makes comments useful for adding private notes, reminders, or instructions without affecting the visible content.

For example, you might leave a reminder for yourself:

<!-- Update this section after version 3.0 is released -->

Or leave instructions for your team:

<!-- Replace this screenshot after updating the user interface -->

These comments remain inside the Markdown file but are hidden from the rendered page.

For a practical introduction to Markdown fundamentals, start with Markdown Basics. For the complete formatting reference, see Markdown Syntax.

Comments help keep your Markdown documents organized, especially when you're working on large projects or collaborating with others.

Instead of creating visible notes that readers can see, you can keep important information hidden inside the document.

For example, imagine you're writing a product guide that isn't finished yet.

Without comments, you might write:

TODO: Add installation instructions.

Output

This text appears in the final document, which may look unprofessional.

A better approach is to use a hidden comment.

<!-- TODO: Add installation instructions -->

Readers won't see the note, but anyone editing the Markdown file will.

Comments are commonly used for:

• Writing reminders for yourself
• Leaving notes for team members
• Tracking unfinished sections
• Marking content that needs review
• Adding temporary instructions
• Planning future updates
• Hiding draft information
• Managing documentation projects

Using comments keeps your published documentation clean while still allowing writers to leave helpful notes.

Markdown itself does not recognize comments as part of its syntax.

Instead, most Markdown processors allow HTML comments because HTML can be included in Markdown documents.

A basic HTML comment looks like this:

<!-- This comment will not appear in the rendered page -->

When the Markdown document is rendered, the comment is ignored and only the visible content is displayed.

For example:

# Installation

<!-- Update this section after testing -->

Follow these steps to install the project.

Output

The comment remains inside the source file but is hidden from readers.

This allows writers to keep internal notes without affecting the final document.

Deep dive: Read the complete Markdown HTML guide for supported tags, GitHub restrictions, and when to use HTML inside Markdown.

Many users search for "Markdown comments" expecting a dedicated syntax. In practice, "Markdown comments" is what people call hidden notes in Markdown files — but the actual mechanism is HTML comments.

Feature	Markdown Comments	HTML Comments
Built into Markdown	❌ No	✅ Yes
Official syntax	❌ No	✅ HTML
Works in GitHub	Via HTML comments	✅ Yes
Hidden in rendered output	✅ Yes	✅ Yes
Recommended method	HTML comments	✅ Yes

There is no separate Markdown comment syntax. When documentation refers to "Markdown comments," it almost always means HTML comments embedded in a Markdown document.

The standard syntax is:

<!-- Your hidden note goes here -->

Anything between <!-- and --> is ignored when the document is rendered. This works because most Markdown parsers — including GitHub Flavored Markdown and CommonMark-compatible processors — allow raw HTML in Markdown source files.

If you need HTML for more than comments, see Markdown HTML for supported tags and platform-specific behavior.

No.

One of the biggest misconceptions is that Markdown has a built-in way to write comments.

It does not.

Unlike languages such as HTML, CSS, JavaScript, or Python, the original Markdown specification never introduced a comment syntax.

Instead, developers typically rely on HTML comments because most Markdown parsers support embedded HTML.

For this reason, you'll often see comments written like this:

<!-- Hidden comment -->

This has become the standard way to add comments in Markdown files.

Example 1: Simple Comment

<!-- This section needs more examples -->

The comment stays in the Markdown file but does not appear in the rendered document.

---

Example 2: Reminder

<!-- Update this guide after the next software release -->

This is useful when planning future updates.

---

Example 3: Team Note

<!-- Sarah: Please verify these screenshots before publishing -->

Comments make collaboration easier without exposing internal discussions to readers.

---

Example 4: Hidden TODO

<!-- TODO: Add troubleshooting section -->

Many documentation teams use comments to keep track of unfinished work.

---

Example 5: Draft Content

<!-- Draft introduction

Replace this paragraph before publishing.

-->

Longer comments can span multiple lines, making them useful for storing temporary notes or editing instructions.

Markdown comments are helpful whenever information is intended only for people editing the file.

Some common situations include:

• Planning future updates
• Leaving editing notes
• Adding TODO reminders
• Collaborating with other writers
• Reviewing documentation
• Organizing large Markdown projects
• Preparing release notes
• Maintaining GitHub README files

If readers don't need to see the information, a hidden comment is often the best solution.

For visible notes that readers should see, use Markdown Blockquotes or callout-style formatting instead of hiding content in comments.

Since Markdown does not have its own comment syntax, the standard way to add comments is by using HTML comments.

The basic syntax is:

<!-- Your comment goes here -->

Anything written between <!-- and --> is treated as a comment.

When the Markdown document is rendered, the comment is hidden from the visible page.

For example:

<!-- This section needs more examples -->

The comment stays in the source file but does not appear in the rendered output.

This is the most widely supported way to add comments in Markdown.

Single-Line Comments

Most comments are only one line long.

Example:

<!-- Review this section before publishing -->

Single-line comments are perfect for:

• Quick reminders
• TODO items
• Review notes
• Small editing instructions

They keep the Markdown file organized without interrupting the visible content.

Multi-Line Comments

Comments can also span multiple lines.

Example:

<!--
Update this section after the next release.

Add more screenshots.

Check all download links.
-->

Multi-line comments are useful for:

• Project planning
• Writing detailed notes
• Explaining future improvements
• Leaving instructions for other writers

Everything inside the comment remains hidden in the rendered document.

Comments Between Sections

A common practice is placing comments between major sections of a document.

Example:

# Installation

Installation instructions go here.

<!-- Add Linux installation steps later -->

# Configuration

Configuration instructions go here.

Output

Readers only see the headings and content. The editing note stays hidden inside the Markdown source.

Comments Around Images

Comments are often used to remind writers to replace or update images.

Example:

<!-- Replace this screenshot after updating the dashboard -->

![Dashboard](dashboard.png)

This helps documentation teams keep track of outdated screenshots.

Deep dive: Read the complete Markdown Images guide for syntax, URLs, alt text, and GitHub paths.

Comments Around Code Examples

You can also place comments before code blocks.

Example:

<!-- Verify this command before the next release -->

```bash
npm install
```

The code block appears normally, while the comment stays hidden.

This is helpful when commands may change in future versions.

Deep dive: Read the complete Markdown Code Blocks guide for fenced blocks, syntax highlighting, and GitHub behavior.

Comments in GitHub README Files

HTML comments work well in GitHub README files.

For example:

# My Project

<!-- Replace the project logo before release -->

Welcome to the project documentation.

Output

GitHub renders the README without showing the comment. This allows repository maintainers to leave notes without exposing them to visitors.

Another example:

<!-- TODO

Add badges after creating the release.

-->

Many open-source projects use comments like this to manage future improvements.

Deep dive: Read the complete GitHub Markdown guide for README structure, GFM syntax, and GitHub-specific features.

Comments in Technical Documentation

Documentation teams often use comments during the writing process.

Example:

## Authentication

<!-- Confirm API endpoint with the backend team -->

Use your API key to authenticate requests.

Output

The published documentation stays clean while editors can still see the reminder.

Comments in Markdown Tutorials

When writing tutorials, comments can store editing notes without distracting readers.

Example:

<!-- Add more examples for beginners -->

## Creating Lists

Markdown supports ordered and unordered lists.

This is especially useful for large documentation websites where pages are updated regularly.

For GitHub-specific syntax extensions, see GitHub Flavored Markdown.

Markdown comments are used in many different situations.

Leaving TODO Notes

<!-- TODO: Explain advanced options -->

Tracking Future Updates

<!-- Update this section after version 4.0 -->

Collaborating with Team Members

<!-- John: Please review this example -->

Hiding Draft Content

<!--

This paragraph is still being written.

Do not publish yet.

-->

Marking Content for Review

<!-- Needs technical review -->

Keeping Personal Notes

<!-- Remember to optimize these screenshots -->

Comments are a simple way to manage your writing process while keeping the published document clean and professional.

For task-style tracking that readers can see, consider Markdown Task Lists instead of hidden TODO comments.

No.

HTML comments cannot be nested inside other HTML comments.

Incorrect example:

<!--

Outer comment

<!-- Inner comment -->

-->

This may cause unexpected rendering or break the comment.

If you need multiple comments, write them separately.

Correct example:

<!-- First comment -->

<!-- Second comment -->

Keeping comments separate makes them easier to read and avoids parsing issues.

Comments are hidden from the rendered page, but they are not private.

Anyone who has access to the original Markdown file can read them.

For example:

• Team members can view comments in the repository.
• Anyone browsing the source file on GitHub can see HTML comments.
• Static site generators may remove comments from the final HTML, but the source Markdown still contains them.

For this reason, never include:

• Passwords
• API keys
• Access tokens
• Private customer information
• Confidential business data

Use comments only for editing notes and documentation reminders.

Markdown comments are not part of the original Markdown syntax or the CommonMark specification.

However, CommonMark allows raw HTML in Markdown documents. Since HTML comments are valid HTML, most CommonMark parsers support them.

For example:

<!-- This is a hidden comment -->

# Welcome

Output

The comment is ignored, while the heading is displayed normally.

If you're writing Markdown that follows the CommonMark specification, HTML comments are the recommended way to add hidden notes.

GitHub Flavored Markdown is based on CommonMark while adding GitHub-specific extensions such as tables and task lists.

GitHub Flavored Markdown (GFM) fully supports HTML comments.

This means you can safely use comments in:

• README files
• Repository home pages
• GitHub Wikis
• Documentation
• Pull request templates
• Issue templates
• Contributing guides

Example:

<!-- Replace this badge after the next release -->

# Awesome Project

Output

Visitors won't see the comment, but anyone editing the README can.

Many open-source projects use comments to:

• Leave TODO notes
• Organize documentation
• Plan future updates
• Hide editing instructions
• Remind contributors about pending work

If you're maintaining a GitHub project, comments are a simple way to keep the source file organized.

Deep dive: Read the complete GitHub Markdown guide for README structure, GFM syntax, and GitHub-specific features.

Most modern Markdown applications support HTML comments, but it's still useful to understand how different platforms handle them.

Platform	HTML Comments Supported	Visible in Rendered Output
GitHub	✅ Yes	❌ No
GitLab	✅ Yes	❌ No
VS Code Preview	✅ Yes	❌ No
Obsidian	✅ Yes	❌ No
CommonMark Parsers	✅ Usually	❌ No
Static Site Generators	✅ Usually	❌ Depends on the generator
Markdown Editors	✅ Most editors	❌ No

Although comments are hidden in the rendered document, they usually remain in the original Markdown source file.

Always check your publishing workflow if you're working with a static site generator or documentation platform.

Using comments correctly makes Markdown files easier to maintain, especially for long-term projects.

Keep Comments Short and Clear

A comment should explain exactly what needs attention.

Good example:

<!-- Update screenshots after redesign -->

Less helpful example:

<!-- Fix this -->

Specific comments save time for everyone working on the document.

Use Comments for Editing Notes

Comments are best used for information intended only for editors.

Examples include:

• TODO reminders
• Review notes
• Future improvements
• Editing instructions
• Internal documentation

Avoid using comments for information that readers need to see.

Remove Outdated Comments

As documentation evolves, some comments become unnecessary.

For example:

<!-- Add installation guide -->

Once you've added the installation guide, remove the comment.

Keeping outdated comments can confuse future contributors.

Don't Overuse Comments

Comments are useful, but too many can make the Markdown source difficult to read.

Instead of scattering comments on every line, use them only where they provide real value.

Use Meaningful TODO Comments

Instead of writing:

<!-- TODO -->

Write:

<!-- TODO: Add Windows installation instructions -->

A descriptive comment is much easier to understand later.

Don't Store Sensitive Information

Comments are hidden from the rendered page, but they are not secure.

Never write comments like:

<!-- API Key: abc123 -->

or

<!-- Password: mypassword -->

Anyone with access to the Markdown file can read these comments.

Only use comments for documentation-related notes.

Open the Markdown Editor to preview how comments behave before you publish.

Even experienced Markdown users sometimes make mistakes when using comments.

Here are some of the most common ones.

Assuming Markdown Has Its Own Comment Syntax

Many beginners try to write comments like this:

//
This is a comment

or

# This is a comment

Neither of these is valid Markdown comment syntax.

The correct approach is:

<!-- This is a comment -->

Forgetting to Close a Comment

An HTML comment must always end with -->.

Incorrect:

<!-- This comment never ends

Correct:

<!-- This comment ends correctly -->

An unclosed comment may cause unexpected rendering.

Using Comments for Visible Notes

If readers need to see important information, don't hide it inside a comment.

Incorrect:

<!-- Installation requires Node.js -->

Readers won't see this message.

Instead, write:

> **Note:** Installation requires Node.js.

Output

Visible notes should remain part of the documentation.

Leaving Too Many Old Comments

Over time, Markdown files can become filled with outdated reminders.

Example:

<!-- Update next month -->

<!-- Replace later -->

<!-- Temporary -->

<!-- Review -->

If the work is complete, remove the comments.

A clean source file is easier to maintain.

Assuming Comments Are Private

Comments are hidden from the rendered page, but they are still part of the Markdown source.

Anyone who can access the source file may be able to read them.

Treat comments as internal notes—not as a secure place for confidential information.

Example 1: GitHub README

<!-- Replace logo after the new branding is approved -->

# My Project

Welcome to the project.

The project visitors see a clean README, while contributors see the reminder.

Example 2: Documentation Website

## Installation

<!-- Add Docker installation steps -->

Follow these instructions to install the application.

This helps documentation teams plan future updates.

Example 3: API Documentation

<!-- Confirm endpoint with backend team -->

## Authentication

Include your API key in every request.

Comments make collaboration easier without affecting published documentation.

Example 4: Release Notes

<!-- Add version number after release -->

# Upcoming Changes

New features will be announced soon.

The editing reminder stays hidden from readers.

Example 5: Team Documentation

<!-- Emily: Please review the troubleshooting section -->

## Troubleshooting

If the application doesn't start, check the log files.

This is a common workflow when multiple writers contribute to the same documentation project.

The best way to learn Markdown comments is by writing them yourself.

Open the Markdown Editor to experiment with HTML comments while previewing the rendered output in real time. Keep the Markdown Cheat Sheet nearby for quick syntax lookup.

Try building a short document that includes:

• A single-line comment with a TODO reminder
• A multi-line comment with editing instructions
• A comment placed between two section headings
• A comment before an image or code block
• A comparison between a visible note (blockquote) and a hidden comment
• A preview check confirming comments do not appear in rendered output

Markdown does not include a built-in comment feature, but HTML comments provide a simple and widely supported way to add hidden notes.

In this guide, you learned:

• What Markdown comments are
• Why Markdown uses HTML comments
• How Markdown comments differ from HTML comments in practice
• How to write single-line and multi-line comments
• Where comments work in GitHub and CommonMark
• Best practices for using comments effectively
• Common mistakes to avoid
• Practical examples for README files and documentation
• How comments help teams collaborate on Markdown projects
• Frequently asked questions

Comments are a small but valuable feature that can make documentation easier to maintain. They allow writers to leave reminders, plan future updates, and collaborate with others without affecting the final content that readers see.

Use comments to improve your writing workflow, but remember that they are not private. Anyone with access to the original Markdown file can read them, so avoid storing sensitive information inside comments.

Continue learning Markdown with these guides:

Available now

• Markdown Basics — core concepts for beginners
• Markdown Cheat Sheet — quick syntax lookup
• Markdown Syntax — complete reference with examples
• Markdown Headings — document structure with H1–H6
• Markdown Paragraphs — blank lines and spacing
• Markdown Line Breaks — soft breaks, hard breaks, and <br> tags
• Markdown Lists — ordered, unordered, nested, and task lists
• Markdown Links — inline, reference, and relative links
• Markdown Images — syntax, URLs, alt text, and GitHub paths
• Markdown Tables — syntax, alignment, and GitHub GFM
• Markdown Code Blocks — fenced blocks and syntax highlighting
• Markdown Blockquotes — syntax, nesting, and GitHub callouts
• Markdown Horizontal Rules — section dividers with ---, ***, and ___
• Markdown HTML — use HTML tags inside Markdown documents
• Markdown Task Lists — checkbox syntax, nested checklists, and GitHub GFM
• Markdown Footnotes — references, citations, and GitHub GFM support
• GitHub Markdown — GFM syntax, README examples, and GitHub-specific features
• GitHub Flavored Markdown (GFM) — deep dive into GFM extensions and compatibility
• Markdown Emojis — Unicode emojis and GitHub emoji shortcodes
• Markdown Escaping Characters — backslash escaping for special Markdown symbols
• Markdown Comments — hidden notes with HTML comments in Markdown
• GitHub README Guide — templates, essential sections, and professional README workflows

Coming soon

• VS Code Markdown

The best way to learn Markdown comments is by writing them yourself. Open the Markdown Editor to experiment with HTML comments while previewing the rendered output in real time.