Comments in Markdown: Hidden Display Is Not Private Storage

A comment can leave an editing note in source without displaying it as ordinary document text. Markdown has no universal dedicated comment delimiter. HTML comments are a common option, while frontmatter and application-specific syntax need additional support.

The key rule is that a hidden display is not a privacy boundary. A person who receives the source file can read the note.

HTML comments

An HTML comment looks like this:

Visible paragraph.

<!-- TODO: check the heading before publishing. -->

Another visible paragraph.

In an HTML-enabled renderer, the browser does not display the comment. The application may pass it through to the HTML, strip it, or handle it differently. GitHub describes this technique in its formatting documentation.

MD File Viewer removes raw HTML, including comments, from the rendered preview and HTML conversion output. The original Markdown still contains the comment. Keep it in the source only if everyone who can access that source is allowed to read it.

A comment can span lines:

<!--
Review notes:
- Check the example URL.
- Confirm the image permission.
-->

Avoid nesting comment delimiters, and test a multiline example at the destination. A malformed comment may hide more content than intended or expose the note as text.

Why link definitions are not a general comment format

You may encounter this convention:

[//]: # (An editing note)

It uses an unused reference-link definition rather than a real comment object. Recognition depends on the precise input and parser. A linter may also flag unused definitions. If another part of the document uses the reference, its destination or title can become visible through a link.

Use ordinary reference definitions for links and use an explicitly supported comment mechanism for notes. Do not store secrets in either one.

Frontmatter is metadata with a preprocessing step

Some publishing systems read a YAML block at the top of a file before rendering:

---
title: Import handbook
draft: true
---

# Import handbook

Core Markdown does not define this block as hidden metadata. Without frontmatter preprocessing, the hyphens and text can become document content or headings. The current MD File Viewer tool does not strip frontmatter as a metadata block, so do not rely on it to hide an internal note.

A draft: true field also only works when the publishing system enforces it. The field alone does not prevent a file from being uploaded, served, or indexed.

MDX and other application syntax

MDX combines Markdown with JSX and uses a compilation step. In an MDX project, a comment can be written as:

{/* Check this component before publishing. */}

The MD File Viewer editor parses Markdown, not MDX, and does not execute JSX. That comment syntax can appear as ordinary text here. A source filename used by this website's own build system does not change what the public tool accepts.

Other note applications can have their own delimiters, such as %% ... %%. Use them only with the application that documents them, and test again when exporting to another format.

What is actually visible?

Method	Rendered display	Original source
HTML comment	Usually hidden or removed; depends on application	Contains the note
Unused reference definition	Can be omitted when recognized	Contains the definition and note
Frontmatter	Hidden only when preprocessed	Contains all metadata
MDX comment	Handled by an MDX compiler	Contains the comment
App-specific delimiter	Depends on that application	Contains the note

Before publishing, search the source for unfinished notes and private material, inspect the rendered page, and check the exported artifact. Do not assume that removing a comment from the preview removes it from a repository, a saved draft, or an earlier shared copy.

Keep passwords, keys, personal data, and confidential review discussion in an approved private system rather than a comment in a shared document. For conversion behavior, see the HTML export guide.