I always thought GitHub Pages was simple. You build your project, push the static export, and the site updates. That is what the docs say and that is how everyone on Reddit and StackOverflow talks about it. So when my site refused to update and kept serving old HTML from some random folder I forgot existed, I figured I just messed up a command.
Turns out this was one of those problems that teaches you way more about the platform than you ever wanted to know.
This whole thing started because my repo had multiple deployments in it over time. I had old folders, old builds, old static exports, and GitHub Pages settings that I never checked after the very first time I set the repo up. It was the perfect storm of confusion.
Where things started breaking
My project had gone through a few iterations. I had:
- an older site that used a
/docsfolder - a later version that output to
/dist - some leftover static files inside the root
- GitHub Actions workflows I copied from older repos
- Pages pointed at a folder I forgot even existed
At first none of this mattered because I was not rebuilding the repo often. But when I pushed a brand new version of the site, the Pages server kept pulling from that ancient /docs folder instead of the new static export.
I did not even remember creating /docs. It was from a build system I used months before.
The symptoms
I would deploy and the site would show:
- old CSS
- old JavaScript
- old HTML
- broken layout
- missing assets
I checked the code and everything in my repo was up to date. The build artifact looked correct. The static export was correct. The workflow logs were clean.
Meanwhile the live site looked like it was living three timelines behind my repo.
The moment I realized the issue
At one point I opened GitHub Pages settings and it hit me immediately.
The Pages source was set to:
/docs
Not:
/dist
Not:
/build
Not anything modern.
Just the old folder I did not delete because I assumed it did not matter.
That small detail caused the entire deployment to serve stale content. Pages was not reading my new build at all. It was faithfully serving whatever was in /docs because I had told it to do that a long time ago and then forgot.
Cleaning it up
Once I figured that out, the fix was straightforward:
- Delete the old
/docsfolder completely. - Update the Pages deployment settings to point to the correct build output.
- Clean the repo of leftover static files.
- Commit a fresh static export from Bun or Next.js.
- Trigger a clean GitHub Pages build.
The second I deleted /docs and pointed GitHub Pages to the actual build directory, everything snapped back to normal. The new layout loaded. The CSS updated. The site finally reflected the code I was actually writing.
What the problem really taught me
This was not a bug. It was user error plus how GitHub Pages is designed.
Pages keeps serving whatever folder you told it to serve until you explicitly change it. It does not auto detect changes. It does not switch to a new build folder because it looks “more correct.” It sticks to the literal path you set.
If you point Pages at /docs, it will die on that hill until you fix it.
That is both a feature and a trap.
How to avoid this mess
If your GitHub Pages site serves old content even though your build is correct, check this list:
- Look at the Pages source folder.
- Make sure your static export path matches that folder exactly.
- Delete any old build folders you are not using.
- Clean out orphaned HTML files in the root.
- Make sure your workflow artifacts match your Pages directory.
It takes five minutes to check, but if you forget how the repo was originally configured, you can lose hours trying to debug something that is not actually broken.
Final thoughts
This taught me to treat deployment folders like infrastructure. They matter. They carry history. And if you do not clean them up, they can bite you months later when you least expect it.
Now I check my Pages settings before every new repo upgrade. Not because I am paranoid, but because I now understand exactly how easy it is to break a Pages deployment by accident.
And how annoying it is when GitHub is faithfully serving the wrong folder while you blame everything else.
Top comments (0)