Local Jekyll Development Setup Guide

Claude Opus 4.6, verified by Yanfei Tang 2026-03-25

This guide documents how to set up a local Jekyll development environment for this GitHub Pages site on a fresh Ubuntu machine.

Prerequisites

  • Ubuntu 22.04 (or similar Debian-based Linux)
  • sudo access
  • Git (to clone the repository)
  • VS Code with Remote - SSH extension (if working on a remote machine)

Step 1: Clone the Repository

git clone https://github.com/yanfeit/yanfeit.github.io.git
cd yanfeit.github.io

Step 2: Install Ruby and Build Dependencies

sudo apt-get update
sudo apt-get install -y ruby-full build-essential zlib1g-dev ruby-bundler

Verify the installation:

ruby --version    # Should show Ruby 3.x
gem --version
bundler --version

Step 3: Install Jekyll and Gems

Configure Bundler to install gems locally (avoids needing sudo):

bundle config set --local path 'vendor/bundle'

Install all dependencies:

bundle install

This reads the Gemfile and installs the github-pages gem (which includes Jekyll and all plugins used by GitHub Pages) plus webrick (required for Ruby 3+). The gems are stored in vendor/bundle/ and won’t pollute your system Ruby.

Step 4: Serve the Site Locally

bundle exec jekyll serve --livereload

Then open http://localhost:4000 in your browser.

  • --livereload makes the browser auto-refresh whenever you save a file.
  • Press Ctrl+C to stop the server.

Other useful flags

Flag Purpose
--drafts Include posts in _drafts/
--incremental Faster rebuilds (only changed files)
--host 0.0.0.0 Allow access from other devices on the network
--port 5000 Use a different port

How It Works on a Remote Machine (VS Code Remote - SSH)

If you connect to a remote workstation via VS Code Remote - SSH, you can still open localhost:4000 in your local browser. This works because:

  1. Jekyll starts on the remote machine, listening on port 4000.
  2. VS Code detects the new listening port automatically.
  3. VS Code creates an SSH port-forwarding tunnel: local:4000 → remote:4000.
  4. Your local browser hits localhost:4000, which is transparently forwarded through the SSH tunnel to the remote Jekyll server.

You can view and manage forwarded ports in VS Code’s Ports panel (Ctrl+Shift+P → “Ports: Focus on Ports View”).

File Summary

File Purpose
Gemfile Declares Ruby gem dependencies (github-pages, webrick)
Gemfile.lock Locks exact gem versions (auto-generated by bundle install)
_config.yml Jekyll site configuration
.bundle/config Bundler local config (gem install path)
vendor/bundle/ Installed gems (git-ignored)

Quick Reference

# Start the server
cd ~/projects/yanfeit.github.io
bundle exec jekyll serve --livereload

# Rebuild without serving
bundle exec jekyll build

# Update gems (after changing Gemfile)
bundle update