Debugging GitHub Pages Deployment: Two Distinct Infrastructure Challenges
By Thanh Phong Le
July 28, 2025
When deploying a custom Node.js static site generator to GitHub Pages, I encountered two separate infrastructure issues that perfectly illustrate how modern web deployment involves multiple independent systems. Each required different diagnostic approaches and solutions, demonstrating the kind of systematic troubleshooting that Node.js architects employ in production environments.
Issue #1: Jekyll Build Failure
The Problem
GitHub Pages failed to build with the error:
Conversion error: Jekyll::Converters::Scss encountered an error while converting 'assets/css/style.scss':
No such file or directory @ dir_chdir0 - /github/workspace/docs
Root Cause
GitHub Pages was attempting to process my pre-built static files through Jekyll, looking for Sass files that didn't exist because my custom Node.js build system had already compiled everything.
Diagnostic Commands
# Verify repository structure
git branch --show-current && ls -la
# Check for pre-built static files in /docs
tree -I 'node_modules' docs
The Solution
# Tell GitHub Pages to skip Jekyll processing
touch docs/.nojekyll
git add docs/.nojekyll
git commit -m "Fix GitHub Pages Jekyll build error by adding .nojekyll file"
git push origin main
The .nojekyll file instructs GitHub Pages to serve files as-is rather than attempting to rebuild them with Jekyll.
Issue #2: DNS Configuration Error
The Problem
GitHub Pages displayed "www.thanhphongle.net is improperly configured" even after successful deployment.
Root Cause
The www subdomain lacked a CNAME record pointing to GitHub Pages, causing domain verification to fail.
Diagnostic Commands
# Check A records for root domain
dig thanhphongle.net A +short
# Check CNAME for www subdomain (revealed the missing record)
dig www.thanhphongle.net CNAME +short
# Verify root domain is serving correctly
curl -I https://thanhphongle.net
The Solution
Added a CNAME record in Cloudflare:
- Type: CNAME
- Name: www
- Target: ltphongssvn.github.io
- Proxy status: Proxied
Key Architectural Insights
These two issues highlight important principles for Node.js architects working with modern deployment pipelines:
Separation of Concerns: The build system (GitHub Pages with Jekyll) and the DNS system (Cloudflare) are completely independent. A failure in one doesn't necessarily indicate a problem in the other—systematic diagnosis is essential.
Platform Defaults Matter: GitHub Pages assumes Jekyll by default. When deploying custom build systems, we must explicitly override these assumptions rather than fighting against them.
Layered Diagnostics: Each issue required different diagnostic tools:
- Build issues: Examined logs and repository structure
- DNS issues: Used
digandcurlto verify network-level configuration
Minimal Intervention: Both solutions were remarkably simple—one file creation and one DNS record—demonstrating that understanding the problem deeply often leads to elegant solutions.
This experience reinforces why Node.js architects must be comfortable debugging across the entire stack, from build systems to DNS infrastructure. The ability to isolate issues, use appropriate diagnostic tools, and implement targeted solutions is what enables us to maintain reliable production systems.
If you enjoyed this article, you can also find it published on LinkedIn and Medium.