【ツール活用｜豆知識】Markdown画像リンク管理の極意！リポジトリをスリムに保ち、どこでもリッチなドキュメントを

はじめに

皆さんは、Markdownでドキュメントを作成する際、画像ファイルの管理に悩んだことはありませんか？リポジトリに画像を直接含めてしまうと、あっという間にリポジトリが肥大化し、クローンやプッシュに時間がかかる…なんて経験、あるのではないでしょうか。本記事では、リポジトリを軽量に保ちつつ、いつでもどこでも画像付きでリッチなドキュメントを参照できる、そんな理想的なMarkdown画像リンク管理のコツをご紹介します。

基礎知識：画像ホスティングとMarkdown

まず、今回のテーマを理解するために、いくつかの関連用語と仕組みを抑えておきましょう。

Markdown: テキストベースで構造化された文書を作成するための軽量マークアップ言語です。プレーンテキストで記述でき、簡単な記法で見出し、リスト、リンク、画像などを表現できます。
画像ホスティング: 画像ファイルをインターネット上のサーバーにアップロードし、URLを介してアクセスできるようにするサービスのことです。これにより、ローカル環境に依存せず、どこからでも画像を参照できるようになります。
リポジトリ軽量化: Gitなどのバージョン管理システムで管理されるリポジトリ（コードやドキュメントの保管場所）のファイルサイズを小さく保つことです。リポジトリが軽量であるほど、操作が高速になり、ストレージ容量も節約できます。

今回のTipsでは、これらの要素を組み合わせ、画像ファイルをリポジトリ外に配置することで、リポジトリの軽量化と、場所を選ばないドキュメント参照環境の実現を目指します。

実装/解決策：クラウドストレージとGitHubの活用

リポジトリ内に画像を置かずに管理する最も一般的な方法は、クラウドストレージサービスを利用することです。

クラウドストレージへの画像アップロード: Google Drive, Amazon S3, Dropboxなどのクラウドストレージに、ドキュメントで使用する画像をアップロードします。
画像URLの取得とMarkdownへの埋め込み: アップロードした画像ファイルの公開URLを取得します。取得したURLをMarkdownの画像記法 `![alt text](image_url)` に埋め込みます。
GitHubなどのホスティングサービスでの自動ホスティング（補足）: GitHubなどの一部のプラットフォームでは、Markdownファイルに画像を貼り付けた際に、自動的にGitHub上にホストしてくれる機能があります。この機能を利用すると、手軽に画像を含めたドキュメントを作成できます。ただし、この機能はプラットフォーム依存であり、常に利用できるとは限らないため、汎用的な管理方法としてはクラウドストレージの利用が推奨されます。

この方法の利点は、画像ファイルがリポジトリに含まれないため、リポジトリのサイズが肥大化しないことです。また、画像はインターネット上に配置されるため、ドキュメントを閲覧する場所を選ばず、常に最新の画像を参照できます。

サンプルプログラム：Markdownファイルでの画像リンク指定例

ここでは、クラウドストレージで取得した画像URLをMarkdownに埋め込む例を示します。実際に画像ファイルを用意し、クラウドストレージにアップロードして、その公開URLを以下の `image_url` の部分に置き換えて試してみてください。

サーバー構成図

このドキュメントでは、弊社の主要なサーバー構成図を掲載します。

Webサーバー構成

Webサーバーの構成は以下の図を参照してください。

![Webサーバー構成図](https://example.com/images/webserver_config.png “Webサーバー構成図”)

DBサーバー構成

データベースサーバーの構成は以下の図を参照してください。

![DBサーバー構成図](https://example.com/images/dbserver_config.png “DBサーバー構成図”)

—
最終更新日: 2023/10/27

上記の例では、`https://example.com/images/webserver_config.png` と `https://example.com/images/dbserver_config.png` が、クラウドストレージで取得した公開画像URLです。`![alt text](image_url “optional title”)` の形式で、画像の説明（alt text）と画像URLを指定します。オプションで画像にマウスカーソルを合わせた際に表示されるタイトルも指定できます。

応用・注意点：現場で役立つ補足情報と注意点

画像URLの管理

定期的なURLの確認: クラウドストレージの仕様変更や、誤操作によって画像URLが無効になる可能性があります。定期的に画像URLが有効であることを確認しましょう。
画像バージョニング: 画像を更新した場合、URLも変わる場合があります。URLの変更があった際は、Markdownファイルも忘れずに更新してください。可能であれば、URLにバージョン情報を含める（例: `…/image_v2.png`）などの工夫も有効です。
アクセス権限: 画像がプライベートな情報を含む場合は、アクセス権限の設定に注意が必要です。公開URLが意図しない範囲に共有されないよう、各クラウドストレージのセキュリティ設定を適切に行いましょう。

リポジトリ軽量化のさらなる工夫

`.gitignore` の活用: もし誤って画像ファイルをリポジトリに追加してしまった場合でも、`.gitignore` ファイルに画像ファイルの拡張子（例: `.png`, `.jpg`）を記述しておけば、Gitの追跡対象から外すことができます。
Git LFS (Large File Storage) の検討: 非常に大きなバイナリファイル（画像だけでなく、動画や実行ファイルなども含む）を頻繁に扱う必要がある場合は、Git LFSの導入も検討に値します。Git LFSは、大きなファイルをリポジトリ本体から分離して管理することで、リポジトリの軽量化に貢献します。ただし、Git LFSの利用には別途設定やサーバー側の対応が必要になります。

これらのTipsを活用して、より効率的で快適なドキュメント管理を目指しましょう！