How to use GitHub releases as markdown image storage

_How_To_Use_GitHub_Releases_As_Markdown_Image_Storage.md

How to use GitHub releases as markdown image storage

I often uploaded images to GitHub issues and used their URLs in markdown files (such as README.md).
This method was convenient since it didn’t require adding the images to the repository, and each image had a unique URL.
However, in (probably) March 2025, GitHub changed their policy so that accessing images uploaded to issues now requires cookie-based authentication.
This applies even to images uploaded to issues in public repositories.

As a result, the benefit of 'anyone who knows the URL can access the image' has been lost.
Although images still display properly when viewing markdown on GitHub in a browser, they no longer appear when the markdown is rendered elsewhere.
This affects markdown hosted in remote environments such as package registries or GitHub Pages, as well as local environments.
Not being able to preview images while editing markdown is quite inconvenient.

To address this, I came up with a method of embedding images in markdown using GitHub Releases.
GitHub Releases allow you to upload additional files, and those files don’t count toward the repository’s size.
There’s no limit to the number of files or total size, and files in public repository releases have URLs accessible to anyone.

Here’s how you can edit markdown to use this method:

1. Create a public repository on GitHub and create a release.
   In this example, I created a release named docs in the mob-sakai/mob-sakai repository.
   You can make it a pre-release, but note that draft releases are not publicly accessible.
   

2. In VSCode, when you paste or drop an image into a markdown file, it saves the image with a relative path and enables previewing.
   You can also configure the destination path in your settings.
   With the following setting, a .vscode directory is created in the same directory as the markdown file, and images are saved with a filename like <unixTime>.<fileExtName>.
   This format avoids problematic spaces and symbols for shell scripts and ensures a unique name.

   "markdown.copyFiles.destination": {
     "**/README.md": ".vscode/${unixTime}.${fileExtName}"
   }

   

3. After saving the markdown file, download the markdown-image-upload.sh script from this gist and run it as follows:

   markdown-image-upload.sh mob-sakai/mob-sakai docs .vscode/ README.md

   This script scans the markdown for image paths starting with .vscode/, optimizes them using imageoptim, uploads them to the GitHub release, and then replaces the local image paths in the markdown with their corresponding GitHub release URLs.
   

4. Done!

With these steps, you can use GitHub Releases as markdown image storage.
This script is intended for macOS, but similar functionality should be possible on Windows and Linux as well.

---

In Japaneesese:

私はよく画像をGitHub issueにアップロードし、そのURLをmarkdown (README.md等)に貼り付けて使っていました。
この方法はリポジトリに画像を追加することなく、また画像ごとにユニークなURLを持つので便利でした。
しかしながら、2025年の(おそらく)3月に、issueにアップロードした画像にアクセスするためにはクッキーによる認証が必要になりました。
これは、公開リポジトリのissueにアップロードした画像にも適用されます。

もはや、「URLを知っている人は誰でも画像にアクセスできる」という利点は失われてしまいました。
ブラウザでGitHub上のmarkdownを閲覧する分には問題ありませんが、markdownをGitHub以外の場所で表示する場合は、画像が表示されなくなります。
これは、パッケージレジストリやGitHub Pagesなどのリモート環境にホストされたmarkdownだけでなく、ローカル環境でも同様です。
markdownを編集する際に画像をプレビューできないのは非常に不便です。

そこで、GitHubのリリース機能を利用して、画像をmarkdownに貼り付ける方法を考えました。
GitHubのリリースは追加のファイルをアップロードでき、これらのファイルはリポジトリのサイズを肥大させません。
ファイル個数や合計サイズにも制限はなく、公開リポジトリのリリースは誰でもアクセスできるURLを持っています。

具体的なmarkdownの編集方法は以下の通りです。

1. GitHubに公開リポジトリを作成し、リリースを作成します。
   ここではmob-sakai/mob-sakaiというリポジトリにdocsというリリースを作成しました。
   リリースはプレリリースでも大丈夫ですが、ドラフトリリースは公開されないため注意してください。
   

2. VSCodeには、markdownに画像をペースト/ドロップすると、画像を相対パスで保存し、プレビューする機能があります。
   また、設定から保存先を変更することもできます。
   次のように設定すると、markdownと同じディレクトリに.vscodeというディレクトリが作成され、その中に画像が<unixTime>.<fileExtName>という名前で保存されます。
   このファイル名はシェルスクリプトに都合の悪い空白や記号が含まれず、ユニークな名前になります。

   "markdown.copyFiles.destination": {
     "**/README.md": ".vscode/${unixTime}.${fileExtName}"
   }

   

3. markdownを保存後、このgistにアップロードされているmarkdown-image-upload.shをダウンロードし、以下のように実行します。

   markdown-image-upload.sh mob-sakai/mob-sakai docs .vscode/ README.md

   このスクリプトは、markdownに記述されている「.vscode/」で始まる画像のパスを取得し、imageoptimで軽量化した後にGitHubのリリースにアップロードします。
   その後、markdown内の画像パスをアップロード先のURLに変更します。
   

4. Done!

以上の手順により、GitHubのリリースをmarkdownの画像ストレージとして利用することができます。 このスクリプトはMacOS向けですが、WindowsやLinuxでも同様の事ができるでしょう。

markdown-image-upload.sh

#!/usr/bin/env bash

help()
{
    echo "Usage: markdown-image-upload.sh <repo> <tag> <img_dir> <markdown_file>"
}

[ "$4" = "" ] && help && exit 0

repo="$1"
tag="$2"
img_dir="$3"
file="$4"
dir_path=$(dirname "$file")
file_name=$(basename "$file")

(
    cd "$dir_path" || exit 1

    images=$(grep -o "$img_dir"'[^")]*' "$file_name")
    [ -z "$images" ] && echo "No images found." && return

    echo "$images" | while read -r img; do
        [ -f "$img" ] || { echo "Skip missing: $img"; continue; }
        echo "Optimizing: $img"
        npx -y imageoptim-cli "$img"
        echo "Uploading:  $img"
        gh release upload "$tag" "$img" -R "$repo" --clobber
    done

    sed -i '' "s|$img_dir|https://github.com/$repo/releases/download/$tag/|g" "$file_name"
    echo "✅ Complete!"
)