Markdown の画像に必要な文脈を添える
画像入りの Markdown を使い、参照先と説明の準備から書き出し後の確認までを説明します。共有ページやログインが必要な画像、期限切れリンク、相対パスを切り分け、不要な画面領域を除きます。実際の表示サイズで画像と本文を読み、公開時の説明と代替テキストも用意する手順です。
Markdown に画像を入れるときは、リンクが開くだけでは不十分です。何を示し、なぜ必要で、編集できる原稿はどこにあるのかを読者に伝えます。Markdown コンバーターで画像と文章の組み合わせを確認してから共有しましょう。
本文で扱う要点を説明する画像を選びます。たとえばリリースのチェックリストなら、レビューがまだ終わっていないことを示せます。装飾用のノートパソコンの写真では、その状態は伝わりません。説明は画像の近くに置き、意味を読者の推測に任せないようにします。
Markdown の画像構文では、角括弧に説明、丸括弧に参照先を書きます。構造は CommonMark 仕様で確認できます。説明には、ファイル名や単なる「画像」ではなく、この文脈で重要な内容を書きます。
このデモでは、用意されたチェックリスト画像を使います。画像の説明とその下の一文はセットで残します。前者は見た目を説明し、後者は原稿を引き続き編集できることを伝えています。
# Image with useful context
The source document remains editable; the exported card is for sharing.
出力は画像と文章を一つにまとめたもので、社内レビューの状況共有に使う想定です。元のチェックリストの編集可能なコピーではありません。未完了の項目がメッセージの中心なら、投稿の本文にもその内容を書きましょう。
まず画像の URL を直接開き、目的の画像が表示されるか確認します。コピーしたアドレスが共有ページ、期限切れのリンク、ログイン中だけ見られるファイルを指している場合があります。リポジトリで使える相対パスも、別の Web エディターでは参照先が分からないことがあります。
自分で管理でき、共有する権利のある画像を使います。読み込みを直すためだけに非公開のスクリーンショットを公開せず、機密部分を隠すか、安全なデモ画像を選んでください。URL を差し替えたらアクセスを再確認し、書き出す前にプレビューを見ます。
横長のスクリーンショットにある小さなラベルは、外側のカードが整っていても読めないことがあります。関係のない画面領域を切り取り、説明に必要な部分を残します。小さすぎる原画像を拡大しても、元からない細部は戻りません。
ダウンロードしたファイルでは、埋め込んだ画像と周囲の文章を実際の表示サイズで確認します。投稿には読み取れる文章の説明も添えましょう。Markdown 原稿の画像説明は、書き出した画像に設定する代替テキストの代わりにはなりません。
公開前に画像入りの Markdown をプレビューしてください。
関連ガイド：二つの画像を横に並べる、Markdown を PNG に書き出す。