Markdownで文章を書いているとき、
「この行は一旦メモとして残しておきたいけど、プレビューや公開時には見せたくない」
「後から書き直すかもしれない部分を、ひとまずコメントアウトしておきたい」
と思ったことはありませんか？
MarkdownにはHTMLのような専用のコメント機能はありませんが、簡単に使える方法があります。
この記事では、Markdownでコメントアウトを実現するやり方と注意点を初心者にもわかりやすく解説します。
Markdownに正式なコメント文法はない
実は、Markdown自体にはHTMLの <!-- コメント --> のような純粋なコメント文法はありません。
これは、Markdownが「簡単に読み書きできるテキスト形式」として設計されたためです。コメント機能を入れると、記法が複雑になってしまうからです。
そのため、普通にMarkdownだけを書いていると、何らかの工夫でコメントを埋め込む必要があります。
Markdownの設計思想
Markdownは以下の理念で作られました：
- 読みやすいプレーンテキスト形式
- 簡潔で覚えやすい記法
- HTMLに変換できる
コメント機能よりも、シンプルさを重視した結果、専用のコメント文法は含まれませんでした。
一般的なコメントアウト方法：HTMLコメントを使う
HTMLコメント <!-- --> を使う
MarkdownはHTMLをそのまま書ける仕様なので、HTMLのコメントタグ <!-- --> を使うのが一般的で確実な方法です。
基本的な使い方
これは表示されるテキストです。
<!-- これはコメントです。プレビューには表示されません -->
さらに文章が続きます。
<!--
複数行のコメントも
このように書けます
-->
このように書くと、プレビュー画面や公開されたページには <!-- --> で囲んだ部分は一切表示されません。
実際の表示例
Markdownソース：
# 見出し
この文章は表示されます。
<!-- ここは非表示のコメント -->
この文章も表示されます。
表示結果：
見出し
この文章は表示されます。
この文章も表示されます。
コメント部分が完全に非表示になっているのがわかります。
複数行コメントの書き方
長いコメントや複数行にわたるコメントも簡単に書けます。
<!--
このセクションは後で書き直す予定：
- 項目1の詳細説明
- 項目2の具体例
- 参考リンクの追加
-->
# 公開される見出し
実際のコンテンツがここに入ります。
対応プラットフォーム
以下のような主要なMarkdownレンダラでHTMLコメントがサポートされています：
| プラットフォーム | 対応状況 | 備考 |
|---|---|---|
| GitHub | ✅ 対応 | README、Issues、PRなど |
| Qiita | ✅ 対応 | 記事投稿で利用可能 |
| はてなブログ | ✅ 対応 | Markdownモード |
| Zenn | ✅ 対応 | 記事・本の執筆 |
| Notion | ✅ 対応 | Markdownブロック |
| Typora | ✅ 対応 | プレビューで非表示 |
注意点とトラブルシューティング
一部の処理エンジンでの制限
Markdown処理エンジンによっては、まれにコメントがそのまま出力されてしまうケースもあります。
特に注意が必要な環境：
- 古いMarkdownパーサ
- セキュリティ制限が厳しい環境
- カスタム設定のCMS
確認方法
新しい環境でコメントを使う前は、必ずテストしてみましょう。
<!-- テスト用コメント：これが表示されたらコメント機能が無効です -->
通常のテキスト
コメントアウトの代替手法
ダミーのコードブロックとして書く
HTMLコメントを使いたくない場合は、表示上は目立ちにくいコードブロックにする方法もあります。
空のコードブロック
```
ここはコメントとして扱いたい内容
後で削除予定の文章
```
表示例：
ここはコメントとして扱いたい内容
後で削除予定の文章
特定の言語名を付けたコードブロック
```comment
この部分は開発メモです
- タスク1: 画像を追加
- タスク2: リンクを確認
```
表示例：
この部分は開発メモです
- タスク1: 画像を追加
- タスク2: リンクを確認
引用ブロックを利用
目立ちにくい形でメモを残したい場合は、引用ブロックも使えます。
> **開発メモ：** この部分は後で詳しく書く予定
表示例：
開発メモ： この部分は後で詳しく書く予定
脚注機能を活用
Markdownの脚注機能をコメント代わりに使う方法もあります。
この文章には開発メモがあります[^memo]
[^memo]: 後で追加する内容：統計データ、グラフ、参考文献
脚注はページの下部に小さく表示されるため、目立ちにくいコメントとして機能します。
用途別のコメント活用法
執筆途中のメモ
# 記事タイトル
## はじめに
<!-- TODO: 導入文をもっと魅力的に書き直す -->
現在の導入文...
## 本文
<!--
参考資料：
- 書籍A（123ページ）
- ウェブサイトB（リンク保存済み）
-->
チーム開発でのコミュニケーション
<!--
@tanaka さんへ：
この部分の技術的な詳細について確認お願いします
-->
# API仕様書
## エンドポイント一覧
<!-- @suzuki さん：ここに新しいエンドポイントを追加予定 -->
バージョン管理のためのメモ
<!--
バージョン情報：
- v1.0: 初版作成（2024/01/15）
- v1.1: セクション3を追加（2024/02/01）
- v2.0: 全体構成を見直し（予定）
-->
# ドキュメント
内容...
エディタ別のコメント表示
Visual Studio Code
VSCodeでMarkdownファイルを開くと：
- エディタ画面：コメントがグレーアウト表示
- プレビュー画面：コメントが非表示
Typora
Typoraでは：
- 編集モード：コメントが見える
- プレビューモード：コメントが完全に非表示
GitHub Web Editor
GitHub上でファイルを編集する際：
- 編集タブ：コメントが表示
- プレビュータブ：コメントが非表示
コメントを使う際のベストプラクティス
適切なコメントの書き方
明確で具体的に
<!-- 良い例：具体的で actionable -->
<!-- TODO: 2024/07/15までに最新の統計データに更新 -->
<!-- 悪い例：曖昧 -->
<!-- 後で直す -->
期限や担当者を明記
<!-- @yamada さん：来週の会議までにレビューお願いします -->
<!-- 締切：2024/07/20、確認者：田中さん -->
コメントの管理
定期的な見直し
古いコメントは定期的に削除しましょう。
<!--
作成日：2024/01/15
最終更新：2024/07/03
次回見直し：2024/10/01
-->
Gitとの連携
Gitでバージョン管理している場合、コメントの変更も履歴に残ります。コミットメッセージでコメントの追加・削除を明記すると良いでしょう。
まとめ
今回は「Markdownでコメントアウトする方法」について詳しく解説しました。
重要なポイント：
- Markdown自体にコメント文法はない
- HTMLの
<!-- -->を使えばプレビューや公開時に非表示にできる - 多くの主要プラットフォームでHTMLコメントがサポートされている
- 代替手法として、コードブロックや引用ブロックも活用できる
- コメントは明確で具体的に書き、定期的に見直すことが重要
コメント