Jekyll Deployment & Usage Guide

Prerequisites

Ruby: Version 2.5 or higher (3.0+ recommended)
RubyGems: Latest version recommended
Bundler: gem install bundler
Build tools: GCC, Make, and development headers (for native extensions)
Git: Optional but recommended for version control and deployment

Platform-specific requirements:

macOS: Xcode Command Line Tools (xcode-select --install)
Ubuntu/Debian: sudo apt-get install build-essential zlib1g-dev
Windows: RubyInstaller with MSYS2 Devkit

Installation

Global Installation

gem install jekyll bundler

New Site Setup

# Create new site
jekyll new mysite
cd mysite

# Install dependencies
bundle install

Existing Project

cd existing-jekyll-site
bundle install

Verify Installation

jekyll --version
bundle exec jekyll doctor

Configuration

Create or edit _config.yml in your site root:

# Core configuration (from lib/jekyll/site.rb)
source: .                    # Source directory (frozen after init)
destination: ./_site         # Build output directory (frozen after init)
baseurl: ""                  # Subpath of your site, e.g. /blog
url: "https://example.com"   # Base hostname

# Build settings
safe: false                  # Disable custom plugins
lsi: false                   # Latent Semantic Indexing (slower)
highlighter: rouge           # Syntax highlighter
permalink: pretty            # URL style

# Content handling
future: false                # Publish future-dated posts
unpublished: false           # Publish unpublished posts
show_drafts: false           # Process _drafts folder
limit_posts: 0               # Limit number of posts (0 = no limit)

# File processing
exclude: [node_modules, Gemfile, Gemfile.lock, README.md]
include: [.htaccess]         # Force inclusion of excluded files
keep_files: [.git]           # Preserve in destination
cache_dir: .jekyll-cache     # Cache directory

# Plugins (gems in legacy config)
plugins:
  - jekyll-feed
  - jekyll-sitemap

# Collections (implied by lib/jekyll/document.rb)
collections:
  posts:
    output: true
    permalink: /:collection/:name/

Environment Variables

# Set environment (development/production)
export JEKYLL_ENV=production

# Custom config file
bundle exec jekyll serve --config _config.yml,_config_dev.yml

Build & Run

Development Server

Basic serve (from lib/jekyll/commands/serve.rb):

bundle exec jekyll serve

Advanced options:

# LiveReload (auto-refresh browser)
bundle exec jekyll serve --livereload

# Custom host/port (0.0.0.0 for network access)
bundle exec jekyll serve --host 0.0.0.0 --port 4000

# Open browser automatically
bundle exec jekyll serve --open-url

# Background process (detach)
bundle exec jekyll serve --detach

# Skip initial build (use with caution)
bundle exec jekyll serve --skip-initial-build

# SSL/TLS support
bundle exec jekyll serve --ssl-cert cert.pem --ssl-key key.pem

# Show directory listing instead of index
bundle exec jekyll serve --show-dir-listing

Build for Production

# Standard build
JEKYLL_ENV=production bundle exec jekyll build

# Clean and rebuild
bundle exec jekyll clean
JEKYLL_ENV=production bundle exec jekyll build

# Build with drafts and future posts
bundle exec jekyll build --drafts --future

Draft Management

Enable drafts via configuration or CLI:

# CLI flag (temporary)
bundle exec jekyll serve --drafts

# Or in _config.yml
show_drafts: true

Place drafts in _drafts/ directory without date prefix (e.g., my-draft-post.md).

Deployment

GitHub Pages (Recommended)

Push to repository:

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/username/repo.git
git push -u origin main

Enable Pages: Repository Settings → Pages → Source → GitHub Actions
Use GitHub Actions workflow (.github/workflows/pages.yml):

name: Deploy Jekyll site to Pages
on:
  push:
    branches: ["main"]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.1'
          bundler-cache: true
      - run: bundle exec jekyll build
      - uses: actions/upload-pages-artifact@v2
  deploy:
    needs: build
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
    runs-on: ubuntu-latest
    steps:
      - uses: actions/deploy-pages@v2

Netlify

Connect Git repository to Netlify
Build settings:
- Build command: jekyll build (or bundle exec jekyll build)
- Publish directory: _site
Add Gemfile and Gemfile.lock to repository

Vercel

Create vercel.json:

{
  "builds": [
    {
      "src": "Gemfile",
      "use": "@vercel/ruby"
    }
  ],
  "buildCommand": "bundle exec jekyll build",
  "outputDirectory": "_site"
}

Traditional Hosting (FTP/RSYNC)

# Build locally
JEKYLL_ENV=production bundle exec jekyll build

# Deploy via rsync
rsync -avz --delete _site/ user@server:/var/www/html/

# Or using jekyll-deploy (plugin required)

Troubleshooting

Ruby Version Issues

Error: jekyll requires Ruby version >= 2.5.0 Solution: Install correct Ruby version via rbenv/rvm:

rbenv install 3.1.0
rbenv local 3.1.0

Bundle Install Failures

Error: Gem::Ext::BuildError: ERROR: Failed to build gem native extension Solution: Install development headers:

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt-get install ruby-dev build-essential

# Fedora/RHEL
sudo dnf install ruby-devel gcc make

Permission Denied

Error: You don't have write permissions for the /Library/Ruby/Gems directory Solution: Use Bundler or user install:

bundle install --path vendor/bundle
# OR
gem install jekyll --user-install

Encoding Issues

Error: invalid byte sequence in UTF-8 Solution: Set locale or add to shell config:

export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

Liquid Syntax Errors

Error: Liquid Exception: Unknown tag Solution: Check plugin availability in safe mode or install missing gems:

# Add to Gemfile
gem 'jekyll-some-plugin'
bundle install

Livereload Not Working

Error: LiveReload connection fails Solution: Check firewall/port 35729 or disable:

bundle exec jekyll serve --no-livereload

Cache Issues

Error: Stale content or build artifacts Solution: Clear cache directory:

bundle exec jekyll clean
# Or manually remove .jekyll-cache/

How to Deploy & Use jekyll/jekyll