Windows vs. Linux: Why Jekyll Pages Disappear After Deploying to GitHub Pages
As you already know, my WebAnd3D website is hosted on GitHub Pages. I, on the other hand, work on Windows.
Locally, the website works just fine. Some of my pages are generated automatically using a Jekyll plugin. The website takes images from specific folders, reads their filenames, retrieves data from files, and uses a template to generate complete 3D model pages.
For example, pages for downloadable STL models. Images, descriptions, titles, printing settings — everything comes together without me having to create a separate HTML file for every single model.
And you know that feeling when everything works perfectly on your local machine? All the pages are there, CSS loads, buttons respond when clicked. You’re pretty pleased with yourself, so you run git push and go check the live website.
And then… nothing.
404 — Page Not Found.
And you’re sitting there thinking: “Oh, come on! Where are my pages? They were working perfectly on my local machine!”
GitHub Actions isn’t showing Pending or In progress anymore, either. Everything is green. The build succeeded, and deployment is complete. Anyone who works with GitHub knows the feeling: a green checkmark is nice, but sometimes it only means the computer successfully did something other than what you expected.
Windows and Linux: Same Code, Different Rules
My first thought was that something had gone wrong during the GitHub Pages deployment. But what? The website worked locally!
Here’s something worth remembering: local development on Windows and building a website on Linux with GitHub Actions are not the same environment.
I build the website locally on Windows, while GitHub Actions runs the build in a Linux environment. There are differences between the two that are easy to overlook when you only test the local version.
Take filename capitalization, for example.
On Windows, Main.css and main.css usually refer to the same file. Linux, however, treats uppercase and lowercase letters as different characters. So if your HTML references Main.css, but the actual file is named main.css, everything might look fine locally — until the website goes live and the CSS suddenly stops loading.
And that’s one of the simpler examples. When automatic page generation is involved, there are other places where things can go wrong.
When Jekyll Generates Pages Automatically
My WebAnd3D website uses Jekyll, a static site generator. It turns templates, data, and other files into ready-to-publish HTML pages.
For my 3D printing model pages, I use the jekyll-datapage-generator plugin. It helps generate pages from data and templates instead of making me write every page by hand.
Imagine this: I add a model, prepare its images and data, and the website is supposed to generate a page like this:
/models/automotive-parts/chery-tiggo/
That’s exactly the kind of page I want to check after deployment. It’s not enough for the website to build successfully. I also need to make sure the expected pages actually exist in the build output.
And here’s an important detail: getting the website to work with jekyll serve locally doesn’t automatically mean the production build will behave the same way.
So I started checking not only whether a page opened in my browser, but also whether Jekyll actually generated its HTML file during the build.
GitHub Actions: A Green Checkmark Isn’t the Whole Story
I configured GitHub Actions to automate the build and deployment process. It runs Jekyll on Linux, builds the website, and uploads the generated files to GitHub Pages.
I added a separate check for my Chery Tiggo page:
if [ ! -f "_site/models/automotive-parts/chery-tiggo/index.html" ]; then
echo "ERROR: Chery Tiggo page was not generated"
exit 1
fi
echo "Chery Tiggo page generated successfully"
Now the workflow checks whether the page file exists after the build. If it doesn’t, the process fails instead of simply giving me a green checkmark.
This doesn’t guarantee that the page will open perfectly in a browser, but it helps catch a specific problem during the build stage.
While investigating, I also noticed two separate workflows in GitHub Actions: my Build and deploy WebAnd3D workflow and pages build and deployment.
Their presence alone doesn’t prove that they were interfering with each other, but it gave me another thing to investigate: the GitHub Pages publishing settings. I needed to make sure the website was being deployed using the method I had actually configured.
Because when there are several possible places for something to go wrong, it’s better to check the evidence than to blame the first line of code that looks suspicious.
What About Gemfile.lock and Dependencies?
There’s another thing to consider when developing Jekyll websites: Ruby dependencies and Bundler.
The Gemfile lists the libraries and plugins a project needs, while Gemfile.lock records the specific dependency versions. This helps make builds more reproducible, but when you develop on Windows and build on Linux, you need to account for both platforms.
In my case, I added Linux as a Bundler platform:
bundle lock --add-platform x86_64-linux
This updates Gemfile.lock so Bundler accounts for Linux dependencies. It won’t automatically fix every possible build error, but it can help avoid issues involving platform-specific dependencies.
There’s another important detail: not every Jekyll plugin is available in GitHub Pages’ standard build process. If your website uses third-party plugins, you may need a custom build through GitHub Actions.
That’s why it’s important to check not only the code, but also how the website is built and deployed.
What I’ll Check Next Time
When the local website works but a page returns a 404 error after deployment to GitHub Pages, here’s the order I’d follow:
- Jekyll build output. Was the expected HTML file generated inside
_site? - GitHub Actions. Did the build actually succeed, and does the uploaded artifact contain the required pages?
- GitHub Pages settings. Which workflow or publishing process is responsible for deployment?
- File paths and capitalization. Do filenames, CSS references, image paths, and links match exactly?
- Plugins and dependencies. Are they available in the environment where the website is built?
- The published website itself. Is the page URL correct, and has the latest deployment finished?
This doesn’t mean every 404 error is caused by Windows, Linux, or GitHub Actions. It’s simply a way to investigate systematically and find the point where the result starts to differ from what you expected.
The Takeaway: Working Locally Isn’t the Finish Line
I still love the moment when my code finally works. Especially when I don’t have to rewrite half the website or start having a heated conversation with my monitor.
But this experience reminded me that local development, Jekyll builds, and GitHub Pages deployment are separate stages. I need to check not only whether the website works on my computer, but also what actually makes it into the published version.
Now I have a check that looks for a specific model page. No artificial intelligence, no magic, no tiny programmer living inside my computer. Just a file check.
But sometimes, little things like that save you from another evening spent asking: “Where on earth did my pages go?”
Meanwhile, WebAnd3D keeps growing: more STL models, more pages, downloadable files, and more reasons to make sure everything stays where it belongs after git push.
Because WebAnd3D isn’t just about 3D modeling, 3D printing, and web development. It’s also a continuing education in the art of negotiating with computers.
Sometimes successfully. Sometimes with a git push, a 404 error, and a cup of coffee.