【コピペで使える】Markdownコメント・コメントアウトの書き方完全ガイド｜非表示メモ・HTMLコメント・リンク定義ハック・エディタ対応一覧まで徹底解説

Markdown（マークダウン）でドキュメント、技術記事、ブログ記事、業務マニュアル、仕様書を作成しているとき、「執筆用の自分用メモやTODOを画面に出さずに残したい」「一時的に文章を非表示（コメントアウト）にして、後で復活させられるようにしたい」「記事テンプレートや執筆ガイドラインをファイル内に埋め込んでおきたい」と感じたことはありませんか？

プログラミング言語であれば // や /* ... */、# などでおなじみのコメントアウトですが、Markdownでは「どう書けば画面に表示されないコメントになるのか？」「複数行をまとめて非表示にする方法は？」「GitHub、VS Code、Notion、Obsidian、Qiita、Zennなどでちゃんと非表示になる？」「HTMLソースから第三者に見られてしまう危険性はない？」といった疑問を持つ方が非常に多くいます。

結論から言うと、Markdown自体には専用のコメント記号は定義されていませんが、HTMLコメント記法（<!-- コメント -->）やリンク定義ハック（[//]: # (コメント)）を利用することで、簡単に文章を非表示にできます。

この記事では、コピペですぐに使える「Markdownコメント逆引きチートシート」をはじめ、基本となるHTMLコメントの書き方、複数行コメント、リンク定義ハックの仕組み、主要エディタ・Webサービス（GitHub / VS Code / Notion / Obsidian / Qiita / Zenn）の対応状況とショートカット、そして公開時に注意すべきセキュリティリスクまでを徹底解説します！

【早見表】Markdownコメント・コメントアウト逆引きチートシート

まずは、Markdownで使える代表的なコメント・非表示記法を一覧表にまとめました。目的に応じて使い分けてみてください。

なぜMarkdownには専用のコメント記法がないのか？

プログラミング言語のように // コメント や /* コメント */ といったMarkdownネイティブの構文が存在しない理由には、Markdownの成り立ちが深く関わっています。

Markdownは2004年にジョン・グルーバー（John Gruber）氏によって、「プレーンテキストのままでも読みやすく、かつ簡単にHTMLに変換できる軽量マークアップ言語」として開発されました。

その設計思想の中心にあるのが、「Markdownの構文でカバーされていない表現は、そのまま生のHTML（Raw HTML）を書いてよい」というルールです。HTMLにはすでに <!-- --> という確固たるコメント構文が存在していたため、Markdown独自に新しいコメント構文をわざわざ定義する必要がなかったのです。

1. 基本の書き方：HTMLコメント記法（<!– –>）

Markdownでコメントアウトを行う最も標準的で汎用性の高い方法が、HTMLのコメントタグ <!-- コメント内容 --> を使用する方法です。

1行コメントの書き方

行全体、または文章の前後に <!-- と --> を記述します。

<!-- ここは執筆者用の非表示メモです。ブラウザには表示されません -->
これは通常の本文です。読者にはこの行だけが表示されます。

ブラウザやMarkdownビューアでの表示結果：

コメントで囲まれた部分は完全に無視され、画面上には一切出力されません。

複数行コメントの書き方

段落全体や複数の見出し、リスト、コードブロックなどをまとめて非表示にしたい場合は、開始行に <!--、終了行に --> を配置します。

<!--
### 一時的に非表示にしたいセクション
- 下書き項目1
- 下書き項目2

後で推敲してから公開する予定の文章をここにストックしておきます。
```javascript
console.log("未完成のコード");
```
-->

ここから公開用の本文が始まります。

ブラウザでの表示結果：

このように、Markdown要素（見出し、箇条書き、コードブロック）が含まれていても、<!-- から --> までのすべての内容が丸ごと非表示になります。

文中のインラインコメント（行の途中にメモを挟む）

文中の特定単語の直後や文末に、インラインでメモを挟み込むことも可能です。

今年の目標売上は1億円<!-- 役員会での確定数値を確認すること -->を達成する見込みです。

ブラウザでの表示結果：

文章の前後がつながって表示されるため、編集者同士の校正メモや推敲時の検討メモとして便利に使えます。

2. 発展テクニック：リンク定義記法ハック（[//]: #）

「HTMLコメントだとWebサイト公開時にソースコード（HTML）にメモが残ってしまうのが嫌だ」という場合に広く使われているのが、Markdownの「リンク参照定義」を悪用（ハック）したコメント手法です。

リンク定義ハックの仕組み

Markdownには、長いURLを文末にまとめて定義する「参照リンク（Reference-style Link）」という機能があります。

[Google][1] を開く

[1]: https://www.google.com "Google検索"

Markdownパーサーの仕様上、「本文中から一度も参照（呼び出し）されていないリンク定義は、HTMLへの変換時に完全に破棄される（HTMLタグとしても出力されない）」という性質があります。

この仕様を利用して、リンクの識別子に //（プログラミングのコメント記号に見立てた文字列）を指定し、URL部分にダミーの文字列を記述するのがリンク定義ハックです。

代表的な書き方パターン

よく使われる記法には以下のバリエーションがあります。

[//]: # (ここにコメント内容を記述します)
[//]: # "ダブルクォーテーションで囲むパターン"
[//]: # 'シングルクォーテーションで囲むパターン'

[//]: <> (不等号を使ったパターン。VS Code等でURLハイライトされにくい)

[comment]: <> (識別子をわかりやすくcommentにしたパターン)

最も推奨される書き方：

リンク定義ハックで複数行コメントを書く方法

リンク定義ハックで複数行のコメントを残す場合は、括弧内で改行するか、行ごとに [//]: # を記述します。

[//]: # (
ここに複数行の
コメントやメモを
記述できます
)

または：

[//]: # (1行目のコメント)
[//]: # (2行目のコメント)
[//]: # (3行目のコメント)

HTMLコメント vs リンク定義ハック 徹底比較

どちらを使うべきか迷ったときは、以下の違いを参考に選んでください。

3. 主要エディタ・プラットフォーム別対応状況＆ショートカット

執筆環境によってコメントのレンダリング挙動や便利な機能が異なります。主要なツールでの対応状況を検証しました。

VS Code（Visual Studio Code）でのコメントアウト操作

VS CodeはMarkdownファイルのコメントアウト操作が最も洗練されています。

• 1行コメントアウト： コメントにしたい行にカーソルを置き、Ctrl + /（Macは Cmd + /）を押すと、即座に <!-- 行の内容 --> に変換されます。もう一度押すと解除（アンコメント）されます。
• 複数行ブロックコメントアウト： 複数行をマウスやキーボードで範囲選択し、Shift + Alt + A（Macは Shift + Option + A）を押すと、選択範囲全体が <!-- ... --> で囲まれます。
• おすすめ拡張機能： 「Markdown All in One」を導入すると、キーボードショートカットや目次自動生成とともにコメント管理が非常にスムーズになります。

Obsidianの独自コメント記法（%%）

人気ナレッジベースアプリ「Obsidian」では、標準のHTMLコメントに加えて、Obsidian独自のパーセント記法 %% がサポートされています。

%% これはObsidian専用のインラインコメントです %%

%%
ここはObsidian専用の
複数行コメントブロックです。
ライブプレビューでも読書ビューでも非表示になります。
%%

Notionでコメントアウト・非表示を実現する代替策

NotionはMarkdownテキストをペーストした際にリッチブロックへと自動変換する仕組みを採用しているため、<!-- --> や [//]: # を記述してもそのままプレーンテキストの文字として画面に残ってしまいます。

Notion内で画面に出したくないメモを残したい場合は、以下の代替機能を利用してください：

1. Notion標準の「コメント機能」を使う： テキストを選択してポップアップから「コメント」を追加するか、Ctrl + Shift + M（Macは Cmd + Shift + M）を押す。サイドバーにスレッド形式でメモが残せます。
2. 「トグルリスト（Toggle）」に隠す： /toggle と入力してトグルを作成し、その中にメモを収納して折りたたんでおく。
3. 「コールアウト（Callout）」をグレーアウト： /callout で背景をグレーにして「執筆用メモ」と明記しておく。

4. 【超重要】セキュリティと公開時の注意点（HTMLソース流出リスク）

Markdownのコメントアウトを使用する上で、最も注意しなければならないのが「情報の漏洩（情報流出リスク）」です。

コメントに絶対に書いてはいけないNG情報

ブログ記事、Webサイト、GitHubの公開リポジトリ（パブリックリポジトリ）にアップロードするMarkdownファイルには、以下の情報を絶対にコメントとして残さないでください。

• 認証情報・機密データ： パスワード、APIキー、アクセストークン、秘密鍵、データベース接続文字列
• 個人情報・社内情報： 社員や顧客の氏名・電話番号・メールアドレス、社内限定URL、非公開サーバーのIPアドレス
• 未公開のビジネス情報： リリース前の新機能情報、未発表の価格設定、競合他社に関する内部評価
• 感情的なメモや愚痴： 「この仕様は意味不明」「クライアントの要望で仕方なく追加」といった制作時の裏話や愚痴

静的サイトジェネレーター（SSG）での挙動

Hugo、Jekyll、Gatsby、Astro、Next.js（Contentlayer等）などの静的サイトジェネレーターを使ってMarkdownからWebサイトをビルドしている場合、パーサーの設定によって挙動が分かれます：

• HTMLコメントがそのまま本番HTMLに出力される設定： デフォルトの多くはこの挙動です。ビルド後のHTMLファイルに <!-- メモ --> がそのまま残ります。
• HTMLコメントをビルド時に自動除去（Strip）する設定： HTMLミニファイア（HTML Minifier）やパーサーオプション（例: GoldmarkのHTML破棄設定）を有効にしている場合、本番HTMLからは自動削除されます。

確実性を求める場合や、設定に依存したくない場合は、「公開用ファイルからはコメントそのものを削除する」か、前述の「リンク定義ハック（[//]: #）」を採用してください。

Gitコミット履歴に残るリスク

「公開前にコメント行を削除したから安心」と思っていても、Gitのコミット履歴（Commit Log）には過去に記述したコメントがそのまま残ります。

GitHubでリポジトリをパブリック（全体公開）にした場合、コミットログを遡れば過去のコメントを誰でも閲覧できてしまいます。一度でも機密情報を書き込んでコミットしてしまった場合は、Git履歴の書き換え（git filter-branch や BFG Repo-Cleaner 等）が必要になるため注意しましょう。

5. 【コピペで使える】実践テンプレート＆活用シーン

日常のドキュメント作成や開発現場ですぐに役立つ、実用的なコメントテンプレート集を用意しました。

テンプレート1：執筆用アウトラインとTODO管理

記事の冒頭にTODOリストや構成案をメモしておき、執筆完了したものからチェックしていくパターンです。

<!--
【執筆前TODO & 構成メモ】
- [x] 導入文の作成（想定読者：Markdown初心者〜中級者）
- [x] HTMLコメントの書き方解説
- [ ] エディタ比較表の画像作成と差し替え
- [ ] 参考URLのリンクチェック
ターゲットKW：markdown コメント / 狙いPV：月間5,000PV
-->

# 記事タイトル

ここに本文を書き進めていきます...

テンプレート2：チーム向け執筆ガイドライン・テンプレート

共同編集するドキュメントや社内Wiki、OSSのREADMEテンプレートに執筆ルールを埋め込んでおくパターンです。

# 機能名仕様書

<!--
【執筆ガイドライン】
1. 各機能の概要は200文字以内で簡潔にまとめてください。
2. APIエンドポイントを記載する際は、必ずリクエスト・レスポンス例を併記してください。
3. 未確定の仕様は [未確定] プレフィックスを付けて記述してください。
-->

## 1. 機能概要
ここに機能の概要を記述します。

テンプレート3：一時的な下書き・推敲用ストック

「文章を削るか迷っているが、後で復活させるかもしれない」という段落をキープしておくパターンです。

Markdownは非常に軽量で扱いやすいフォーマットです。

<!--
【推敲メモ（削除候補）】
以前のバージョンでは以下のような複雑な設定が必要でしたが、
最新版では自動認識されるようになったため説明を省略。
要望が多ければ後日復活させる。
-->

続いて、具体的なインストール手順について見ていきましょう。

6. コメントアウトが崩れる・表示されてしまう原因と対処法

「コメントアウトしたはずなのに、プレビューに文字が表示されてしまう」「コメント以降の文章がすべて消えてしまった」というトラブルの主な原因と解決策です。

原因1：コメント内にハイフンが連続している（–）

HTMLの仕様上、コメントの内部に --（ハイフン2つ連続）を含めると、パーサーが終了タグと誤認して構文エラーを引き起こす場合があります。

<!-- ❌ エラーになりやすい例：ハイフンの連続 -->
<!-- ------------- ここからセクション ------------- -->

<!-- ⭕ 推奨される例：イコールやアスタリスクを使う -->
<!-- ============= ここからセクション ============= -->
<!-- ************* ここからセクション ************* -->

原因2：全角文字（記号やスペース）が混ざっている

<！-- や --＞ のように感嘆符や不等号、ハイフンが全角になっていると、Markdownパーサーはコメントタグとして認識せず、通常の文字列として画面に出力してしまいます。必ず半角英数記号で入力してください。

原因3：閉じタグ（–>）の書き忘れ

<!-- で開始した後に --> で閉じるのを忘れると、ファイルの末尾までのすべての文章がコメントとみなされ、画面から丸ごと消滅してしまいます。必ず開始と終了が対になっているか確認しましょう。

原因4：コードブロックの内部にコメントを書いている

バッククォート3つ（```）で囲まれたコードブロックの中に <!-- --> を書いても、HTMLコメントとしては解釈されず、プログラムコードの文字列としてそのまま表示されます。

```html
<!-- コードブロックの中では、この行自体が画面に表示されます -->
<div class="container"></div>
```

コードブロック全体を非表示にしたい場合は、コードブロックの外側を <!-- と --> で囲んでください。

7. よくある質問（FAQ）

まとめ｜Markdownコメントをマスターして快適な執筆環境を作ろう

Markdownには専用のコメント記法はありませんが、HTMLコメント（<!-- -->）やリンク定義ハック（[//]: # ()）を上手に使い分けることで、効率的で美しいドキュメント管理が実現できます。

自分用のTODO管理やチームでのドキュメント共有に、ぜひ本記事のテクニックを取り入れてみてください！

📚 あわせて読みたいMarkdown関連記事

• 【コピペで使える】Markdown記法一覧・チートシート｜基本の書き方から応用・早見表まで完全網羅
• 【コピペで使える】Markdown注釈・脚注の書き方完全ガイド｜構文ルール・複数行・ツール対応・チートシートまで徹底解説
• 【コピペで使える】Markdownリンクの書き方完全ガイド｜ページ内リンク・別タブ・相対パス・画像リンクまで網羅
• 【コピペで使える】Markdown表（テーブル）の書き方完全ガイド｜配置揃え・セル結合・改行・便利ツールまで徹底解説
• 【コピペで使える】Markdown箇条書き・リストの書き方完全ガイド｜インデント階層化・番号付き・段落やコードの挿入まで徹底解説
• Markdownコードブロックの書き方完全ガイド｜シンタックスハイライト・言語一覧
• Markdownの引用記法完全ガイド！複数行・ネスト（入れ子）・引用内リストまで徹底解説
• Markdownで折りたたみ（トグル・アコーディオン）を作る方法｜details・summaryタグの使い方と空行ルール