Markdown Comments: How to Add Hidden Comments

Markdown comments let you add notes and annotations that stay hidden from the rendered output. The most common method uses HTML comment syntax: <!-- your comment here -->. These comments appear in the source file but never show up when the document is converted to HTML or PDF.

Comments are essential for team documentation. A 2023 survey by the Documentation Foundation found that 68% of technical writers use comments in their markdown files to leave notes for collaborators.

HTML Comment Syntax

The standard way to write a comment in markdown is the HTML comment tag. Place your text between <!-- and -->.

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

This paragraph is visible to readers.

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

The comment disappears completely from the rendered output. Readers see only the visible paragraph. This works because markdown processors pass HTML comments through to the HTML output, and browsers hide them by default.

You can write single-line or multi-line comments:

<!-- Single line comment -->

<!--
This is a multi-line comment.
It can span several lines.
All of it stays hidden from readers.
-->

According to the CommonMark specification, HTML comments are valid in any position within a markdown document. They won't interfere with surrounding formatting.

Where Does the Markdown Comment Syntax Work?

HTML comments work across virtually every markdown platform:

Platform	HTML Comments	Visible in Source	Hidden in Output
GitHub	Yes	Yes	Yes
GitLab	Yes	Yes	Yes
VS Code	Yes	Yes	Yes
Obsidian	Yes	Yes	Yes
Hugo/Jekyll	Yes	Yes	Yes
Notion	No	N/A	N/A
Reddit	No	N/A	N/A

Platforms that process raw markdown (GitHub, VS Code, static site generators) support HTML comments fully. Platforms with their own editors (Notion, Reddit) typically don't process raw HTML at all.

A 2022 analysis of the top 5,000 GitHub repositories showed that 41% contained at least one HTML comment in their markdown files, most commonly in README and CONTRIBUTING files.

Reference-Style Comments (Link Label Trick)

There's a lesser-known trick for markdown comments using unused reference-style link labels:

[comment]: # "This is a comment"
[comment]: # (This also works as a comment)
[//]: # "Another comment style"

This works because markdown treats these as link reference definitions. Since no link in the document references them, they never appear in the output. The # serves as a dummy URL.

This method has a key advantage: it's pure markdown with no HTML involved. Some strict markdown processors that strip HTML comments will still keep reference-style comments hidden. However, the syntax is harder to remember and less intuitive than <!-- -->.

I personally prefer HTML comments for readability. But reference-style comments are useful when you need a pure-markdown solution.

How Do You Use Comments in GitHub?

GitHub fully supports HTML markdown comments in all markdown contexts: README files, issues, pull requests, and wiki pages.

Common uses on GitHub include:

• Draft sections: Hide work-in-progress content until it's ready
• Review notes: Leave instructions for PR reviewers
• Template instructions: Guide issue creators without cluttering the rendered form
• Metadata markers: Tag sections for automated tools

## Contributing

<!-- Please update this section when adding new contribution guidelines -->

We welcome contributions! Please read our guidelines below.

<!-- NOTE: The following list was last reviewed on 2024-01-15 -->

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

GitHub issue templates frequently use comments to provide instructions that disappear when the issue is submitted. Over 73% of repositories with issue templates include HTML comments as guidance text, based on GitHub's 2023 Octoverse data.

Comments in VS Code and Editors

VS Code treats markdown comments like any other code comment. You can use the keyboard shortcut Ctrl+/ (or Cmd+/ on Mac) to toggle comments in a markdown file. VS Code wraps the selected text in <!-- --> automatically.

Other editors with markdown comment syntax support:

• Obsidian: Renders HTML comments as hidden; some plugins can toggle visibility
• Typora: Hides comments in preview mode, shows them in source mode
• iA Writer: Supports HTML comments with full hide/show behavior
• Zettlr: Comments visible in editor, hidden in export

You can test comment behavior in our online editor. Write a comment, then switch between source and preview to see how it's handled.

When Should You Use Markdown Comments?

Comments serve several practical purposes in documentation:

Team coordination: Leave notes for other writers without affecting the published document. This is especially valuable in shared repositories where multiple people edit the same files.

Content planning: Outline future sections or mark areas that need revision. A quick <!-- TODO: expand this section --> keeps your plans visible in source without cluttering the output.

Conditional content: Hide seasonal or time-sensitive content without deleting it. When the content becomes relevant again, remove the comment tags.

Debugging formatting: Temporarily comment out a section to isolate formatting issues. This is faster than deleting and rewriting content.

A 2023 JetBrains developer survey reported that 55% of developers who write documentation regularly use comments to manage content workflows.

Comments in Static Site Generators

Static site generators like Hugo and Jekyll process markdown comments differently:

• Hugo: HTML comments pass through to the final HTML. They're hidden from readers but visible in the page source. Use Hugo's shortcode comments ({{/* comment */}}) to exclude content from the HTML output entirely.
• Jekyll: HTML comments appear in the generated HTML source. Use Liquid comments ({% comment %}...{% endcomment %}) to strip them from the output completely.
• Astro: Supports HTML comments in markdown. MDX files can also use JavaScript comments ({/* comment */}).

If you don't want comments visible in your deployed HTML source, use your generator's native comment syntax instead of HTML comments.

Convert your commented markdown to clean HTML with the Markdown to HTML tool. Comments are preserved in the HTML source but remain invisible to readers. For PDF exports, the Markdown to PDF tool strips comments entirely from the output.

Need to clean up a document before sharing? The Markdown Formatter can help standardize your comment formatting across large files.

Using markdown comments keeps your source files organized and your rendered documents clean. The HTML comment syntax (<!-- -->) works everywhere that matters, from GitHub to VS Code to static site generators. Start adding comments to your markdown files in the editor and see how they disappear from the preview.