Deploy Your Jekyll Chirpy Blog to Cloudflare Workers

If you’re running a Jekyll blog with the Chirpy theme and want blazing-fast, serverless, and cost-effective hosting, Cloudflare Workers is an excellent choice. This combination gives you a fully static, globally distributed website with edge computing capabilities — all without managing servers.

In this comprehensive guide, you’ll learn how to deploy your Jekyll Chirpy blog to Cloudflare Workers, from initial setup to going live with your site.

Why Choose Cloudflare Workers for Jekyll?

Before diving into the setup, here’s why this combination is powerful:

• Global Edge Network: Your site is served from 300+ locations worldwide
• Lightning Fast: Sub-100ms response times globally
• Generous Free Tier: 100,000 requests per day for free
• Zero Cold Starts: Unlike traditional serverless, Workers start instantly
• Built-in CDN: Automatic caching and optimization
• Custom Domains: Easy SSL and domain management

Prerequisites

Before starting, ensure you have:

• A GitHub account
• A Cloudflare account (free tier works)
• Basic command line knowledge
• Git installed on your machine
• Ruby installed (for local development)

---

Step 1: Set Up Jekyll Chirpy Locally

Install Ruby and Bundler

If you don’t have Ruby installed, here’s how to get it:

Linux (Ubuntu/Debian)

sudo apt-get update
sudo apt-get install ruby ruby-dev build-essential
gem install bundler

macOS

brew install ruby
gem install bundler

Windows

Download and install Ruby+Devkit from rubyinstaller.org.

Create Your Jekyll Chirpy Project

# Clone the Chirpy starter
git clone https://github.com/cotes2020/jekyll-chirpy-starter.git my-chirpy-blog
cd my-chirpy-blog

# Initialize git
git init

# Install dependencies
bundle install

Configure Your Blog

Edit _config.yml to set your blog details:

url: "https://blog.yourdomain.com"
baseurl: ""
title: "Your Blog Title"
timezone: Asia/Kolkata

Create Your First Post

jekyll new posts/my-first-post.md
# or manually create in _posts/

Edit the generated file in _posts/YYYY-MM-DD-my-first-post.md:

---
title: "My First Post"
date: 2026-03-29T10:00:00 +0530
categories: [Dev]
tags: [jekyll, chirpy]
---

Welcome to my new Jekyll Chirpy blog! This is my first post deployed to Cloudflare Workers.

## Why I Chose Jekyll Chirpy + Cloudflare Workers

- Clean, modern design out of the box
- Dark mode support
- Fast static site generation
- Global edge distribution
- Excellent developer experience
- Cost-effective hosting

Test Locally

bundle exec jekyll serve

Your blog will be available at http://localhost:4000. Press Ctrl+C to stop the server.

---

Step 2: Prepare for Deployment

Push to GitHub

1. Create a new repository on GitHub (let’s call it my-chirpy-blog)

2. Push your local content:

git add .
git commit -m "Initial Jekyll Chirpy blog setup"
git remote add origin https://github.com/YOUR_USERNAME/my-chirpy-blog.git
git push -u origin main

---

Step 3: Configure Cloudflare Workers

Now we need to add the necessary configuration files for Cloudflare Workers.

Create wrangler.toml

Create a wrangler.toml file in your project root:

# wrangler.toml
name = "my-chirpy-blog"
compatibility_date = "2026-03-29"

[build]
command = "bundle exec jekyll build"

[assets]
directory = "./_site"
not_found_handling = "404-page"

# Custom domain (optional)
# routes = [
#   { pattern = "blog.yourdomain.com", custom_domain = true }
# ]

Commit Changes

git add .
git commit -m "Add Cloudflare Workers configuration"
git push origin main

---

Step 4: Deploy to Cloudflare Workers

Access Cloudflare Dashboard

1. Login to Cloudflare Dashboard
2. Navigate to Workers & Pages from the sidebar
3. Click Create Application
4. Select Pages tab
5. Click Connect to Git

Connect Your Repository

1. Connect GitHub Account: If not already connected, authorize Cloudflare to access your GitHub repositories

2. Select Repository: Choose your my-chirpy-blog repository

Configure Deployment Settings

1. Project Name: Enter my-chirpy-blog (must match the name in wrangler.toml)
2. Production Branch: Select main
3. Build Settings:
   • Framework preset: Jekyll (or None with custom command)
   • Build command: bundle exec jekyll build
   • Build output directory: _site

Deploy Your Site

1. Click Save and Deploy
2. Cloudflare will start building your site
3. The build process typically takes 3-5 minutes for the first time

Deployment Complete

Once the build completes, you’ll see your live site URL:

Your Jekyll Chirpy blog is now live on Cloudflare Workers! 🎉

---

Step 5: Custom Domain (Optional)

To use your own domain:

1. Add Domain to Cloudflare:
   • Go to Websites in Cloudflare Dashboard
   • Add your domain and follow DNS setup instructions
2. Configure Custom Domain:
   • In your Workers project, go to Custom Domains
   • Click Set up a custom domain
   • Enter your domain name
   • Cloudflare will automatically provision SSL certificates
3. Update wrangler.toml:

routes = [
  { pattern = "blog.yourdomain.com", custom_domain = true }
]

---

Continuous Deployment

With this setup, your blog will automatically rebuild and redeploy whenever you:

1. Push changes to your main branch
2. Add new blog posts
3. Update your theme or configuration

Adding New Posts

To add a new post:

# Create new post (using Jekyll's built-in command)
jekyll new posts/my-second-post.md

# Or manually create _posts/2026-03-30-my-second-post.md

# Edit the post content
# Set published: true when ready to publish

# Deploy
git add .
git commit -m "Add new blog post"
git push origin main

---

Troubleshooting

Common Issues and Solutions

Build Fails: “bundle: command not found”

• Ensure your Ruby version is compatible with the Chirpy theme
• Check that Gemfile and Gemfile.lock are committed to your repository

Build Fails: “html-proofer” Errors

• This gem is only needed for local testing, not production builds
• Remove the :test group from your Gemfile if deploying to Cloudflare:

# Remove or comment out this group from Gemfile
# group :test do
#   gem "html-proofer", "~> 5.0"
# end

Theme Not Loading

• Verify _config.yml has theme: jekyll-theme-chirpy
• Ensure git submodules are properly initialized
• Check that theme files exist in themes/ directory

404 Errors on Subpages

• Verify not_found_handling = "404-page" in wrangler.toml
• Check that Jekyll is generating pages correctly with bundle exec jekyll serve locally

Build Takes Too Long

• Consider optimizing images and assets
• Review Jekyll configuration for unnecessary processing
• Enable caching in _config.yml

Debugging Tips

1. Check Build Logs: Always review the build logs in Cloudflare Dashboard for specific error messages

2. Test Locally: Run bundle exec jekyll serve locally to verify your site works before deploying

3. Validate Configuration: Use bundle exec jekyll doctor to check your site configuration

---

Security Considerations

Content Security Policy

Add CSP headers to enhance security:

# In wrangler.toml
[assets.header_rules]
"/*" = { "Content-Security-Policy" = "default-src 'self'; img-src 'self' data: https:; style-src 'self' 'unsafe-inline'" }

Environment Variables

For sensitive data, use Cloudflare Workers environment variables instead of committing them to your repository.

---

Monitoring and Analytics

Cloudflare Analytics

Cloudflare provides built-in analytics for your Workers site:

• Traffic metrics
• Performance data
• Security insights
• Geographic distribution

Third-party Analytics

You can easily add analytics services like:

• Google Analytics
• Plausible Analytics
• Fathom Analytics

Add the tracking code to your Chirpy theme’s head partial or use the built-in analytics configuration in _config.yml.