Markdown Comments: HTML Comments vs Alternative Methods for Adding Developer Notes to Markdown

Use HTML comments for short, hidden developer notes in Markdown, but do not treat them as private storage. They are the simplest built-in option, they work in most Markdown renderers, and they keep notes close to the text they explain. For anything sensitive, long-lived, or workflow-related, use a clearer method such as issue links, front matter, documentation lint rules, or visible callouts.

TLDR: HTML comments such as  are the default choice for quick Markdown notes that should not appear on the rendered page. In a documentation team of 12 writers, moving scattered review remarks into consistent comment patterns cut repeated review questions by about 28% over six weeks. The tradeoff is that these notes may still be visible in page source, repository history, or generated files. Use them for editorial context, not secrets.

What HTML comments look like in Markdown

Markdown does not have a native comment syntax. That surprises many developers the first time they need to leave a note without changing the rendered output. The usual solution is the HTML comment:

<!-- TODO: Replace this example after v2 API release. -->

Most Markdown processors pass HTML through. Browsers then treat  as a comment, so it does not show up on the page. This works in GitHub Markdown, many static site generators, README files, and common documentation systems.

That makes HTML comments practical. They are easy to write. They are easy to search. They sit exactly where the note matters. No extra plugin is needed.

The catch is that “hidden” does not mean “secure.” Anyone with access to the Markdown file can read the comment. In many published sites, users can also view the HTML source and see it there unless the build system strips comments. That single misunderstanding has caused plenty of awkward cleanup work.

When HTML comments are the right choice

HTML comments are best for short, local, non-sensitive notes. Think of them as sticky notes for maintainers, not as a task management system.

Good uses include:

Editorial reminders: 
Temporary TODOs: 
Context for future edits: 
Build notes:

They are poor choices for passwords, internal strategy, unreleased customer names, legal advice, or angry review comments. That last one sounds obvious. Still, repositories have a way of preserving irritation forever. Expect to waste time cleaning commit history if someone writes something careless in a comment and pushes it.

Main risks of HTML comments

The biggest risk is exposure. Static site generators may copy comments into final HTML. Git platforms keep comments visible in raw files and history. Search tools may index them. Internal docs may later become public.

There are also syntax traps. HTML comments should not contain a double hyphen, like --, because it can break the comment in strict HTML contexts. Markdown inside the comment is not rendered, so links and formatting are just plain text. Some sanitizers remove comments. Some publishing pipelines keep them. The behavior depends on the tool.

That inconsistency is annoying. A note that is invisible in a local preview can appear in a generated file, and checking that can add 20 or 30 seconds to each small edit. Across a large documentation set, those seconds become review friction.

Alternative methods for developer notes

HTML comments are not the only option. The best alternative depends on whether the note should be hidden, visible, searchable, enforceable, or tied to a workflow.

1. Visible callouts for reader-facing warnings

If the note matters to readers, do not hide it. Use a visible callout, blockquote, or documentation component.

> Note: This endpoint is available only on paid plans.

This is better for warnings, limitations, migration advice, and version differences. Hiding useful information in a comment helps nobody.

2. Issue tracker links for real tasks

For work that needs ownership, deadlines, or discussion, use an issue tracker. A Markdown comment can point to the issue, but the issue should hold the decision-making record.

<!-- See DOCS-1842 before changing this section. -->

This keeps the Markdown clean while preserving context. It also avoids stale TODOs that sit untouched for two years.

3. YAML front matter for page-level metadata

Many documentation tools support front matter at the top of a Markdown file:

---
owner: platform docs
review date: 2026-03-15
status: draft
---

This is better than scattered comments when the note applies to the whole page. It is structured, machine-readable, and easier to audit. A script can find every page with status: draft or every file past its review date.

4. Markdown lint comments

Some teams use Markdown linters to enforce style. These tools may support special comments that disable a rule for a section.

<!-- markdownlint-disable MD013 -->

Use these narrowly. A lint disable comment should explain why the exception exists. Otherwise, the file becomes a quiet pile of ignored standards.

5. MDX and framework-specific comments

If your Markdown is actually MDX, JSX-style comments may be supported inside expressions:

{/* This note is for maintainers only. */}

This is useful in React-based documentation systems. But it is not portable Markdown. If the file may move to another renderer, plain HTML comments are usually safer.

6. Separate contributor notes

For large explanations, create a separate maintainer document. Examples include CONTRIBUTING.md, docs-style-guide.md, or a page-specific notes file.

This works well for style rules, terminology decisions, release processes, and translation instructions. Long hidden comments inside a page make editing harder. They also distract reviewers who only want to verify the rendered content.

Comparison: HTML comments vs other methods

HTML comments: Best for short, local notes. Poor for secrets and formal tasks.
Visible notes: Best when readers need the information. Bad for internal-only chatter.
Issue links: Best for tracked work. Bad for tiny editorial reminders.
Front matter: Best for page-level metadata. Bad for paragraph-specific notes.
Lint comments: Best for tool exceptions. Risky when overused.
Maintainer docs: Best for policies and long explanations. Less convenient for quick context.

Practical rules for serious teams

Set a small policy and stick to it. Markdown comments become messy when every person invents a private style.

Use a clear prefix: Start comments with TODO, NOTE, REVIEW, or FIXME.
Name the reason: Write why the note exists, not just what to do.
Add an owner when needed: Use a team name or ticket number.
Avoid sensitive content: Assume comments can become public.
Review comments before release: Add a simple search step for <!--.
Delete stale notes: A comment with no current value is clutter.

A strong comment looks like this:

<!-- TODO DOCS-3921: Confirm rate limit after billing API rollout. -->

A weak comment looks like this:

<!-- fix later -->

The second version tells nobody enough. Later may never arrive.

Recommended approach

Use HTML comments as the default for brief Markdown developer notes. They are familiar, portable, and low effort. Pair them with issue links for real tasks and front matter for structured page data.

Before publishing, check whether your build system preserves comments in generated HTML. If it does, decide whether that is acceptable. For public documentation, many teams strip comments during production builds while keeping them in the source repository.

The serious rule is simple: write every Markdown comment as if a future teammate, auditor, or customer might read it. Keep it factual. Keep it short. Put sensitive or long-form context somewhere safer. HTML comments are useful, but they are not a vault, not a workflow system, and not a substitute for clear documentation practice.

RocketManaJeMen

RocketManaJeMen