Home › Blog › How to Deploy a Jekyll Site to Vercel (2026 Guide)
Tutorial

How to Deploy a Jekyll Site to Vercel (2026 Guide)

Deploy Jekyll to Vercel — step-by-step setup, vercel.json configuration, custom domains, environment variables, and the Vercel CLI.

Updated 8 min read
How to Deploy a Jekyll Site to Vercel (2026 Guide)

Vercel is best known as the home of Next.js, but it works equally well for Jekyll sites. Its build infrastructure is fast, the developer experience is polished, and its free tier is generous. If you want a simple Git-connected deploy with a great CLI, Vercel is worth considering.

Why Vercel for Jekyll

  • Automatic Git deploys — push to GitHub, GitLab, or Bitbucket and Vercel deploys automatically
  • Preview URLs for every PR — every pull request gets a unique shareable preview
  • Fast global CDN — Vercel’s Edge Network serves files from locations worldwide
  • Vercel CLI — deploy from your terminal with a single command
  • Free tier — 100GB bandwidth/month, unlimited personal projects
  • Zero config needed — Vercel detects Jekyll automatically

Prerequisites

  • A Jekyll site in a GitHub, GitLab, or Bitbucket repository
  • A Gemfile with your dependencies
  • A Vercel account (free at vercel.com)

Step 1: Prepare your repository

Ensure you have a Gemfile at the project root:

source "https://rubygems.org"

gem "jekyll", "~> 4.3"
gem "jekyll-feed"
gem "jekyll-seo-tag"
gem "jekyll-sitemap"

Run bundle install and commit the lockfile:

bundle install
git add Gemfile Gemfile.lock
git commit -m "Add Gemfile for Vercel"
git push

Step 2: Import your project to Vercel

  1. Go to vercel.com/new
  2. Click Continue with GitHub (or GitLab/Bitbucket) and authorise Vercel
  3. Find your Jekyll repository and click Import
  4. Vercel detects the framework as Jekyll and pre-fills:
    • Framework Preset: Jekyll
    • Build Command: jekyll build
    • Output Directory: _site
    • Install Command: bundle install
  5. Click Deploy

That is it for a basic setup. Vercel runs bundle install then jekyll build and publishes _site/.

Step 3: Create a vercel.json configuration file

For more control, add a vercel.json to your repository root:

{
  "buildCommand": "jekyll build",
  "outputDirectory": "_site",
  "installCommand": "bundle install",
  "framework": "jekyll",
  "env": {
    "JEKYLL_ENV": "production"
  },
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=31536000, immutable"
        }
      ]
    },
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "X-Frame-Options",
          "value": "DENY"
        },
        {
          "key": "X-Content-Type-Options",
          "value": "nosniff"
        }
      ]
    }
  ],
  "redirects": [
    {
      "source": "/old-post/",
      "destination": "/new-post/",
      "permanent": true
    }
  ],
  "rewrites": [
    {
      "source": "/blog/",
      "destination": "/blog/index.html"
    }
  ],
  "cleanUrls": true,
  "trailingSlash": true
}

Commit this file — Vercel picks it up automatically on the next deploy.

Step 4: Set environment variables

In the Vercel dashboard:

  1. Go to your project → Settings → Environment Variables
  2. Add variables for each environment (Production, Preview, Development)

Useful variables for a Jekyll project:

Variable Value Environment
JEKYLL_ENV production Production
JEKYLL_ENV development Preview
RUBY_VERSION 3.2.2 All

Step 5: Add a custom domain

  1. In your Vercel project, go to Settings → Domains
  2. Enter your domain and click Add
  3. Vercel shows the DNS records to add:
    • For the root domain: an A record pointing to 76.76.21.21
    • For www: a CNAME pointing to cname.vercel-dns.com

Add these records at your domain registrar. SSL is provisioned automatically once DNS propagates (usually within minutes).

Configuring redirects in vercel.json

Vercel handles redirects via vercel.json rather than a _redirects file:

{
  "redirects": [
    {
      "source": "/old-url/",
      "destination": "/new-url/",
      "permanent": true
    },
    {
      "source": "/blog/:year/:month/:day/:slug/",
      "destination": "/blog/:slug/",
      "permanent": true
    }
  ]
}

"permanent": true sends a 301 redirect. Use false for a 302.

Deploying with the Vercel CLI

The Vercel CLI is one of the best features for developers who prefer working in the terminal:

npm install -g vercel
vercel login

Deploy a preview:

vercel

Deploy to production:

vercel --prod

Pull environment variables to your local .env:

vercel env pull .env.local

The CLI is particularly useful for testing your production build locally before pushing:

JEKYLL_ENV=production bundle exec jekyll build
vercel --prod --prebuilt

Preview deployments and branch deploys

Every push to a non-production branch creates a preview deployment at a unique URL (https://your-project-abc123.vercel.app). Share this URL with teammates or clients for review before merging.

Configure which branches trigger deployments in Settings → Git → Ignored Build Step.

Specifying Ruby version

Vercel uses a default Ruby version for builds. To pin a specific version, create a .ruby-version file in your project root:

3.2.2

Or set it via the RUBY_VERSION environment variable in your Vercel project settings.

Using GitHub Actions with Vercel (advanced)

For complex builds — fetching content from an API, running a pre-build script — use GitHub Actions:

# .github/workflows/deploy.yml
name: Deploy to Vercel

on:
  push:
    branches: [main]

env:
  VERCEL_ORG_ID: $
  VERCEL_PROJECT_ID: $

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: "3.2"
          bundler-cache: true

      - name: Build Jekyll
        run: JEKYLL_ENV=production bundle exec jekyll build

      - name: Install Vercel CLI
        run: npm install -g vercel

      - name: Pull Vercel environment
        run: vercel pull --yes --environment=production --token=$

      - name: Deploy to Vercel
        run: vercel deploy --prebuilt --prod --token=$

Vercel vs Netlify vs Cloudflare Pages for Jekyll

  Vercel Netlify Cloudflare Pages
Free bandwidth 100GB/month 100GB/month Unlimited
Build minutes 6,000/month 300/month Unlimited
Serverless functions Yes Yes Yes (Workers)
Form handling No Yes (built-in) No
CDN locations ~70 ~100 300+
CLI quality Excellent Good Good

Vercel’s free tier includes 6,000 build minutes — significantly more than Netlify’s 300. For teams with frequent deploys, this matters. Cloudflare Pages has truly unlimited builds and the largest CDN, but Vercel’s developer experience and CLI are the smoothest.

Troubleshooting

Build fails with Could not find gem Ensure Gemfile.lock is committed to your repository. Run bundle install locally and push the lockfile.

404 errors on Jekyll pages Add "cleanUrls": true and "trailingSlash": true to vercel.json to handle Jekyll’s URL structure correctly.

Assets return 404 Verify _site/ contains your assets folder. Check that no exclude: entries in _config.yml are accidentally excluding asset directories.

Custom domain SSL warning SSL is provisioned after DNS propagates. Check DNS propagation with dig yourdomain.com A and wait if records are not yet live.

Vercel is a polished, developer-friendly option for Jekyll deployment — especially if you value a great CLI and want generous build minutes on the free tier.

Share LinkedIn