jekyll

name	jekyll
description	Start, stop, and manage the local Jekyll development server for PlanExe-web. Use this skill when doing web development on the site — editing CSS, layouts, index.md, examples, or any site content that needs a local preview.

Jekyll Development Server

Prerequisites

Ruby 3.3 is required. The PATH must include the Ruby 3.3 bin directory.

Starting the server

Run Jekyll in a background Bash process so it stays alive for the duration of the session:

PATH="/opt/homebrew/opt/ruby@3.3/bin:$PATH" LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 bundle exec jekyll serve --port 4000

Use run_in_background: true with the Bash tool. This keeps the server running while you continue working.

After starting, wait a few seconds then verify it's up:

curl -s -o /dev/null -w "%{http_code}" http://localhost:4000/

The user browses to http://localhost:4000/ to preview.

Hot reload

Jekyll has auto-regeneration enabled by default. When you edit files (index.md, CSS, _data/examples.yml, layouts, etc.), Jekyll detects the change and rebuilds _site/ automatically. The user just refreshes their browser — do NOT restart the server after editing files.

Stopping the server

Only stop the server when the user explicitly asks, or when the session is ending. Kill it with:

pkill -f "jekyll serve"

Important rules

1. Never use upsert_plan/start_jekyll.py or upsert_plan/stop_jekyll.py for web development. Those scripts are for plan management workflows only.
2. Never restart the server after file edits. Auto-regeneration handles it. Only restart if the server has actually crashed.
3. Never kill Jekyll just because you're done previewing. The user manages their own browser tabs and will stop the server themselves with Ctrl-C when done.
4. If port 4000 is occupied, use --port 4001.