How to write comments in Markdown

To write a comment in Markdown, use an HTML comment: <!-- your note -->. It does not appear in the rendered page on GitHub or in most Markdown viewers. Markdown itself defines no comment syntax, so the other common option is an unused link reference definition such as [//]: # (your note), which CommonMark parsers drop from the output entirely. Neither is private: the text stays in the .md file, and HTML comments are often copied into the generated HTML.

Syntax quick reference

Key facts

• CommonMark and GitHub Flavored Markdown have no dedicated comment syntax.
• HTML comments, <!-- -->, are the most portable option. GitHub Docs states that content in an HTML comment is hidden from the rendered Markdown.
• A standard CommonMark renderer passes HTML comments through to the HTML output, so anyone who views the page source can read them.
• A link reference definition such as [//]: # (note) produces no output in CommonMark, so it is absent from the HTML as well as the rendered view.
• A link reference definition cannot interrupt a paragraph, so it needs a blank line before it.
• Obsidian's %%comment%% syntax is specific to Obsidian and shows as plain text elsewhere.
• No Markdown comment is private. The text is always in the source file.

HTML comments

Markdown allows raw HTML, and an HTML comment is a piece of raw HTML that browsers never display. Start it with <!-- and end it with -->. It works inline, inside a sentence, or as a block on its own lines.

Inline and block comments

Markdown

The release ships in March. <!-- confirm date with Sam -->

<!--
TODO before publishing:
- add screenshots
- check links
-->

Install the app from the downloads page.

Rendered output

HTML output

<p>The release ships in March. <!-- confirm date with Sam --></p>
<!--
TODO before publishing:
- add screenshots
- check links
-->
<p>Install the app from the downloads page.</p>

The HTML output shown is what a standard CommonMark renderer produces: the comments are hidden on screen but remain in the page source. GitHub goes further and removes them from the rendered HTML.

In CommonMark, a line that begins with <!-- starts an HTML block that continues until a line containing -->. That means a block comment can span blank lines and can hide Markdown, such as a draft section you want to keep but not publish. The comment text must not contain -->, because that ends it early.

Comments are not processed inside code. In a code span or fenced code block, <!-- --> is shown as literal text, which is how you document the syntax itself. See Fenced code blocks.

The [//]: # link reference trick

A link reference definition, such as [docs]: https://example.com, defines a label that reference links elsewhere can use. CommonMark states that a definition does not correspond to a structural element of the document, so it produces no output of its own. A definition that nothing links to is therefore invisible, and that is the trick: write a definition whose title is your comment.

Comment as an unused link definition

Markdown

Paragraph before.

[//]: # (This note is not rendered or included in the HTML.)

Paragraph after.

Rendered output

HTML output

<p>Paragraph before.</p>
<p>Paragraph after.</p>

Each part follows the spec: [//] is the link label, # is the destination, and (…) is the optional link title, which can also be written in double or single quotes. Common variants all use the same rule:

[//]: # (Comment in parentheses)
[//]: # "Comment in double quotes"
[comment]: <> (Empty destination written as <>)
[note]: # (Any label works if nothing links to it)

CommonMark allows an empty destination only inside angle brackets, which is why the [comment]: <> form uses <> rather than nothing. The label can be any text that is not used as a link elsewhere in the document.

Two ways the trick breaks

Markdown

A paragraph line
[//]: # (no blank line above)

[//]: # (a (nested) parenthesis)

Rendered output

HTML output

<p>A paragraph line
[//]: # (no blank line above)</p>
<p>[//]: # (a (nested) parenthesis)</p>

A definition cannot interrupt a paragraph, so the first one is read as paragraph text. The second fails because unescaped parentheses inside a parenthesized title are not allowed. If another valid [//] definition exists elsewhere in the file, these leftover [//] fragments render as links to #, which is how GitHub displays them.

Obsidian comments with %%

Obsidian adds its own comment syntax: wrap text in double percent signs. Obsidian Help states that comments are only visible in Editing view and are hidden in Reading view. An inline comment can sit anywhere in a line, and a block comment starts on a line beginning with %% and ends at the next %%.

Obsidian inline and block comments

Markdown

Meeting moved to Friday. %%check room booking%%

%%
Private notes for the next draft.
They can include **Markdown** and blank lines.
%%

Rendered output

HTML output

<p>Meeting moved to Friday. </p>

Rendered output is Obsidian's Reading view. On GitHub and in other renderers, the %% markers and the text inside them appear as ordinary text.

Obsidian Help warns that an unclosed block comment hides the rest of the note in Reading view. It also notes that the %% syntax is specific to Obsidian and suggests HTML comments for text that must stay hidden in other apps. To show literal %%, put it in a code span or escape each marker with a backslash.

Pandoc, MDX, and other tools

• Pandoc: passes HTML comments through to HTML and Markdown output as raw HTML by default. The --strip-comments option removes them instead. Formats such as DOCX and PDF do not carry raw HTML, so comments do not appear there.
• MDX: HTML comments are not supported. Use a JavaScript comment inside braces: {/* note */}.
• Static site generators and documentation tools: most use a CommonMark-compatible parser, so both HTML comments and the link reference trick are hidden on the page. Whether HTML comments survive into the published source depends on the tool and any HTML minifier.
• Chat and note apps such as Slack, Discord, and Notion do not process raw HTML, so <!-- --> typically appears as literal text. Check your renderer.

For text a reader should be able to open on demand, a comment is the wrong tool. Use a collapsible <details> block instead; see Collapsible sections. For metadata such as a title or tags, use front matter, which many tools hide from the rendered page.

Comments are hidden, not private

Every comment method hides text from the rendered view only. The words are still in the Markdown file, in its version history, and, for HTML comments, often in the HTML that a static site or documentation build publishes. Anyone who opens the raw file on GitHub, views the page source in a browser, or receives the .md file can read them.

• Do not put passwords, API keys, internal URLs, personal data, or candid review notes in comments.
• Deleting a comment later does not remove it from Git history.
• If comments must not ship, strip them in the build (for example, Pandoc --strip-comments) or prefer the link reference trick, which CommonMark parsers leave out of the HTML.

Flavor differences

Comment support depends on whether the renderer accepts raw HTML and follows CommonMark link reference rules.

For more on raw HTML handling, see Inline HTML and Markdown flavors.

For the full comparison of how flavors differ across all elements, see Markdown flavors.

How Markdific renders it

Markdific renders CommonMark and GFM with sanitized raw HTML, so standard HTML comments and unused link reference definitions are expected to stay out of the preview; check the preview for your document. Front matter is also hidden from the rendered view. Try it in the Markdific online editor.

Common mistakes and gotchas

• Treating comments as private. The text stays in the file and its history, and HTML comments are often in the published page source.
• No blank line before [//]: #. A link reference definition cannot interrupt a paragraph, so the line shows as text.
• Parentheses inside the comment. In [//]: # (…), unescaped nested parentheses break the definition. Use double quotes instead: [//]: # "note (with parentheses)".
• Writing --> inside an HTML comment. The first --> closes the comment, and the rest becomes visible.
• Using %% outside Obsidian. Other renderers show the markers and the text.
• Using HTML comments in MDX. MDX does not support them; use {/* */}.

Best practices

• Use <!-- --> for general notes in files read on GitHub or in most editors.
• Use [//]: # (…) when the comment must not appear in the generated HTML, and leave a blank line before it.
• Keep comments short and actionable, such as TODOs for the next editor, and remove them once resolved.
• Never store secrets or personal data in comments.
• When a document moves between tools, prefer HTML comments over tool-specific syntax such as %%.

HTML equivalent

An HTML comment in Markdown is passed through unchanged by a CommonMark renderer, while a link reference comment produces nothing.

Markdown

Visible text. <!-- HTML comment -->

[//]: # (Link reference comment)

HTML output

<p>Visible text. <!-- HTML comment --></p>

FAQ

How do you comment in Markdown? Use an HTML comment: <!-- your comment -->. Markdown has no comment syntax of its own, but HTML comments are hidden in the rendered view on GitHub and most renderers.

What does [//]: # mean in Markdown? It is a link reference definition with the label // and the destination #. Nothing links to it, so it produces no output, and the text in parentheses after it acts as a hidden comment.

Are Markdown comments visible to readers? Not in the rendered view, but they are in the source file. HTML comments are also often included in the generated HTML, where anyone can read them with View Source.

How do I write a multi-line comment in Markdown? Put <!-- on one line, your text on the following lines, and --> on the last line. The comment can include blank lines and Markdown.

Do HTML comments work on GitHub? Yes. GitHub Docs states that you can hide content from rendered Markdown by placing it in an HTML comment. The text is still visible in the raw file.

How do comments work in Obsidian? Wrap text in %%, inline as %%note%% or as a block between lines starting with %%. Comments are visible in Editing view and hidden in Reading view.

How do I hide text in Markdown? To hide text completely, use a comment. To hide it until the reader clicks, use a <details> collapsible section, which works on GitHub.

Sources and compatibility references

• GitHub Docs: Basic writing and formatting syntax (Hiding content with comments)
• CommonMark Spec 0.31.2: Link reference definitions
• CommonMark Spec 0.31.2: Links (destinations and titles)
• CommonMark Spec 0.31.2: HTML blocks
• CommonMark Spec 0.31.2: Raw HTML (HTML comments)
• Obsidian Help: Basic formatting syntax (Comments)
• Pandoc User's Guide: --strip-comments
• MDX: What is MDX? (comments)
• GitHub REST API: Render a Markdown document (used to check GitHub's output)

Use these primary references for syntax rules. Renderer behavior can still vary by version and configuration, so preview important documents in their final destination.

To see how your Markdown renders while you write, open the file in Markdific, a Markdown viewer and editor for Mac, Windows and Linux.

Related pages

• Markdown documentation hub
• Inline HTML
• Links
• Collapsible sections
• Front matter
• Escaping characters
• Markdown flavors
• Markdown cheat sheet