How to Add Comments in Markdown—and What Stays Visible

The short answer: use an HTML comment for portable notes

Write `<!--` before the note and `-->` after it. A compatible renderer treats that range as raw HTML comment content, so it does not appear as visible prose in the rendered document.

This is HTML syntax embedded in Markdown, not a dedicated Markdown comment feature. That distinction matters because some publishing systems disable or sanitize raw HTML.

# Release notes

<!-- Check the version number before publishing. -->

Version 2.4 is available.

Release notes

Version 2.4 is available.

Single-line and multiline HTML comments

A short comment can stay on one line. A longer editorial note can span several lines as long as the opening and closing markers are present.

Keep the markers easy to spot. A missing `-->` can cause a larger part of the document to be treated as raw HTML or hidden unexpectedly, depending on the renderer.

• Use a complete opening and closing marker.
• Do not rely on comments to disable executable code in another language.
• Preview the final document after changing a multiline comment.

<!-- Replace this screenshot after launch. -->

<!--
Reviewer: confirm the figures in the table.
Remove this note before publishing.
-->

Neither note appears as visible page content in a compatible renderer.

Hidden from the page does not mean private

A Markdown comment normally stays in the `.md` file. A reader can open the raw file, use a repository's source view, inspect an exported file, or retrieve the original through version history.

Comments are appropriate for harmless editorial context: a fact to verify, a section waiting for review, or a reminder to replace an image. They are not an access-control mechanism.

How comments behave on GitHub

GitHub documents HTML comments as the way to hide content from rendered Markdown. The hidden text still exists in the repository file, and GitHub lets readers switch from the rendered view to the source.

Use comments in README files for contributor reminders only when it is acceptable for every repository reader to see them. In a public repository, assume the raw comment is public.

## Installation

<!-- Keep this command synchronized with package.json. -->

```sh
npm install
```

The reminder is omitted from the rendered README; it remains in the README.md source.

• GitHub: Hiding content with comments

Obsidian comments are useful but not portable

Obsidian supports `%% comment %%` for inline or block comments. Obsidian hides them outside Editing view, which makes the syntax convenient for personal notes and drafting inside a vault.

The `%%` form is an Obsidian extension. Another Markdown renderer may show the percent signs and the note as ordinary text. Use HTML comments instead when the same file must move between GitHub, a CMS, a static-site generator, and multiple editors.

The proposal is ready. %%Ask Sam to check the budget.%%

%%
This whole block is an editing note.
%%

Obsidian hides these comments in Reading view; a generic renderer may display them.

• Obsidian Help: Comments

Comment markers inside code are examples, not comments

Inline code and fenced code blocks preserve literal characters. Put `<!-- note -->` inside a code block when you want to teach the syntax or show an HTML file; do not expect the Markdown renderer to remove it.

The language inside a fenced block controls highlighting, not whether Markdown comment rules run inside that block.

```html
<!-- This marker is displayed as code. -->
<p>Example</p>
```

A visible HTML code block containing the comment marker and paragraph tag.

Why a comment may appear or disappear in another renderer

CommonMark defines HTML comments as raw HTML, but a product can still disable raw HTML or sanitize the generated HTML for security. Some systems preserve the comment in generated source; others remove it during conversion or publishing.

A local preview proves only how that preview behaves. Before relying on a comment, test the file in the actual destination: the repository, documentation generator, CMS, note app, or export format that readers will use.

Choose comments according to where the file will live

Portability matters more than convenience when several tools share the same Markdown file. HTML comments are the safer default for a repository or publishing workflow that accepts raw HTML. Platform-specific markers are reasonable when the file is deliberately tied to one application.

1. Name the final rendererDecide whether the document will live on GitHub, in Obsidian, in a CMS, or in another publishing system.
2. Use the narrowest safe noteKeep comments short, non-sensitive, and directly related to editing the surrounding content.
3. Test source and outputCheck the rendered view, raw source, downloaded file, and version history before publishing.
4. Delete resolved commentsRemove notes that no longer help the next editor instead of leaving permanent clutter.

The standards behind the behavior

CommonMark specifies HTML comments within raw HTML blocks and inline raw HTML. GitHub and Obsidian then document the behavior of their own renderers and extensions. These references are more reliable than assuming every app implements the same dialect.

• CommonMark 0.31.2: HTML blocks
• CommonMark 0.31.2: Raw HTML
• GitHub writing and formatting syntax
• Obsidian basic formatting syntax