MDUtil

Comments in Markdown

Markdown has no comment syntax of its own, but two tricks hide text from the rendered page: HTML comments and an unused link definition. This guide shows both and when to use each.

Quick answer

How do you write a comment in Markdown?

Wrap the note in an HTML comment: <!-- note -->. It is hidden on the rendered page but stays in the file. For a comment that does not reach the HTML either, write an unused link definition on its own line: [//]: # (note).

Markdown
Visible text.

<!-- This note is hidden. -->

[//]: # (This one is hidden too.)

More visible text.

Result

Visible text.

More visible text.

Comment syntax and examples

Both kinds of comment disappear from the rendered page. They differ in where else the text survives.

HTML comment

Hidden on the rendered page. It stays in the Markdown file, and some sites keep it in the page's HTML source.

Markdown
Visible text.

<!-- This note is hidden. -->

More visible text.

Result

Visible text.

More visible text.

Comment over several lines

An HTML comment can span as many lines as you need.

Markdown
<!--
TODO: add screenshots
and a troubleshooting section.
-->

The guide continues here.

Result

The guide continues here.

The link definition trick

A link definition that nothing uses produces no output at all, not even in the HTML. It must sit on one line with a blank line before it.

Markdown
Visible text.

[//]: # (This comment never reaches the HTML.)

More visible text.

Result

Visible text.

More visible text.

Other forms of the trick

Any label and address work; the comment goes in the title, in parentheses or quotes.

Markdown
[comment]: <> (Hidden with an empty address)
[//]: # "Hidden with a quoted title"

Only this line is shown.

Result

Only this line is shown.

Commenting out a section

Wrap Markdown in an HTML comment to hide it without deleting it.

Markdown
## Changelog

<!--
## Old roadmap
- Dark mode
-->

- Fixed the login bug

Result

Changelog
  • Fixed the login bug

Obsidian comments

Obsidian hides text between %% pairs in reading view. Other apps show the percent signs.

Markdown
Visible text %%inline comment%%

%%
A hidden block
on several lines.
%%

Obsidian only. Other Markdown apps display this differently, so there is no preview.

Comments in popular apps

Apps that render Markdown files hide both kinds of comment. Chat apps have no comments.

AppSupportNotes
GitHub / GitLabSupportedHTML comments and [//]: # are hidden in files, issues and pull requests.
ObsidianSupportedHTML comments are hidden, and so is %%text%%.
VS Code / TyporaSupportedBoth kinds are hidden in the preview.
Hugo / JekyllSupportedBoth are left out of the page; HTML comments may stay in its source.
Discord / SlackNot supportedNo comments; the text is posted as typed.

Questions and answers

Are HTML comments visible to readers?

Not on the rendered page. Anyone who opens the Markdown file can read them, though, and some sites keep them in the page's HTML source, so never put passwords or private notes in a comment.

What does [//]: # mean?

It is a link definition with the label // and the address #. Nothing links to it, so it produces no output, and the text in parentheses after it works as a comment.

Why does my comment show up?

The link trick needs a blank line before it and must fit on one line. An HTML comment must end with -->; when it never closes, everything after it can disappear.

Do comments work on GitHub?

Yes. GitHub hides HTML comments and the [//]: # trick in files, issues and pull requests. Issue and pull request templates often use HTML comments for instructions.

Can I hide a whole section?

Yes. Put <!-- on the line before the section and --> on the line after it. The Markdown inside is not rendered.

Can I add a comment inside a code block?

Everything in a code block is shown, so a Markdown comment there appears as text. Use the comment syntax of the code's own language.

How do I write comments in Obsidian?

Wrap the text in %%: %%hidden%%. It shows in the editor and is hidden in reading view.

Do comments end up in a PDF or Word file?

No. Both kinds produce no output, so Markdown to PDF and Markdown to Word leave them out.