Markdownコメントの書き方：表示されない注釈と注意点

まず覚えるならHTMLコメント

注釈を `<!--` と `-->` で囲みます。HTMLコメントを扱えるレンダラーでは、その範囲が本文として表示されません。

これはMarkdown固有のコメント命令ではなく、Markdown内に書いたHTMLです。公開先が生HTMLを無効化している場合は、文字として表示されたり変換時に削除されたりします。

# 更新案内

<!-- 公開前に日付を確認する。 -->

新しい版を公開しました。

更新案内

新しい版を公開しました。

画面から消えてもソースからは消えない

コメントの文章は `.md` に保存されたままです。ソース表示、Gitの履歴、ダウンロードした原稿を開けば読めます。

公開前の確認事項や差し替え予定など、読まれても問題のない編集情報だけを書いてください。知られてはいけない内容は、コメント化するのではなく、ファイルと履歴から適切に取り除く必要があります。

複数行のメモも同じ記号で囲む

短い注釈は一行で書けます。校正項目が複数ある場合は、開始行に `<!--`、最後に `-->` を置けば複数行にできます。

閉じ記号を忘れると、その後の本文までHTMLブロックとして扱われる可能性があります。長いコメントを編集した後は必ず最終レンダラーで確認します。

<!--
公開前の確認
- リンク先
- 表の合計
- 画像の代替テキスト
-->

対応するレンダラーでは、この確認一覧は本文に表示されません。

GitHubではREADMEのコード表示まで確認する

GitHub公式ドキュメントは、レンダリング結果から内容を隠す方法としてHTMLコメントを案内しています。一方で、READMEのコード表示を開けばコメントは読めます。

共同作業者向けの注意書きには便利ですが、公開リポジトリで閲覧者に知られて困ることは書けません。

## セットアップ

<!-- package.json更新時にコマンドも見直す。 -->

```sh
npm install
```

レンダリング画面では見えず、コード表示では読めます。

• GitHub Docs：コメントで内容を隠す

Obsidianの`%%`は便利でも専用記法

Obsidianでは `%%` で囲んだ部分を編集用コメントとして扱い、閲覧表示では隠せます。インラインにも複数行にも使えます。

ただしCommonMarkの共通記法ではありません。同じファイルをGitHubや別のCMSで開くと、そのままの文字が表示される場合があります。保管先をObsidianに限定しないなら、HTMLコメントのほうが移植しやすい選択です。

原稿は完成です。%%表の数値だけ再確認する%%

`%%`をコメントと解釈しないアプリでは、メモも表示されます。

• Obsidianヘルプ：コメント

コードブロック内ではコメント記号も表示対象

コードフェンスの中身は文字どおりに表示されます。HTMLコメントの書き方を説明したいときは便利ですが、その場所で注釈を非表示にする効果はありません。

フェンスに付ける `html` などの言語名は色分けの指定です。中のMarkdown処理を再開するスイッチではありません。

```html
<!-- この行はコードとして表示されます。 -->
<p>例</p>
```

コメント記号を含むHTMLコードブロックが見えます。

表示が違うときの切り分け方

CommonMarkはHTMLコメントを生HTMLとして扱いますが、製品側の安全設定で生HTMLを無効にすることがあります。書き出し処理がコメントを削除する場合もあります。

一つのプレビューだけで互換性を決めず、実際の公開先と出力ファイルを確認してください。

公開前に行う四つの確認

コメントは原稿整理の補助です。公開工程の最後には、必要なものだけを残し、不要な注釈を片付けます。

1. 公開先を決めるGitHub、Obsidian、CMSなど、最終レンダラーを先に明確にします。
2. 読まれてよい内容だけを書くコメントは非表示になっても、ソースから読める前提で書きます。
3. ソースと表示を両方見るプレビューだけでなく、元ファイルとダウンロード結果も確認します。
4. 役目を終えた注釈を削除する次の編集者に必要な背景だけを残します。

• CommonMark：HTMLブロック
• CommonMark：生HTML

関連ツール