How to Add Comments in Markdown

HTML comment syntax

Markdown does not define a separate comment marker. The usual approach uses the HTML comment syntax: <!-- comment text -->. Put the opening and closing delimiters around the note. The browser does not display the text in the normal page view when the comment reaches the HTML output. You can place a comment between paragraphs, after a heading, or around a block that the renderer passes through. Keep the syntax closed correctly. A missing --> can cause later content to be interpreted as part of the comment or produce unexpected output. Comments can contain ordinary words and some punctuation, but avoid nested comment markers because HTML comments do not nest reliably. Use comments for editing instructions, build hints, or temporary context, not for content that readers must receive.

What comments hide and what they expose

A hidden comment is invisible in the rendered page, but it remains part of the source or generated HTML in many pipelines. Anyone who can inspect source code, download the document, access a repository, or view a build artifact may read it. Public repositories also preserve earlier versions through commits, pull requests, and forks. Sanitizers may remove comments, while other systems keep them. A Markdown preview may display them differently from the production site. This makes comments unsuitable for secrets, unpublished claims, customer information, internal credentials, or security instructions. If a note must stay private, use a review system, issue tracker, draft branch, or access-controlled document. Removing a comment from the current file does not remove copies from version history.

Comments for documentation maintenance

Useful comments explain a local editing decision or mark a controlled build action. Examples include <!-- Replace this screenshot after the next release. --> and <!-- The following block is consumed by the API extractor. -->. Make the instruction specific and actionable. Assign an owner or issue number when the note requires follow-up, but do not assume the comment itself creates a task. Delete temporary comments before release when they no longer help maintainers. If your build system uses comment directives, follow its documented syntax instead of inventing a similar marker. Test whether the processor passes comments through, strips them, or treats them as input metadata. A clean source file with external review records is often safer for long-lived public documentation.

Working example

This comment gives maintainers a release reminder without adding visible text to the paragraph.

Install the package with the command below.

<!-- Verify the command after the next major release. -->

```bash
package install example
```

The page shows the sentence and code block. The reminder is not visible in the normal rendered view, but it may remain in the HTML source.

Whether the comment survives conversion depends on the Markdown processor, sanitizer, and publishing pipeline.