🎯 Goal

Polish my GitHub Pages website, troubleshoot Jekyll environment issues, and consolidate past days’ notes for publication.

âś… What I Did

Website & Blogging

  • Attempted to add themes in Jekyll
  • Encountered website breakage due to version incompatibilities
  • Formatted notes from previous days to be ready for publication

Troubleshooting Environment Issues

  • Identified multiple conflicting Jekyll, Ruby, and package manager versions
  • Observed VS Code losing GitHub integration (no commit/pull/push buttons)
  • Discovered multiple PATH conflicts from remnants of RVM, chruby, ruby-build, .rubies, and rbenv
  • Tried rolling back to previous versions, with partial success but new incompatibilities emerged

Cleaning & Reinstalling

  • Backed up .zshrc
  • Used a cleanup script to remove all Ruby version managers and duplicate PATH entries
  • Reinstalled Jekyll and Ruby, ensuring correct versions and consistent PATH setup
  • Updated .zshrc to the following working configuration:
# === Homebrew first ===
export PATH="/opt/homebrew/bin:/opt/homebrew/sbin:$PATH"

# === rbenv setup ===
export PATH="$HOME/.rbenv/bin:$HOME/.rbenv/shims:$PATH"

# Initialize rbenv
if command -v rbenv >/dev/null 2>&1; then
    eval "$(rbenv init - zsh)"
fi

# Deduplicate PATH
typeset -U PATH```
  • Verified Jekyll, VS Code, and GitHub integration now working smoothly

Learning

âś… What Worked

  • Cleanup script successfully removed all conflicting Ruby managers
  • Correctly configured .zshrc eliminated PATH duplication issues
  • VS Code GitHub integration fully restored
  • Jekyll site builds and runs locally without errors

❌ What Didn’t

  • Initial attempt to add themes broke the website
  • Version mismatch issues consumed hours of troubleshooting
  • ChatGPT guidance was sometimes misleading on PATH and version issues
  • Complexity of Ruby/Jekyll/Homebrew ecosystem exposed gaps in prior understanding

🧠 Key Takeaways

  • Version management matters: multiple version managers can conflict disastrously
  • PATH pollution is a real problem—cleaning .zshrc and deduplicating PATH is crucial
  • Backup configuration files before experimentation
  • Debugging environment issues can be more time-consuming than actual development
  • Persistent troubleshooting and methodical approach eventually resolve complex conflicts

âť“ Questions

  • How can I prevent future version conflicts when experimenting with Jekyll or Ruby?
  • Are there simpler workflows for managing Ruby and Jekyll versions on macOS?
  • How much of the environment complexity is unavoidable vs. preventable?

đź“š Resources