Running Jekyll locally on Windows is one of those things that’s straightforward once you’ve done it, and mildly annoying the first time. Here’s the setup that works for me.

What You Need

  • RubyInstaller for Windows — grab the Ruby+Devkit version (3.2.x x64). The Devkit matters; without it native gem extensions won’t compile.
  • Bundler: gem install bundler after Ruby is installed
  • VS Code with the Jekyll Snippets extension if you want syntax highlighting for Liquid templates

The wdm Gem

On Windows you want the wdm gem — it lets Jekyll watch for file changes natively instead of polling. Without it --livereload is sluggish. The Gemfile already has it:

platforms :mingw, :x64_mingw, :mswin do
  gem "wdm", "~> 0.1.1"
end

It only installs on Windows platforms, so it doesn’t affect GitHub Actions or anyone running on Mac/Linux.

Running the Dev Server

bundle exec jekyll serve --livereload

That’s it. The site builds to _site/ and reloads in the browser whenever you save a file. Default port is 4000.

A few flags worth knowing:

# Preview draft posts from _drafts/
bundle exec jekyll serve --livereload --drafts

# If something's broken and you want a clean build
bundle exec jekyll clean && bundle exec jekyll serve --livereload

The Gemfile.lock Platform Issue

If you develop on Windows and deploy via GitHub Actions (Linux), you’ll eventually hit this: the lockfile only has Windows platforms listed, and the Actions runner can’t resolve gems.

Fix it once and forget it:

bundle lock --add-platform x86_64-linux

Commit the updated Gemfile.lock. Done. GitHub Actions will be happy.

VS Code Setup

Two things worth configuring:

  1. Set the terminal to PowerShell (terminal.integrated.defaultProfile.windows) so bundle exec works without switching shells
  2. Add _site/ and .jekyll-cache/ to .gitignore if they aren’t already — no reason to commit build output