HTML comments are usually the safest choice for hiding notes in Markdown source without showing them in the rendered page. A writer can place private reminders, editing notes, or build instructions inside <!-- --> blocks, as long as the publishing system does not expose raw source to readers.
TLDR: Markdown has no official native comment syntax, so most teams use <!-- hidden note --> for comments. For example, <!-- Check this statistic before publishing --> stays visible in the Markdown file but usually disappears from the rendered HTML page. In a 40-page documentation audit, editors may cut review time by 20% by leaving clear hidden notes beside unfinished sections. The main risk is privacy: hidden comments can still be visible in source files, Git history, CMS previews, or public repositories.
What a Markdown Comment Really Means
A Markdown comment is a note that exists in the source file but does not appear in the final rendered content. Markdown itself does not define a formal comment feature. That creates a mildly annoying gap. Writers expect a simple comment tool, but different Markdown engines handle hidden text in different ways.
In practice, two methods appear most often:
- HTML comments: Standard comments such as
<!-- note -->. - Markdown-compatible workarounds: Tricks based on reference links or parser behavior, such as
[//]: # (note).
The right choice depends on where the file will be processed. GitHub, static site generators, documentation platforms, note apps, and CMS tools may not behave the same way.
HTML Comments in Markdown
Most Markdown processors allow inline HTML. That means HTML comments usually work inside Markdown files:
<!-- This paragraph needs legal review. -->When rendered, the note should not display as visible page text. It remains in the source file. This makes it useful for editors, developers, and content reviewers.
Common uses include:
- Marking sections that still need fact-checking.
- Leaving instructions for another editor.
- Temporarily hiding draft text.
- Adding build notes for static site generators.
- Flagging missing links, images, or screenshots.
The catch is that “hidden” does not always mean “private.” If the output is HTML, comments may still exist in the page source unless the renderer strips them. A reader may not see the note on the page, but a developer can inspect the HTML and find it in seconds.
When HTML Comments Work Best
HTML comments are best when the Markdown content will be reviewed by trusted collaborators. They are also a good fit for documentation files stored in private repositories.
They work well in many common environments, including:
- GitHub Markdown: Comments are usually hidden from the rendered view.
- Static site generators: Many support HTML comments, though output settings vary.
- Developer docs: Comments can explain why a section is unfinished.
- Internal wikis: Editors can leave guidance without cluttering published pages.
Still, teams should avoid placing passwords, API keys, legal notes, private customer data, or internal strategy in comments. A comment is not a security feature. It is only a display control.
Markdown-Compatible Workarounds
Some writers prefer workarounds that look more like Markdown. These methods often abuse reference-style link syntax. One common pattern is:
[//]: # (This is a hidden note.)Another version looks like this:
[comment]: <> (This is also a hidden note.)These lines act like unused reference definitions. Since no visible link calls them, they usually do not show in rendered output. Honestly, it feels like a hack because it is one. It works in many places, then fails in one tool and costs someone five extra minutes during publishing.
Workarounds may help when:
- A platform strips HTML comments.
- A team wants comments that look less like raw HTML.
- A Markdown linter complains about inline HTML.
- A project uses strict Markdown rules.
Yet these patterns are not part of a single required Markdown standard. Some processors keep them hidden. Others display odd fragments. Some formatters may rewrite them. That makes testing essential before a team adopts them.
HTML Comments vs Workarounds
The main difference is predictability. HTML comments are familiar, readable, and widely understood. Markdown workarounds can be useful, but they rely on parser quirks.
| Method | Strength | Weakness |
|---|---|---|
<!-- note --> |
Clear and widely supported | May remain in HTML source |
[//]: # (note) |
Feels more Markdown-like | Can break across processors |
[comment]: <> (note) |
Often hidden in rendered output | May confuse editors and linters |
For most content teams, the plain HTML comment wins. It is easy to read, easy to search, and easy to remove before publication. The workaround wins only when a specific platform blocks or mishandles HTML comments.
Best Practices for Hidden Notes
Hidden notes should be short and useful. A comment should explain a task, risk, or question. It should not become a second draft living inside the first draft.
Good comments look like this:
<!-- Confirm pricing with finance before release. --><!-- Replace screenshot after version 3.2 ships. --><!-- Add citation for the 2024 survey. -->
Poor comments look like this:
<!-- Maybe rewrite all of this later, not sure. --><!-- Private client issue described in detail here. --><!-- Old paragraph saved just in case, 600 words long. -->
A good rule is simple: if a comment would embarrass the team when exposed, it should not be in the file. Issue trackers, review tools, and private docs are better places for sensitive discussion.
Publishing and Security Concerns
Markdown often passes through several steps. A file may move from a local editor to Git, then to a build tool, then to a website. Each step can keep, strip, or alter comments.
That means a team should test rendered output. It should check the visible page and the page source. If a comment appears in the final HTML source, it should be treated as public.
For public sites, many teams remove comments during build. Minifiers, HTML processors, or custom scripts can strip them. This is useful for content hygiene and a small file-size gain. On a large documentation site with 1,000 pages, even tiny leftover comments can turn into clutter during audits.
Practical Recommendation
The best default is HTML comments for normal editorial notes. They are clear, searchable, and easy for new contributors to understand. If a platform rejects inline HTML, then a team can use a Markdown-compatible workaround such as [//]: # (note), but only after testing it in the final renderer.
For sensitive material, neither method is suitable. Hidden notes are not private notes. They are source-level hints. That distinction saves teams from painful cleanup later.
FAQ
-
Does Markdown have official comments?
No. Standard Markdown does not include a formal comment syntax. Most users rely on HTML comments or parser-specific tricks. -
What is the most common Markdown comment style?
The most common style is<!-- hidden note -->. It is an HTML comment placed inside a Markdown file. -
Are HTML comments truly hidden?
They are usually hidden from the rendered page. They may still appear in source files, HTML output, repository history, and build logs. -
What is a Markdown-only workaround for comments?
A common workaround is[//]: # (hidden note). It often renders as nothing because it behaves like an unused reference link. -
Which method should a team use?
Most teams should use HTML comments. If a tool blocks them, a tested reference-style workaround is the next best option. -
Can comments hide draft content safely?
They can hide draft content from normal rendered view, but not safely from public access. Private or sensitive draft text belongs outside public Markdown files.