Markdown comments are hidden notes written inside a Markdown document for editors rather than readers.

Unlike programming languages such as JavaScript or Python, Markdown does not define its own comment syntax. Instead, almost every Markdown application supports HTML comments, making them the standard way to add private notes.

Basic syntax:

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

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

For example:

# Installation

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

Follow these installation steps.

Output

The reminder stays inside the Markdown source while readers only see the heading and instructions.

Markdown comments are commonly used for TODO notes, editing reminders, collaboration, documentation reviews, and GitHub README files.

Markdown comments help keep documentation organized without displaying internal notes to readers.

They're commonly used when multiple people maintain the same Markdown files or when documentation is updated over time.

Typical use cases include:

• Adding TODO reminders
• Leaving review notes for teammates
• Tracking future updates
• Marking unfinished sections
• Planning documentation changes
• Managing GitHub README files
• Maintaining technical documentation

If the information is meant only for editors, use a hidden comment. If readers should see the information, use a visible note such as a blockquote or callout instead.

Markdown comments work by using standard HTML comments inside a Markdown document.

<!-- Your hidden comment -->

Everything between <!-- and --> is treated as a comment and is ignored when the Markdown document is rendered.

For example:

# Installation

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

Follow these installation steps.

Output

The comment remains in the Markdown source for editors but is hidden from anyone reading the rendered document.

This approach works because most Markdown parsers allow raw HTML, making HTML comments the standard way to add hidden notes in Markdown.

Related: Learn how Markdown HTML works to understand which HTML elements are supported across different Markdown implementations.

Markdown supports both single-line and multi-line HTML comments.

Single-Line Comments#

Use a single-line comment for short reminders or TODO notes.

<!-- TODO: Replace the screenshots before release -->

Common uses include:

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

Multi-Line Comments#

Use a multi-line comment when you need to leave more detailed instructions.

<!--
Update this guide after version 4.0.

Add Windows installation examples.

Review all download links.
-->

Multi-line comments are useful for:

• Documentation planning
• Team collaboration
• Draft content
• Release checklists
• Technical review notes

Choose single-line comments for short notes and multi-line comments when additional context is helpful.

Markdown comments are most useful when you're writing or maintaining documentation that other people will edit. They let you keep notes in the source file without affecting the rendered output.

Comments in GitHub README Files#

Repository maintainers often use comments to track future improvements or leave instructions for contributors.

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

# My Project

Welcome to the project documentation.

Output

The comment stays in the README source but isn't displayed on the GitHub page.

Related: Learn more about GitHub Markdown and GitHub Flavored Markdown (GFM) features.

Comments in Technical Documentation#

Documentation teams frequently use comments during drafting and review.

## Authentication

<!-- Confirm the API endpoint before publishing -->

Use your API key to authenticate requests.

Output

Comments help editors collaborate without exposing internal notes to readers.

Comments in Tutorials and Learning Resources#

When creating Markdown tutorials, comments are useful for tracking updates or reminding authors to expand examples later.

<!-- Add more beginner-friendly examples -->

## Creating Lists

This keeps the published guide clean while making the source file easier to maintain.

Markdown comments are most useful when information is intended for editors instead of readers.

Common use cases include:

• Adding TODO reminders
• Planning future updates
• Leaving review notes for teammates
• Marking sections that need revision
• Hiding temporary drafting notes
• Organizing large documentation projects
• Maintaining GitHub README files
• Collaborating on open-source documentation

For example:

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

Or:

<!-- Review API examples before publishing -->

Use comments only for information that should remain inside the source file. If readers need to see the message, use a visible note or blockquote instead.

Related: Markdown Blockquotes for visible notes, GitHub Markdown for README documentation, or Markdown Best Practices for writing maintainable documentation.

No. HTML comments cannot be nested inside one another.

Incorrect:

<!--

Outer comment

<!-- Inner comment -->

-->

Correct:

<!-- First comment -->

<!-- Second comment -->

Keeping comments separate avoids parsing issues and makes the Markdown source easier to maintain.

No. Markdown comments are hidden from the rendered page, but they are not hidden from the source file.

Anyone who can access the Markdown source—such as contributors on GitHub or members of your documentation team—can still read every comment.

Never store sensitive information inside comments, including:

• Passwords
• API keys
• Access tokens
• Customer information
• Internal credentials

Use comments only for documentation notes, reminders, and collaboration.

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.

Although HTML comments are widely supported, some static site generators remove comments during the build process. Always preview your final output if comment preservation matters.

Follow these recommendations when using comments in Markdown:

• Keep comments short and descriptive.
• Use comments for editor notes, not reader-facing content.
• Remove outdated TODO comments after completing the work.
• Don't overuse comments throughout the document.
• Never store passwords, secrets, or API keys inside comments.
• Preview your document before publishing to confirm comments remain hidden.

Good example:

<!-- Update screenshots after version 3.2 -->

Less helpful:

<!-- Fix later -->

Specific comments are much easier for collaborators to understand.

Assuming Markdown Has Native Comments#

Markdown has no built-in comment syntax.

Incorrect:

// This is a comment

Correct:

<!-- This is a comment -->

Forgetting to Close the Comment#

Every HTML comment must end with -->.

Incorrect:

<!-- Update this section

Correct:

<!-- Update this section -->

Using Comments for Important Reader Information#

If readers need to see the message, don't hide it in a comment.

Instead of:

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

Use a visible note or blockquote:

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

Output

Leaving Old Comments Forever#

Once a task is finished, remove the comment.

Old TODOs make Markdown files harder to maintain and confuse future contributors.

Assuming Comments Are Secure#

Comments are hidden from rendered output—not from the Markdown source.

Treat them as collaboration notes, never as a secure storage location.

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 easiest way to understand Markdown comments is to try them yourself.

Open the Markdown Editor and experiment with HTML comments while using the live preview. Add comments to headings, paragraphs, images, and code blocks to see how they behave.

Try these exercises:

• Create a single-line comment using <!-- -->.
• Add a multi-line comment with editing instructions.
• Place a comment between two headings.
• Add a comment before an image or code block.
• Compare a hidden HTML comment with a visible blockquote.
• Preview your document to confirm that comments are hidden after rendering.

For quick syntax lookup while practicing, keep the Markdown Cheat Sheet open.

Markdown doesn't include its own comment syntax, but HTML comments provide a simple and widely supported way to add hidden notes.

In this guide, you learned:

• Why Markdown uses HTML comments
• How to write single-line and multi-line comments
• Where comments work across GitHub, CommonMark, and other Markdown editors
• Common use cases for documentation and README files
• Platform compatibility and limitations
• Best practices for writing maintainable Markdown
• Common mistakes to avoid when using comments

Comments are ideal for collaboration, documentation maintenance, and keeping editing notes out of the rendered page. Just remember that comments remain part of the Markdown source, so they should never contain passwords, API keys, or other sensitive information.