Troubleshooting Hugo Site Deployment on Vercel
Issue 1 - After Deployment, the Homepage Shows an RSS XML Page
After deploying following Vercel’s official guide, the homepage displayed an RSS XML page. The cause: Vercel’s built-in Hugo version is too old.
✅ Solution
Add a vercel.json file in your project’s root directory to specify the Hugo version, Go version, and build command (buildCommand).
When Hugo is set as the Framework Preset in Vercel, these configurations will be automatically detected.
{
"build": {
"env": {
"HUGO_VERSION": "0.147.8",
"GO_VERSION": "1.24.4"
}
},
"buildCommand": "hugo --gc --minify && npx pagefind --site public",
"outputDirectory": "public"
}
You can check your current Hugo and Go versions by running
` hugo env`
Issue 2 - The Website Loads Without CSS After Deployment
After deployment, clicking the automatically generated Vercel URL led to a website with broken styles.
Using the browser’s Developer Tools, it was discovered that the requested CSS paths were tied to the Domain set in hugo.toml.
✅ Solution
Simply configure your custom Domain correctly in Vercel.
Once the site is accessed through that domain, the CSS will load normally.
Issue 3 - ReferenceError: PagefindUI is not defined
⚠️ Symptom
After adding a search function to the blog using PagefindUI, search worked fine locally (localhost) but not on the deployed site.
🔍 Cause
The public folder was missing from the repository because the hugo command hadn’t been executed yet.
Without building the static site, Pagefind cannot run — it is a post-processing tool that depends on Hugo’s generated output.
✅ Solution
1. Build the static site:
`hugo --gc --minify`
2. Generate the Pagefind index:
`npx pagefind --site public`
3. Deploy the entire public folder to Vercel.
✅ After completing these steps, both the search functionality and page styles should work properly on your deployed Hugo site.