Building My github Blog with Chirpy: A Rollercoaster of Errors & FixesWhen I decided to set up my personal blog using the Chirpy jekyll theme, I expected a smooth, well-documented process. Instead, I found myself wrestling with dependency conflicts, cryptic errors, and deployment quirks—especially since I was working on kali-linux, which isn’t the most common choice for jekyll development.

This post isn’t just another “how to set up a blog in 5 minutes” tutorial. Instead, it’s a real-world troubleshooting log—documenting the issues I faced and how I fixed them. If you’re running into similar problems, hopefully, this saves you some headaches.

🛠 My Setup & Initial ChecksBefore diving into the errors, here’s the environment I was working with:

  • OS: kali-linux

  • Ruby: 3.3.8

  • Bundler: 2.6.9

  • jekyll: 4.4.1

  • Node.js: 20.19.0

  • npm: 9.2.0

  • Gulp CLI: 3.0.0

  • Package Managers: APT, Bundler, nvm

Everything looked good at first glance—until I started running commands.

🔥 Problem #1: Ruby Gem Conflicts (ffi & sassc Errors)### The Error:Running jekyll -v spat out a wall of warnings:

1
2
3
Ignoring ffi-1.15.5 because its extensions are not built. Try: gem pristine ffi --version 1.15.5
Ignoring sassc-2.4.0 because its extensions are not built. Try: gem pristine sassc --version 2.4.0

(Repeated multiple times—annoying, right?)

The Cause:These gems (ffi and sassc) require native extensions that weren’t compiled properly. kali-linux, being a security-focused distro, doesn’t always come with all the development tools needed for Ruby gem compilation.

The Fix:

  • Install missing build tools:
1
2
sudo apt install build-essential libffi-dev ruby-dev

  • Reinstall the problematic gems with system libraries:
1
2
3
4
5
6
gem install ffi -v 1.15.5 -- --use-system-libraries
gem pristine ffi --version 1.15.5

gem install sassc -v 2.4.0 -- --use-system-libraries
gem pristine sassc --version 2.4.0

After this, jekyll -v should run without those pesky warnings.

⚙️ Problem #2: Gulp Issues (Local Version Unknown)### The Error:Running gulp -v gave:

1
2
3
CLI version: 3.0.0
Local version: Unknown

The Cause:The Chirpy theme relies on Gulp 4 for asset processing (CSS, JS optimization). The error means Gulp is installed globally, but the project doesn’t recognize a local version.

The Fix:

  • Install Gulp locally:
1
2
npm install --save-dev gulp@4

  • Verify installation:
1
2
npx gulp -v

(Should now show both CLI and local versions.)

  • Run Gulp tasks:
1
2
npx gulp

(This builds assets before jekyll processes the site.)

🕸 Problem #3: github Pages Deployment Failures (Silent Build Issues)### The Problem:I pushed my repo to github, but my site wouldn’t update—no obvious errors, just a broken or outdated build.

The Cause:github Pages doesn’t support all jekyll plugins or custom build steps (like Gulp tasks). Since Chirpy relies on preprocessing, you must build locally first before deploying.

The Fix:

  • Build the site in production mode:
1
2
JEKYLL_ENV=production bundle exec jekyll build

  • Deploy only the _site folder to gh-pages:
1
2
3
4
5
6
7
8
cd _site
git init
git remote add origin https://github.com/yourusername/yourrepo.git
git checkout -b gh-pages
git add .
git commit -m "Deploy site"
git push -f origin gh-pages

  • In github repo settings:

Go to Settings > Pages

  • Set Source to Deploy from gh-pages branch

Now, github serves the pre-built site instead of trying (and failing) to build it itself.

1
2
linking to internal hash # that does not exist

The Fix:

  • Replace # with a valid anchor:
1
2
a href="#top">Back to Topa>

  • Add an anchor target somewhere on the page:
1
2
a id="top">a>

This keeps the same functionality while making html-proofer happy.

💡 Final Thoughts & Lessons LearnedSetting up Chirpy on kali-linux was way harder than I expected. The main issues stemmed from:

  • Ruby gem compilation problems (fixed with -use-system-libraries)

  • Gulp version mismatches (solved by local install)

  • github Pages’ limitations (workaround: pre-build & push _site)

  • Strict HTML validation (fixed with proper anchor tags)

TL;DR – Key Takeaways✔ Always check for native extension errors in Ruby gems.

✔ Install Gulp both globally and locally (v4 for Chirpy).

✔ Don’t rely on github Pages to build—do it yourself.

✔ Validate HTML early to catch broken links.

✔ Avoid href=”#”—use real anchors instead.

If you’re on kali-linux (or any non-standard dev environment) and trying to use jekyll + Chirpy, be prepared for some troubleshooting. But once it’s working, Chirpy is one of the cleanest, most customizable static site themes out there.