We created Nixopus to simplify self-hosting. Think of it as Heroku or Netlify, but built for developers who want full control, especially when working with Docker apps. Naturally, we used Nixopus itself to host our own documentation in the early days. But as we rolled out alpha builds and moved fast, the setup started pushing back. To make sure our docs stayed accessible and reliable for users, we temporarily shifted to GitHub Pages. That’s when Jekyll, GitHub’s default static site generator, started messing with our VitePress setup. Here’s what happened.
Moving Docs to GitHub Pages: What We Did
We started by setting up a custom domain for our docs at docs.nixopus.com. After adding a CNAME file to the repository, we updated the DNS records to point to GitHub’s servers. Domain validation went through without any hiccups. Next, we had to choose how GitHub Pages would serve our documentation.
We picked the branch method for simplicity. We set it to deploy from the master branch and pointed it to the /docs directory, where our VitePress site lives. That got the docs live on the domain, but it also opened the door to a new set of issues.
The Migration Catastrophe: Looks Like Docs, Feels Like Chaos
When we first got the docs live, something felt off. They loaded, but with zero CSS. No layout, no colors, just raw text sitting on the screen. Technically the site was working, but let’s be honest, it was unusable.
We had a GitHub Action set up to build and deploy the docs on every push to master. At one point, we switched the deployment method from branch based to GitHub Actions, then back again, hoping it would help.
The Actions ran without errors. The pages deployed. But the styling came and went like a ghost. And that kind of inconsistency is the worst kind of bug to chase.
Why We Couldn't Pin Down the Root Cause
We were convinced the problem was with VitePress. This GitHub issue matched what we were seeing almost perfectly, so we tweaked our VitePress config, redeployed, and boom it worked.
For a moment, at least. The next time we pushed to master, the problem came back. No styles again. At this point, our GitHub Actions were running flawlessly. No errors, no skipped steps, nothing unusual.
We opened a Discord thread to track the issue in real time and started logging when the bug would appear. But without a clear pattern, it felt like chasing shadows.
The Burnout Moment
One day, while talking to a Nixopus contributor about the docs issue, something clicked. I opened up the GitHub Actions tab to double check the workflow we were using to build and deploy the documentation. That’s when I noticed something strange two GitHub Actions were running for the same trigger.
I paused. We only had one workflow file in the repo. So where was the second action coming from? I took a closer look at both. One was clearly ours. The other seemed to be generated by GitHub itself, tied to the "Pages" deployment configuration. Suddenly, it made sense. We had unknowingly set
We weren’t going crazy. We were just getting Jekylled.
This one was so ridiculous & funny at the same time, we couldn’t help but laugh once we figured it out. Remember how we chose to deploy from a GitHub branch? Turns out, GitHub was quietly running its own internal deployment step for Pages. At the same time, our custom GitHub Action was also building and deploying the site.
The catch was when GitHub’s default Pages deploy ran first, it served our VitePress site without any CSS. Completely styleless. Then, when our GitHub Action ran after it, it deployed the styled version. That’s why it sometimes looked fine and we were racing against GitHub’s own deploy job. and yep, GitHub’s deploy was using Jekyll under the hood, even though we had no .nojekyll file in the repo. Classic Pages behavior.
Conclusion
What looked like a flaky VitePress bug turned out to be a silent tug-of-war between GitHub Pages and our own deployment pipeline. GitHub was defaulting to Jekyll, quietly breaking our styles, and we didn’t even notice it at first because our own action would sometimes fix it afterward.
The fix? We disabled the default GitHub Pages deploy and let our GitHub Action handle everything. Clean, predictable, and no more surprise Jekyll attacks. Lesson learned ? when something works "sometimes," dig deeper. There's probably a rogue process you didn’t invite to the party.
If you're someone who wants to streamline ServerOps without the usual mess, Nixopus might be exactly what you're looking for. And if you enjoy chasing down weird bugs like this one, join us on Discord we’d love to have you around. Let’s hunt bugs, ship clean infra, and laugh through the chaos together.
Top comments (1)
Very intricate details on the specifics! Nice detailed elaboration on the issue ⭐