How to Add Comments in Markdown (Hidden Notes That Don't Render)

If you've ever wanted to leave yourself a note inside a Markdown file without that note showing up on the rendered page, you've probably discovered the awkward truth: Markdown has no official comment syntax. Unlike HTML with its <!-- --> tags or JavaScript with its // lines, the Markdown specification simply doesn't define a dedicated way to add hidden comments. That surprises a lot of newcomers — and it's exactly why the question how to comment in Markdown gets searched thousands of times a month.

The good news is that several reliable workarounds exist, and the right one depends on where your Markdown lives. In this guide we'll cover every practical approach to adding a markdown comment that won't render — from the portable HTML comment that works almost everywhere, to link-reference tricks, YAML frontmatter, and tool-specific syntax used by Obsidian, MDX, and others. If you're still getting comfortable with the basics, skim our Markdown cheat sheet first, then come back here.

Why Markdown Has No Native Comment Syntax

Markdown was designed by John Gruber in 2004 as a lightweight shorthand for converting plain text into HTML, and he intentionally kept the spec tiny. Anything not in the spec is left to the renderer. Because comments were never part of the original grammar, every tool has had to invent its own workaround — usually by borrowing from an adjacent format like HTML or YAML.

This matters because a technique that works in GitHub-flavored Markdown may silently fail in a different renderer, or worse, leak your hidden note onto the page. The safest bet is to understand each method's trade-offs rather than memorize one trick. Below, we'll walk through them from most to least portable. (For a broader intro to the format itself, see What is Markdown.)

The HTML Comment: The Most Portable Markdown Comment

The single most reliable way to leave a hidden note in a .md file is to borrow HTML's comment syntax. Because Markdown passes inline HTML straight through to the browser, an HTML comment is treated as a comment by the renderer and is not displayed on the page.

Here is some visible text.

<!-- TODO: rewrite this intro before publishing -->

And here is more visible text.

The syntax is identical to plain HTML:

<!-- This is a comment. It will not render on the page. -->

A few practical notes:

• Works almost everywhere: GitHub, GitLab, most static site generators (Hugo, Jekyll, Eleventy), and common JavaScript renderers all pass HTML comments through untouched.
• Can span multiple lines: wrap a longer note inside a single <!-- ... --> pair.
• Nesting isn't allowed: you can't put a -- sequence inside the comment body, and you can't nest one comment inside another.

<!--
  Multi-line note:
  - confirm the API endpoint
  - check the screenshot is up to date
-->

This is the method we recommend as your default markdown comment — if you only learn one, learn this one.

The Link-Reference Trick: [//]: # (comment)

A cleverer, more "pure Markdown" approach abuses link reference definitions. A link reference that points to nowhere and is never used effectively disappears from the rendered output, so many writers use it as a comment.

Some visible paragraph.

[//]: # (This is a hidden comment using a link reference)

Another visible paragraph.

A few variations exist and behave similarly:

[//]: <> (comment text)
[comment]: # (comment text)
[^//]: # (used in some setups)

Caveats with this method:

• It must be preceded and followed by a blank line, or it may attach itself to the surrounding paragraph.
• It only "hides" text because it's a valid but unused link reference — some linters will flag unused references.
• Support varies: it works in most CommonMark renderers but is not guaranteed in every tool.

Use this when you want to avoid raw HTML, but treat it as a secondary option rather than your default.

YAML Frontmatter for Metadata, Not Inline Notes

Many Markdown files begin with a YAML block delimited by ---. This frontmatter is read by static site generators and documentation tools but is stripped out before rendering, so it's effectively invisible on the final page.

---
title: My Document
draft: true
author: Jane Doe
reviewers: [Alice, Bob]
---

# My Document

Body text begins here.

Frontmatter is the right place for structured metadata — title, date, draft status, tags, author — not for free-form inline notes scattered through the body. If you need a TODO reminder at a specific spot in the document, use an HTML comment there instead.

---
draft: true
internal_note: "Pending legal review — do not publish yet"
---

Tool-Specific Comment Syntax

Several popular Markdown-based tools define their own comment syntax. These are convenient inside their ecosystem but will render as plain text elsewhere, so use them only when you know your file won't leave that tool.

Obsidian: %% ... %%

Obsidian, the note-taking app, supports %% to wrap comments that are hidden inside Obsidian but visible if you open the file in a plain text editor.

Visible note text.

%% This is only visible inside Obsidian's editor. %%

More visible text.

MDX: {/* ... */}

MDX (Markdown + JSX, used heavily in modern docs and component libraries) treats content inside {/* */} as a JavaScript comment, so it's stripped during compilation.

Here is a paragraph.

{/* TODO: swap in the new <Button /> component */}

Here is another paragraph.

If your project renders MDX — like the editor on MD File Viewer — this is the cleanest way to comment. Just remember it won't work in plain .md files.

Other tools

• R Markdown / Quarto: use HTML comments, or R's <!-- --> plus chunk options.
• Pandoc: supports HTML comments; Lua filters can add custom comment syntax.
• Jekyll / Hugo: HTML comments pass through; frontmatter handles metadata.

Warning: HTML Comments Are Visible in "View Source"

This is the part that trips people up. An HTML comment is hidden from the rendered page, but it is not encrypted or stripped. Anyone who opens your raw .md file, views the page source, or inspects the rendered HTML in DevTools will see your "hidden" note in full.

That means:

• Never put secrets in a comment — API keys, passwords, personal data, draft-only opinions you wouldn't want public.
• Assume comments are public if the file lives in a public repo or on a public site.
• Comments ship to the browser, adding bytes to the HTML payload, so don't leave hundreds of lines of commentary in production files.

If you need to share sensitive notes with collaborators, do it out of band — in your issue tracker, a private doc, or a code review — not in a Markdown comment.

Markdown Comment Methods at a Glance

Method	Syntax	Visibility
HTML comment	<!-- comment -->	Hidden on page; visible in source / raw .md
Link reference trick	[//]: # (comment)	Hidden on page; visible in raw .md
YAML frontmatter	---\nkey: value\n---	Stripped before render; visible in raw .md
Obsidian	%% comment %%	Hidden in Obsidian; visible in raw .md and other tools
MDX	{/* comment */}	Stripped at compile time in MDX; renders as text in plain .md

Frequently Asked Questions

Can I use // or # to comment in Markdown?

No — neither works the way you might expect. // renders as plain text on the page, and # is the heading syntax, so # comment becomes a big bold heading rather than a hidden note. Use an HTML comment (<!-- -->) instead.

Are HTML comments safe to use on GitHub?

Yes. GitHub Flavored Markdown passes HTML comments through, so they stay hidden on the rendered README, issue, or PR description. They will, however, be visible to anyone reading the raw file. For more on GitHub-specific syntax, see our GitHub Flavored Markdown guide.

What's the best way to comment when converting Markdown to HTML?

The HTML comment method is ideal here, because it's already valid HTML — it survives the conversion intact and stays invisible in the output. See our Markdown to HTML guide for the full conversion workflow.

Do comments affect SEO or page weight?

HTML comments do ship to the browser, so they add a few bytes to the page. Search engines generally ignore comment content for ranking, so stuffing keywords into comments won't help SEO and can look spammy. Keep comments short and genuinely useful.

Wrapping Up

Markdown's lack of a native comment syntax is less of a problem than it first appears. For 90% of cases, the HTML comment <!-- ... --> is portable, predictable, and good enough. Reach for the link-reference trick when you want to stay in pure Markdown, use YAML frontmatter for structured metadata, and lean on tool-specific syntax like Obsidian's %% or MDX's {/* */} only inside the tools that support them. Whatever method you pick, remember that "hidden" means hidden from the rendered page — not from anyone who reads the source. Paste your next .md file into the MD File Viewer editor to confirm your comments vanish exactly as expected.