How do you write a comment in Markdown, i.e. text that is not rendered in the HTML output?
Markdown doesn’t have a built-in comment syntax like HTML, but there are several workarounds to create comments that don’t render in the final HTML output. The most common methods include using HTML comment syntax (<!-- comment -->), fenced code blocks with a “comment” language specification, or leveraging specific comment syntax supported by your Markdown processor.
- What is a Markdown Comment?
- HTML Comment Syntax
- Code Block Method
- Processor-Specific Comment Systems
- Best Practices for Comments
- Comparison of Methods
- Real-World Examples
What is a Markdown Comment?
Unlike HTML which has a dedicated <!-- comment --> syntax, standard Markdown specification does not include a native comment syntax. This is one of the most frequently asked questions among Markdown users who want to add notes to their documents without those notes appearing in the rendered output.
A Markdown comment serves several purposes:
- Documenting the document structure for future reference
- Leaving notes for other collaborators
- Storing temporary reminders or to-do items
- Providing context that shouldn’t be visible to readers
The challenge arises because Markdown was designed to be simple and focused on content rather than metadata or comments. However, various Markdown parsers and processors have implemented different solutions to this limitation.
HTML Comment Syntax
The most universal and widely supported method for adding comments in Markdown is to use HTML comment syntax. Since Markdown is designed to be HTML-compatible, you can embed HTML elements within your Markdown document.
<!-- This is a comment that won't appear in the final output -->
Advantages:
- Works with virtually all Markdown processors
- Renders as a true HTML comment in the final output
- Compatible with GitHub, GitLab, Jekyll, and most static site generators
Limitations:
- Not “pure” Markdown syntax
- Some very basic Markdown parsers might strip HTML elements
Example:
# My Document
This is the visible content.
<!-- TODO: Add more examples here -->
<!-- Author: John Doe -->
<!-- Last updated: 2024-01-15 -->
More visible content here.
The comments between the <!-- --> tags will be preserved in the HTML source but won’t be visible to readers.
Code Block Method
Another popular approach is to use fenced code blocks with a special language specification that indicates it’s a comment. This method is particularly useful when you want your comments to be visible while editing but not in the final output.
```comment
This is a comment that can be toggled visibility
**How it works:**
- Most Markdown processors will render code blocks with unknown languages
- Some tools recognize "comment" as a special language
- You can disable rendering in many editors/viewers
**Processor-specific implementations:**
- **Obsidian**: Supports `%% comment %%` syntax
- **Typora**: Has a dedicated comment feature
- **VS Code**: Can be configured with extensions
**Example:**
```markdown
# Main Content
Here's the actual content visible to readers.
```comment
Note: The following section needs more research
Check references on page 23-45
Section 2
---
## Processor-Specific Comment Systems {#processor-specific-comment-systems}
Different Markdown processors and platforms have implemented their own comment systems:
### GitHub/GitLab Flavored Markdown
GitHub and GitLab support **task lists** which can serve as a form of comment:
```markdown
- [x] Completed task
- [ ] TODO: This needs review
- [ ] FIXME: Bug in this section
Jekyll Comments
For Jekyll static sites, you can use:
{% comment %}
This won't appear in the final site output
{% endcomment %}
Obsidian Comments
Obsidian supports:
%% This is an Obsidian comment %%
MultiMarkdown Comments
MultiMarkdown processor supports:
[comment]: # (This is a MultiMarkdown comment)
Best Practices for Comments
When adding comments to Markdown documents, consider these best practices:
1. Consistency
Choose one method and stick with it throughout your document for better maintainability.
2. Comment Metadata
Include useful information in your comments:
<!-- TODO: Add more statistics AUTHOR: Jane Smith DATE: 2024-01-20 PRIORITY: High -->
3. Organization
Use comment blocks to organize your thoughts:
<!--
DOCUMENT STRUCTURE:
- Introduction
- Background
- Objectives
- Methods
- Results
- Conclusion
-->
4. Temporary vs Permanent
Distinguish between temporary comments and permanent documentation:
- Use
TODO:for items that need action - Use
NOTE:for important observations - Use
FIXME:for known issues
Comparison of Methods
| Method | Compatibility | Visibility in Source | Best For |
|---|---|---|---|
HTML Comments (<!-- -->) |
Universal | Hidden in HTML | General purpose, cross-platform |
| Code Block (```comment) | Most processors | Visible as code | Temporary notes, debugging |
Task Lists (- [ ]) |
GitHub/GitLab | Visible as checkboxes | Action items, tracking |
Obsidian (%% %%) |
Obsidian only | Hidden in preview | Personal note-taking |
| YAML Front Matter | Jekyll/Hugo | Hidden in HTML | Document metadata |
Real-World Examples
Technical Documentation
# API Documentation
<!--
This section documents the user authentication endpoints.
AUTHOR: API Team
LAST REVIEWED: 2024-01-15
-->
## Login Endpoint
POST /api/login
Request body:
```json
{
"email": "user@example.com",
"password": "secret123"
}
### Academic Paper
```markdown
# Research Paper Draft
<!--
STRUCTURE NOTES:
- Abstract needs more quantitative data
- Literature review section is complete
- Methodology needs statistical analysis
- Results section requires visualization
-->
## Abstract
This study examines...
## Introduction
<!-- NOTE: Citations from Smith et al. (2023) need verification -->
Project README
# Project Name
<!--
PROJECT STATUS: In Development
CONTRIBUTORS: John Doe, Jane Smith
LICENSE: MIT
-->
## Installation
```bash
npm install project-name
---
## Conclusion {#conclusion}
Creating comments in Markdown that don't render in HTML output requires using workarounds since standard Markdown doesn't have a native comment syntax. The most reliable methods include:
1. **HTML comments** (`<!-- comment -->`) for universal compatibility across all Markdown processors
2. **Code blocks** with special language designations for editor-specific comment functionality
3. **Processor-specific syntax** like Obsidian's `%% comment %%` or MultiMarkdown's `[comment]: # ()`
Choose the method that best fits your workflow and the tools you're using. For maximum compatibility, HTML comments remain the most reliable approach that works across virtually all Markdown processors and platforms. Remember to document your chosen comment style in your project guidelines to maintain consistency across collaborative documents.
## Sources {#sources}
1. [Markdown Guide - Comments](https://www.markdownguide.org/basic-syntax/#html-comments)
2. [GitHub Flavored Markdown Documentation](https://github.github.com/gfm/)
3. [Obsidian Documentation - Comments](https://help.obsidian.md/Editing+and+formatting/Comments)
4. [MultiMarkdown Documentation](https://fletcher.github.io/MultiMarkdown-6/syntax/comments.html)
5. [Jekyll Documentation - Comments](https://jekyllrb.com/docs/posts/#front-matter)