Troubleshooting Local Build Issues

Problem: Ruby commands not found

If you get errors like “ruby: command not found” or “bundle: command not found”, Ruby isn’t in your PATH.

Solution 1: Restart Terminal (Easiest)

Close your current PowerShell/terminal completely
Open a new PowerShell window
Try again: ruby --version

Solution 2: Use Ruby Installer’s Command Prompt

Open Start Menu
Search for “Start Command Prompt with Ruby” or “Ruby Command Prompt”
Navigate to your project: cd D:\CBAResearch\zikangleng.github.io
Run: bundle install

Solution 3: Add Ruby to PATH Manually

Find where Ruby is installed (usually C:\Ruby31-x64 or C:\Ruby32-x64)
Open System Properties → Environment Variables
Edit Path variable
Add: C:\Ruby31-x64\bin (or your Ruby path)
Restart terminal

Solution 4: Reinstall Ruby with PATH option

Download Ruby+Devkit from https://rubyinstaller.org/
During installation, check “Add Ruby executables to your PATH”
Restart your computer (or at least all terminal windows)

Step-by-Step Build Process

Once Ruby is working:

# 1. Navigate to project
cd D:\CBAResearch\zikangleng.github.io

# 2. Install Bundler (if not installed)
gem install bundler

# 3. Install dependencies
bundle install

# If bundle install fails, try:
bundle clean
bundle install

# 4. Build the site
bundle exec jekyll build

# 5. Serve locally (optional)
bundle exec jekyll serve

Common Errors and Fixes

Error: “Could not locate Gemfile”

Fix: Make sure you’re in the project root directory (zikangleng.github.io)

Error: “SSL certificate verify failed”

Fix: Run: gem sources -r https://rubygems.org/ then gem sources -a https://rubygems.org/

Error: “Failed to build gem native extension”

Fix: Make sure you installed Ruby+Devkit (not just Ruby)

Error: “jekyll: command not found”

Fix: Always use bundle exec jekyll instead of just jekyll

Error: “Permission denied” or “Access denied”

Fix: Run PowerShell as Administrator, or install gems to user directory:
```
bundle config set --local path 'vendor/bundle'
bundle install
```

Verify Installation

Run these commands to verify everything is set up:

ruby --version    # Should show Ruby version (e.g., 3.1.0)
gem --version     # Should show gem version
bundle --version  # Should show bundler version

Alternative: Use GitHub Actions to Test

If local build is too difficult, you can:

Push your changes to GitHub
Check the Actions tab for build status
View any errors in the build logs

This is slower but doesn’t require local setup.

Zikang Leng