Comments in Markdown are essential for adding notes, reminders, or explanations that won’t appear in the rendered output. Unlike many programming languages, Markdown doesn’t have native comment syntax, but there are several effective methods to achieve this functionality.

In this tutorial, we’ll explore different ways to add comments to your Markdown files, from HTML comments to creative workarounds.

Method 1: HTML Comments (Most Common)

The most widely supported method for adding comments in Markdown is using HTML comment syntax. Since Markdown supports HTML, these comments work across virtually all Markdown processors.

Basic HTML Comment Syntax

<!-- This is a comment in Markdown -->

HTML comments use the <!-- to start and --> to end the comment. Everything between these tags will be invisible in the rendered output.

Multi-line HTML Comments

You can create multi-line comments for longer notes:

<!--
This is a multi-line comment
that spans several lines.
Perfect for detailed notes or documentation.
-->

Example in Context

# My Document Title

<!-- TODO: Add more examples here -->

This is visible text that will appear in the rendered output.

<!-- 
Author notes:
- Need to verify all links
- Add screenshots later
- Review for grammar
-->

More visible content continues here.

Another approach is using reference-style link syntax with undefined references. These won’t render as links since the references don’t exist.

[//]: # "This is a comment using reference links"
[//]: <> (This is another comment style)

Example Usage

[//]: # "Remember to update this section before publishing"

# Getting Started

This section explains the basics...

[//]: <> (Note: This example needs more detail)

Method 3: Invisible Unicode Characters

You can use zero-width space characters or other invisible Unicode characters, though this method is less reliable across different platforms.

​<!-- This comment uses a zero-width space at the beginning -->

Note: This method is not recommended as it can cause formatting issues and isn’t universally supported.

Method 4: Blockquotes for Visible Notes

While not true comments, you can use blockquotes for notes that should be visible but distinguished from main content:

> **Note**: This is a visible comment that appears in the rendered output
> but is visually distinct from the main text.

This renders as:

Note: This is a visible comment that appears in the rendered output
but is visually distinct from the main text.

For more information on blockquotes, check out our comprehensive guide to blockquotes in Markdown.

Best Practices for Markdown Comments

1. Use HTML Comments for True Comments

When you need comments that are completely invisible in the output, stick with HTML comment syntax:

<!-- This won't appear in the rendered version -->

2. Be Descriptive

Write clear, descriptive comments that explain the purpose:

<!-- Section for user authentication examples - update after API changes -->

3. Use Comments for TODOs and Reminders

<!-- TODO: Add code example for error handling -->
<!-- FIXME: This section needs better organization -->
<!-- NOTE: Double-check these statistics before publishing -->

4. Comment Out Sections Temporarily

Use comments to temporarily remove content without deleting it:

<!--
## Section Under Review

This entire section is temporarily hidden
while we verify the accuracy of the information.
-->

Platform-Specific Considerations

GitHub Markdown

GitHub-flavored Markdown fully supports HTML comments, making them invisible in rendered files, issues, and pull requests.

Static Site Generators

Most static site generators (Jekyll, Hugo, Gatsby) preserve HTML comments in the source but strip them from the final HTML output.

Documentation Platforms

Platforms like GitBook, Notion, and Confluence handle HTML comments differently:

  • GitBook: Comments are hidden in rendered output
  • Notion: Limited HTML support
  • Confluence: Comments may appear depending on settings

Common Pitfalls to Avoid

1. Nested Comments

HTML doesn’t support nested comments, so avoid this:

<!-- This is a comment <!-- This nested comment will break things --> -->

2. Comments in Code Blocks

Comments inside code blocks will be visible:

3. Special Characters in Comments

Be careful with special characters that might break the comment:

<!-- Don't use -- inside comments - it can break the syntax -->
<!-- Use &mdash; instead of -- if needed -->

Conclusion

Adding comments to Markdown files is straightforward once you know the right techniques. HTML comments (<!-- -->) are the most reliable method, working across virtually all Markdown processors and platforms.

Whether you’re documenting code, leaving notes for collaborators, or temporarily hiding content, these comment techniques will help you maintain clean, well-documented Markdown files.

Remember that the visibility of comments depends on your specific Markdown processor and rendering platform, so always test your comments in your target environment to ensure they behave as expected.