Deploy to Netlify¶

Deploy your Jekyll site to Netlify with continuous deployment from GitHub.

Overview¶

Netlify offers several advantages over GitHub Pages:

Custom headers — Control caching and security headers
Redirects — URL rewriting and redirects
Forms — Built-in form handling
Functions — Serverless functions
Deploy previews — Preview branches before merging

Prerequisites¶

GitHub account with your Jekyll site repository
Netlify account (free tier available)

Setup¶

Step 1: Prepare Your Repository¶

Ensure your Gemfile.lock is up to date:

bundle install
bundle update

Commit the updated lock file:

git add Gemfile.lock
git commit -m "Update Gemfile.lock for Netlify"
git push

Step 2: Create Netlify Account¶

Go to netlify.com
Click Sign up and authenticate with GitHub
Authorize Netlify to access your repositories

Step 3: Connect Repository¶

From the Netlify dashboard, click "Add new site" → "Import an existing project"
Choose GitHub as your Git provider
Authorize Netlify if prompted
Select your Jekyll repository

Step 4: Configure Build Settings¶

Setting	Value
Branch to deploy	`main` (or your default branch)
Build command	`jekyll build`
Publish directory	`_site`

Click "Deploy site" to start the first build.

Step 5: Monitor Deployment¶

Watch the build logs for any errors
Once complete, Netlify provides a random URL (e.g., random-name-12345.netlify.app)
Click the URL to view your deployed site

Configuration Files¶

netlify.toml¶

Create netlify.toml in your repository root for advanced configuration:

[build]
  command = "jekyll build"
  publish = "_site"

[build.environment]
  JEKYLL_ENV = "production"
  RUBY_VERSION = "3.0.0"

# Redirects
[[redirects]]
  from = "/old-page"
  to = "/new-page"
  status = 301

# Headers
[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-XSS-Protection = "1; mode=block"
    X-Content-Type-Options = "nosniff"

# Cache static assets
[[headers]]
  for = "/assets/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000"

_redirects File¶

Alternatively, create a _redirects file in your site root:

# Redirect old URLs
/old-page    /new-page    301

# SPA fallback (if using client-side routing)
/*    /index.html   200

_headers File¶

Create a _headers file for custom headers:

/*
  X-Frame-Options: DENY
  X-XSS-Protection: 1; mode=block

/assets/*
  Cache-Control: public, max-age=31536000

Custom Domain¶

Option 1: Netlify UI¶

Go to Site settings → Domain management
Click "Add custom domain"
Enter your domain name
Follow DNS configuration instructions

Option 2: DNS Configuration¶

Add these records at your domain registrar:

For apex domain (example.com):

Type: A
Name: @
Value: 75.2.60.5

For www subdomain:

Type: CNAME
Name: www
Value: your-site.netlify.app

Netlify automatically provisions SSL certificates via Let's Encrypt.

Environment Variables¶

Set environment variables in Netlify UI or netlify.toml:

Go to Site settings → Build & deploy → Environment
Add variables:
JEKYLL_ENV=production
Any API keys your site needs

Deploy Previews¶

Netlify automatically creates preview deployments for pull requests:

Open a pull request on GitHub
Netlify builds and deploys a preview
Preview URL appears in the PR comments
Test changes before merging

Troubleshooting¶

Build Failures¶

Check the deploy log for errors:

Go to Deploys tab
Click the failed deploy
Review build logs

Common issues:

Missing Gemfile.lock — Run bundle lock
Ruby version mismatch — Specify in netlify.toml
Plugin errors — Ensure all gems are in Gemfile

Slow Builds¶

Optimize build time:

Use bundle install --jobs 4 for parallel installs
Cache dependencies (Netlify does this automatically)
Reduce build scope with incremental builds

SSL Certificate Issues¶

If HTTPS isn't working:

Verify DNS propagation with dig yourdomain.com
Check Domain management → HTTPS
Click Verify DNS configuration
Provision certificate manually if needed

Comparison with GitHub Pages¶

Feature	Netlify	GitHub Pages
Custom plugins	Yes	No (whitelist only)
Custom headers	Yes	No
Redirects	Yes	Limited
Deploy previews	Yes	No
Forms	Yes	No
Functions	Yes	No
Build time	Faster	Slower
Free tier	Generous	Unlimited

Next Steps¶

Custom Domain Setup
Security Headers — Harden your site