Jekyll & zer0-mistakes Theme Installation
By bamr87
Install Jekyll with the zer0-mistakes theme — via Gemfile or Docker — then verify your site builds and serves correctly.
Estimated reading time: 3 minutes
Table of Contents
This guide covers Phase 4 of the Quick Start — installing Jekyll and the zer0-mistakes theme that powers it-journey.dev. By the end, you’ll have a working Jekyll site running locally.
Prerequisites
Before starting, confirm these tools are installed:
ruby --version # 3.2+
bundler --version # 2.x+
git --version # 2.x+
If anything is missing, complete the Machine Setup first.
Jekyll also requires:
- RubyGems (ships with Ruby)
- GCC and Make (included with Xcode CLI on macOS,
build-essentialon Linux)
If you want to use GitHub Pages, here are the supported dependency versions.
Install Dependencies via Gemfile
The IT-Journey repository already includes a Gemfile. If you’re starting fresh or want to understand the setup:
cd ~/github/it-journey # or your project directory
Using the Existing Gemfile
# Install all dependencies specified in Gemfile
bundle install
Creating a Gemfile from Scratch
If you don’t have a Gemfile yet (e.g., starting a new zer0-mistakes site):
cat > Gemfile << 'EOF'
source "https://rubygems.org"
gem 'github-pages'
gem 'jekyll-theme-zer0'
gem 'webrick'
EOF
bundle install
Key gems:
| Gem | Purpose |
|---|---|
github-pages |
GitHub Pages-compatible Jekyll build with all supported plugins |
jekyll-theme-zer0 |
The zer0-mistakes theme gem for local development |
webrick |
Required web server for Ruby 3.0+ |
Theme Configuration
The zer0-mistakes theme can be loaded in two ways. Which one you use depends on whether you’re developing locally or deploying to GitHub Pages.
Option 1: Remote Theme (GitHub Pages Deployment)
In your _config.yml:
remote_theme: "bamr87/zer0-mistakes"
This is what GitHub Pages uses when building your site. No gem installation needed on the server.
Option 2: Local Gem (Local/Docker Development)
In your _config.yml (or _config_dev.yml):
theme: "jekyll-theme-zer0"
This uses the locally installed gem, which is faster for development and works offline.
Using Both Configs Together
The recommended workflow uses the remote theme for production and the local gem for development:
# Development: loads _config_dev.yml overrides (including local theme)
bundle exec jekyll serve --config _config.yml,_config_dev.yml
# Production: uses remote_theme from _config.yml only
JEKYLL_ENV=production bundle exec jekyll build
Verify Your Installation
Native Ruby
bundle exec jekyll serve
# Open http://localhost:4000 (or 4002 if configured) in your browser
You should see the zer0-mistakes theme with the site title and navigation.
Docker (Alternative)
If you prefer Docker (no Ruby installation needed on your host machine):
docker-compose up -d
# Open http://localhost:4002 in your browser
See the Local Development guide for the full Docker workflow.
Common Issues
webrick LoadError (Ruby 3.0+)
If you see cannot load such file -- webrick:
bundle add webrick
Bundler Version Mismatch
If bundle install fails with a version error:
gem install bundler
bundle install
Theme Not Loading
If pages render without styling:
- Confirm
remote_themeorthemeis set in_config.yml - For local development, ensure
jekyll-theme-zer0is in yourGemfile - Run
bundle installagain after Gemfile changes - Restart the Jekyll server (
Ctrl+C, thenbundle exec jekyll serve)
Live Reload
Pass --livereload to automatically refresh the browser when files change:
bundle exec jekyll serve --livereload
What’s Next
| Next Step | Guide |
|---|---|
Configure _config.yml — site identity, skins, collections |
Site Configuration |
| Set up VS Code with extensions and Front Matter CMS | VS Code Setup |
| Run the site with Docker or native Ruby | Local Development |
IT-Journey Quests: Jekyll Fundamentals · YAML Configuration
IT-Journey Docs: Installation Update
External Docs: Jekyll Installation · Jekyll Themes · zer0-mistakes Theme