I’m having trouble with image URLs when I deploy my Hugo website to GitHub Pages. The images show up fine when I run the site locally using hugo serve, but they don’t load properly on the deployed version.
My project structure looks like this:
├── content
│ ├── _index.md
│ ├── gallery
│ │ ├── index.md
│ │ ├── photo1
│ │ │ ├── photo1.jpg
│ │ │ └── index.md
In my gallery/index.md file, I’m referencing the image like this:
---
layout: standalone
title: Photo Gallery
menu:
main:
weight: 2
---
<div class="photo-grid">
<a href="/gallery/photo1/" class="photo-link"><img src="/gallery/photo1/photo1.jpg" alt="Photo 1"></a>
</div>
The problem is that on GitHub Pages, it’s trying to load the image from /gallery/photo1/photo1.jpg instead of my-repo-name/gallery/photo1/photo1.jpg. This causes the images to return 404 errors.
I’ve tried adding cache settings to my hugo.toml file but it didn’t help. Has anyone else run into this issue? What’s the best way to fix image paths for GitHub Pages deployment?
To resolve the image path issue on your GitHub Pages deployment, you should adjust the baseURL in your hugo.toml configuration file. Set it to https://yourusername.github.io/your-repo-name/, ensuring to include the trailing slash and your correct GitHub username and repository name. This adjustment is crucial as it influences how Hugo interprets and generates paths for your resources. After making this update, rebuild and redeploy your site. Alternatively, consider using relative paths in your markdown by omitting the leading slash from image sources, changing /gallery/photo1/photo1.jpg to gallery/photo1/photo1.jpg. However, adjusting the baseURL is typically the best and most efficient approach.
yeah this happend to me too! try using hugo’s built-in relURL function instead of hardcoding paths. change your img src to something like {{ "gallery/photo1/photo1.jpg" | relURL }} - this automatically handles the base path stuff for github pages without messing with your local dev setup.
I had a similar headache with my Hugo deployment last month. The issue stems from GitHub Pages serving your site from a subdirectory when using project pages rather than user pages. What worked for me was setting canonifyURLs = true in my hugo.toml config file alongside the correct baseURL. This forces Hugo to convert all relative URLs to absolute ones based on your baseURL setting. Also make sure you’re using hugo --gc --minify when building for production instead of just hugo serve. The build process handles path resolution differently than the development server. After enabling canonifyURLs and rebuilding, my images loaded correctly on GitHub Pages without having to modify every markdown file individually.
Another approach that worked for me is using Hugo’s page bundles more effectively. Since you already have your images organized as page bundles, you can reference them using the .Resources method instead of hardcoded paths. In your gallery template or shortcode, try something like {{ $image := .Resources.GetMatch “photo1.jpg” }} and then use {{ $image.RelPermalink }} for the src attribute. This method automatically resolves paths correctly regardless of whether you’re running locally or on GitHub Pages because Hugo handles the URL generation based on your site configuration. It’s particularly useful when you have multiple images per page bundle and want to avoid path issues entirely. The Resources method also gives you access to image processing features if you need them later.