[🛠] How to Add Images to a GitHub Pages Blog

✨ GPT Summary 　

A guide to adding images to a GitHub Pages blog.

I wanted to add images to my GitHub Pages blog, but then a few issues came up.

• I had forgotten how to do it.

• I remembered that each repository had a 1GB storage limit.
  • Updated on 2025.1.13
    • 1GB is a recommendation, not a hard limit.
    • If a repository exceeds 5GB, GitHub may send an email.
    • There is no separately stated total storage limit.
    • A single file has a 100MB limit. (Git LFS can solve this.)
    • If the repository gets large, clone and push speed are likely to be affected.
• I remembered that using external image hosting was also an option.

… So what is the best approach in this era?

✨ Click ✨

The post below was written with reference to an answer from GPT-4o.

1. The Common Method: Use the assets/images Folder

Store images inside the blog project’s assets/images folder and link to them.

Example

• Image path:

  assets/images/example.jpg
  

• Use it in a post:

  ![Image description](/assets/images/example.jpg)
  

This method is simple, but it can become a problem if the repository reaches the recommended 1GB size.

---

2. What to Do When Storage Becomes an Issue

1) External Image Hosting

Use an external service instead of storing images in the GitHub repository.

• Imgur: Upload the image and use its URL.

  ![Image description](https://i.imgur.com/example.jpg)
  

• Google Photos/Dropbox: Use cloud storage links.

---

2) Create a Separate Image Repository

Create a separate GitHub Pages repository dedicated to images.

1. Create a new repository. (Example: blog-images)
2. Upload and push the images.

3. Use the image link:

   ![Image description](https://username.github.io/blog-images/example.jpg)
   

---

3. Prepare for URL Changes

You can reduce the burden of updating links by setting a default image path in _config.yml.

1. Add this to _config.yml:

   image_baseurl: "/assets/images"
   

2. When writing a post:

      
   ![Image description]({{ site.image_baseurl }}/example.jpg)
      
   

3. If you later move to a separate image repository, update only image_baseurl:

   image_baseurl: "https://username.github.io/blog-images"
   

---

4. Conclusion

For now, store images in the assets/images folder. If storage becomes an issue later, introduce external hosting or a dedicated image repository.