100% プライベート — すべてブラウザ内で処理
マークダウン コメントアウト — HTMLコメントの書き方
Markdownに<!-- メモ -->と書くと、ソースには残り、ページからは消えます。非表示のマークダウン コメントアウト例をライブで編集できます。
MD Viewer チーム
Visible text
マークダウン コメントアウトとは、HTMLコメントを流用した技法です。ソースに<!-- あなたのメモ -->と書くと、レンダラーは完成ページからそれを隠し、ファイルには残します。上のプレイグラウンドはこの挙動の両面を並べて示します。ソースペインにはマークダウン コメントアウトがあり、プレビューペインにはありません。マーカーの間のテキストを編集すると、非表示のメモが変化しながら、決してレンダリング結果に現れない様子が分かります。
マークダウン コメントアウトは、ファイルには必要だがページには見せてはいけないもののために使います。レビューのメモ、TODO、今後の編集者への指示、書き直し中に退避したセクション、テンプレートがどのフィールドを受け付けるかの提醒。コメントはファイル内のただのテキストなので、バージョン管理、diff、grep、検索をすべて生き延びます。レンダラーではなく協力者へのメモです。
この技法には2つの正直な注意が付きます。第一に、マークダウン コメントアウトは非公開ではありません。生ファイルやページソースを開く人は誰でも見えるため、秘密情報、認証情報、未発表の告知を入れてはいけません。第二に、HTMLをすべて除去するレンダラーはコメントも除去します。実害はありませんが、メモは予想より早く消えます。以下の例はブロック形式とインライン形式の両方を扱います。
マークダウン コメントアウトの構文リファレンス
| 入力 | 結果 |
|---|---|
| <!-- メモ --> | 独立行のコメント。プレビューでは非表示 |
| テキスト <!-- メモ --> テキスト | 可視語の間に隠れるインラインコメント |
| <!-- 1行目 2行目 --> | 複数行にわたるコメント |
| <!-- **下書き** --> | コメント内の書式も非表示 |
| <!-- (閉じマーカーなし) | 壊れたコメント。以降のファイル全体が消えることがある |
マークダウン コメントアウトの書き方
- 1
<!-- で開く
開始マーカーを隠したい内容の始まりに置きます。ブロックのマークダウン コメントアウトなら行頭に、インラインのメモなら文の途中に。
- 2
メモを書く
マーカーの間はすべてコメントです。プレーンテキスト、Markdown書式、下書きの段落でさえ何もレンダリングされません。
- 3
--> で閉じる
閉じマーカーは必須です。閉じられていないマークダウン コメントアウトは後続のすべての文字を飲み込みます。コメントでページが壊れる最多の経路です。
- 4
プレビューで確認
ソースペインにはメモが見え、プレビューでは消えています。この分割ビューこそ、実際のドキュメントパイプラインにおけるマークダウン コメントアウトの挙動そのものです。
マークダウン コメントアウトの使いどころ
最も強い用途は編集上のもの、つまり必要な場所に指示を残すことです。テンプレートは各セクションの上に<!-- 下のAPIキー欄を記入 -->と書けます。変更履歴は未公開項目の横に<!-- 項目起草済み、法務確認待ち -->と置けます。長いREADMEは古いセクションを削除する代わりにコメントアウトで歴史を保持できます。テキストはファイルに残るのでgit blameが帰属を示し、将来の編集者はマーカーを消すだけで内容を復元できます。
2番目の用途は構造的なものです。デバッグ中に壊れたコードフェンスを退避する、数値の確認が取れるまで下書きの表を隠す、生成された目次の挿入位置を印す——いずれもマークダウン コメントアウトの自然な仕事です。一方、コメントをセキュリティ機構にしてはいけません。内容は公開ファイルと共に出荷されます。すべてのマークダウン コメントアウトは、表示される礼儀正さを持った公開テキストとして扱ってください。
共有リポジトリでは、コメントは次の編集者へのメッセージです。日付を入れ、頭文字を入れ、次に何をすべきか書く。<!-- TODO(mia): Q3リリース前に価格を確認 -->は<!-- 確認 -->より1年長生きします。タスクが終わったら墓標に書き換えるのではなく、マークダウン コメントアウト全体を削除してください。歴史はバージョン管理に属し、コメントの堆積には属しません。
マークダウン コメントアウトの間違い
<!-- 閉じていないメモ
<!-- 閉じたメモ -->
閉じないコメントは、その後のすべて——時にはファイルの残り全部——を隠します。マークダウン コメントアウトは必ず閉じてください。
<!-->罠のマーカー -->
<!-- 素朴なメモ -->
<!-- の直後に>を置くとコメントが即座に閉じ、残りが可視テキストとして漏れます。開始マーカーの後にはスペースを置いてください。
コメントにAPIキーを保存
秘密はMarkdownに入れない
マークダウン コメントアウトは生ファイルを読む人全員に見えます。暗号化にもアクセス制御にもなりません。
コメントはダウンロードしたファイルにも残る
このページからのコピーやダウンロードは、マークダウン コメントアウトをバイト単位で保存します。非表示にするのはレンダリングだけで、保存したファイルは開いたファイルと同一です。
よくある質問
出典と仕様引用
“Comments must start with the four character sequence U+003C LESS-THAN SIGN, U+0021 EXCLAMATION MARK, U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS (<!--).”
“Raw HTML (and thus, HTML comments) is passed through unaltered — but the rendered output is the browser’s decision.”