How to Host Images for Your GitHub Blog: 3 Practical Options

Images make blog posts easier to scan and more engaging, but large image files can slow down a site and increase repository size. For a GitHub-hosted blog, you can store images with the site, use GitHub issue attachments, or keep media in a separate repository. The right option depends on how many images you publish and how much control you want over them.

1. Store images in your site repository

For a small blog with a few images per post, this is usually the simplest approach. Add an images/ or assets/ folder to your repository, commit optimized images alongside your posts, and link to them with a relative path:

![A descriptive caption](/images/my-post-image.webp)

Keeping each post’s images with the site makes them easy to manage and version together. Compress images before committing, and prefer an efficient format such as WebP when it suits the image. Images count toward the published site size limit; GitHub Pages has a 1 GB limit for a published site, so avoid treating the repository as storage for large media collections.

2. Use GitHub issue attachments

GitHub can upload an image when you drag it into an issue or comment editor and returns a hosted image URL. You can copy that URL into a Markdown post without adding the image file to your blog repository.

1. Open a new issue or comment editor in a repository where you can create content.
2. Drag an image into the editor and wait for GitHub to finish uploading it.
3. Copy the generated Markdown or image URL into your blog post.
4. If you only needed the upload, leave without submitting the issue or comment.

This can be convenient for occasional images, but it relies on GitHub-hosted attachments rather than assets managed with your site. Use it only for images intended to be publicly accessible, and do not treat attachment URLs as a guaranteed image CDN or permanent archival service.

3. Create a dedicated media repository

If you publish many images or want to keep your main site repository lightweight, create a separate public repository for media—for example, blog-images. Organize and upload optimized files there, then reference them from your posts using their raw content URL:

https://raw.githubusercontent.com/your-username/blog-images/main/images/my-post-image.webp

Replace the username, repository, branch, and file path with your own. A separate repository keeps blog source and media apart, but the media repository must be public for visitors to load its images. Raw GitHub URLs are convenient for simple sites, not a substitute for a dedicated image CDN when you need high traffic, image transformations, or delivery guarantees.

Image tips that apply to every option

• Compress before uploading: Large phone photos can be several megabytes each. Resize them to the dimensions you need and use a suitable optimized format such as WebP.
• Check letter case: GitHub Pages paths are case-sensitive. A link to photo.jpg will not find a file named Photo.JPG.
• Avoid leading underscores in asset folder names: Jekyll may exclude folders beginning with an underscore from the generated site unless configured otherwise. Use a name such as images/ instead of _images/.
• Use descriptive alt text: Write meaningful alt text for informative images, and use an empty alt value for purely decorative images.