Markdown Syntax · Comments

How to Comment in Markdown
Notes that do not render

Markdown has no comment syntax of its own. But you often want a note that stays in the file without showing up: a TODO, a reminder to a co-author, a section you are temporarily turning off. The trick is to borrow an HTML comment: <!-- note -->.

Markdown passes HTML straight through, and browsers never display a comment, so it stays out of the rendered page while living in your source. Here is the full picture, including the one big caveat.

The ways to comment

Type How Note
HTML comment <!-- note --> The standard way; the renderer hides it
Multi-line Open with <!-- , close with --> , anything between is hidden One comment across many lines
Link-reference trick [//]: # (note) Renders as nothing in more processors; a bit cryptic
Inside a code block Shows literally A code block does not hide the markers

In context, the HTML comment looks like this, and none of the middle part reaches the reader:

Visible text everyone reads.

<!-- This note will not render.
It can span several lines. -->

More visible text.

The one big caveat: it is not actually hidden

A comment does not render, but it is not a secret. It sits in plain sight in the .md file, and anyone who opens the source sees it. Use it for notes and TODOs, never for a password, a token, or anything you would not want a reader to find. Hidden from the page is not the same as hidden from the file.

When the comment shows up anyway

  • Safe-mode renderers: some Markdown processors escape or strip raw HTML for safety, which can make your comment appear as text or disappear entirely. If it misbehaves, that is usually why.
  • Inside code: in a code block or inline code, the markers are literal and will display. That is the point of code blocks, so it is expected.
  • The no-HTML alternative: if HTML comments do not work in your setup, try the link-reference trick, [//]: # (note). It renders as nothing in more processors, at the cost of being harder to read.

Where comments are handy

Comments earn their keep in longer documents: a TODO next to a half-finished section, a note explaining a decision in a README, or a reminder you leave for future-you. They travel with the file, so the context is right where you need it, without cluttering what readers see. New to the syntax generally? See how to write Markdown.

Seeing both sides with NoteLoom

The useful thing about a comment is that it exists in the source but not the output, and NoteLoom lets you see both. It is an editor that reads and writes local .md files in the browser: the source view shows your comment sitting in the file, and the reading view leaves it out, the way a renderer does.

To be clear about the boundaries: NoteLoom has no AI. It will not write or manage your notes for you. It renders and saves your local file, and the writing stays with you.

How you use it: open app.noteloom.cc in Chrome / Edge / Arc, mount a local folder, and toggle between the source and reading views. Saved straight to your disk, no cloud, no account.

Related reading

How to Write Markdown? The basic syntax, so you know what does and does not render. How do you write code blocks in Markdown? Where comment markers show up literally instead of hiding. How do you escape characters in Markdown? The other "why is my symbol showing" question. What is README.md? A common place to leave TODO comments for later. Online Markdown Editor See source and reading side by side in your browser.

FAQ

How do I write a comment in Markdown?
Markdown has no comment of its own, so you borrow an HTML comment: <!-- your note -->. Markdown passes HTML through and browsers hide comments, so it does not appear in the rendered output.
Can a Markdown comment span multiple lines?
Yes. Everything between the opening <!-- and the closing --> is hidden, across as many lines as you want. It is one comment from the first marker to the last.
Is a Markdown comment actually hidden?
Not from anyone reading the raw file. It does not render in the output, but it is still sitting right there in the .md source. Never put a secret, a password, or a token in a comment.
Why is my comment showing up as text?
Two usual reasons. Some Markdown processors run in a safe mode that escapes or strips HTML, so the comment can show or vanish. And inside a code block the markers are literal, so the comment displays. Test in your actual renderer.
Is there a comment that works without HTML?
A common trick is an unused link reference: [//]: # (your note). It renders as nothing in more processors than an HTML comment does, though it is a bit cryptic to read. Both are fine, pick whichever your renderer respects.
Can NoteLoom show me the difference?
Yes. In NoteLoom’s source view you see the comment sitting in your file; in the reading view it drops out, the way a renderer treats it. It has no AI: it just renders and saves your local .md.
Can I do this with NoteLoom on my phone or in Safari?
Not for now. NoteLoom relies on the browser’s File System Access API, which currently works in Chromium-based desktop browsers like Chrome, Edge, and Arc. Firefox, Safari, and mobile are not supported yet.

See your comments in the source, gone in the output

Open NoteLoom in Chrome / Edge / Arc, mount a local folder, and switch between the source view (your comment is there) and the reading view (it is gone). Saved straight back to your disk, no software to install and no account to sign up for.

Open NoteLoom and try it