Quick Start Guide

This guide provides step-by-step instructions to initialize a new Jekyll site, run a local development server with live reload features, and build your site under various operating systems and container runtimes.

Scenario 1: Initializing a New Jekyll Site

Use these commands to generate a new Jekyll project directory structure on your host machine. The container will mount your current working directory to /srv/jekyll, run a permissions adjustment, and execute the standard jekyll new generator.

On Linux and macOS (including Git Bash)

export site_name="my-blog"
export MSYS_NO_PATHCONV=1

docker run --rm \
  --volume="$PWD:/srv/jekyll" \
  -it jekyll/jekyll \
  sh -c "chown -R jekyll /usr/gem/ && jekyll new $site_name" \
  && cd $site_name

On Windows (Command Prompt - cmd)

set site_name=my-blog

docker run --rm --volume="%CD%:/srv/jekyll" -it jekyll/jekyll sh -c "chown -R jekyll /usr/gem/ && jekyll new %site_name%" && cd %site_name%

On Windows (PowerShell)

$site_name="my-blog"

docker run --rm --volume="${PWD}:/srv/jekyll" -it jekyll/jekyll sh -c "chown -R jekyll /usr/gem/ && jekyll new $site_name"
cd $site_name

Technical Deep Dive: Why `chown -R jekyll /usr/gem/`?

Before running jekyll new, the command updates the owner of /usr/gem/ to the jekyll user inside the container. This ensures that the initialization process can install any required dependencies without running into write access blocks, keeping your host environment clean of root-owned files.

Scenario 2: Running the Development Server with Watchers

To view your site locally and make live edits, run Jekyll in server mode. This command mounts your folder, exposes the standard port 4000, and links the LiveReload port 35729:

docker run --rm \
  --name my-jekyll-server \
  --volume="$PWD:/srv/jekyll:Z" \
  --publish 4000:4000 \
  --publish 35729:35729 \
  -it jekyll/jekyll \
  jekyll serve

Parameter Breakdown

--volume="$PWD:/srv/jekyll:Z": Mounts your local project directory into the container's working directory. The :Z flag configures SELinux file labeling settings on hosts where SELinux is active (e.g., RedHat, Fedora, CentOS).
--publish 4000:4000: Maps port 4000 of the container to port 4000 on your local host, making the site available at http://localhost:4000/.
--publish 35729:35729: Maps the default LiveReload port. This lets Jekyll push automated browser refreshes when you modify markdown or stylesheet files.

Scenario 3: Initializing with Podman (Rootless Environment)

If you run containers in a secured, rootless Linux environment via Podman, standard user mapping changes. Use the JEKYLL_ROOTLESS configuration parameter to run the initialization safely:

podman run -ti --rm \
  -v .:/srv/jekyll:Z \
  -e JEKYLL_ROOTLESS=1 \
  docker.io/jekyll/jekyll jekyll new .

How Rootless Mode Works

When JEKYLL_ROOTLESS=1 is passed to the container, the /usr/jekyll/bin/entrypoint wrapper bypasses the standard privilege-dropping routines. This aligns the containerized execution process with the host user's account namespace, preventing permission mismatches on your local files.

Scenario 4: Compiling a Production Build

To generate your compiled site files (which are written to the _site/ folder) without launching a persistent server web server, execute a single build pass:

docker run --rm \
  --volume="$PWD:/srv/jekyll:Z" \
  -e JEKYLL_ENV=production \
  -it jekyll/jekyll \
  jekyll build

This command compiles your pages, minifies assets (if configured in your Jekyll plugins), and exits as soon as the build finishes, which is ideal for deployment preparation pipelines.