Jekyll •
Last updated: July 8, 2025

Jekyll Theme Deployment

Tokyo Jekyll Theme

Table of Contents

Deploying your Jekyll site is the final step to make it live on the internet. There are several excellent options available, each with their own advantages. This guide covers the most popular deployment methods.

Prerequisites

Before deploying, ensure your Jekyll site is ready:

  1. Test locally first: 
    bundle exec jekyll serve
  2. Build the site: 
    bundle exec jekyll build
  3. Check the _site folder - this contains your built site ready for deployment.

Deployment Methods

GitHub Pages is perfect for beginners and offers free hosting for Jekyll sites.

  1. Create a GitHub repository with your Jekyll site
  2. Push your code to the repository

  3. Enable GitHub Pages:

    • Go to Settings → Pages
    • Select source branch (usually main or master)
    • Choose folder (/ for root or /docs)
  4. Configure Jekyll for GitHub Pages: 
    # _config.yml
baseurl: "/your-repo-name"
url: "https://yourusername.github.io"

Netlify offers more flexibility and features than GitHub Pages.

  1. Connect your repository:

    • Sign up at netlify.com
    • Click “New site from Git”
    • Connect your GitHub/GitLab/Bitbucket account

  2. Configure build settings:

    Build command: bundle exec jekyll build
Publish directory: _site

  3. Deploy automatically - every push to your main branch triggers a new deployment

3. Vercel (Modern Alternative)

Vercel is excellent for modern web development workflows.

  1. Install Vercel CLI:

    npm i -g vercel

  2. Deploy with one command:

    vercel

  3. Follow the prompts to connect your repository

4. Manual Deployment

For complete control, you can manually upload your built site.

  1. Build your site:

    bundle exec jekyll build

  2. Upload _site contents to your web server via FTP/SFTP

  3. Configure your web server to serve static files

Advanced Configuration

Custom Domains

Most platforms support custom domains:

  1. Purchase a domain from a registrar
  2. Add DNS records as instructed by your hosting platform
  3. Configure in your hosting platform’s settings

Build Optimization

Optimize your builds for faster deployment:

# _config.yml
exclude:
  - node_modules
  - .git
  - README.md

Troubleshooting Common Issues

Build Failures

Problem: Site won’t build on deployment platform Solution:

  • Test locally first: bundle exec jekyll build
  • Check for unsupported plugins
  • Verify _config.yml syntax

Missing Assets

Problem: Images/CSS not loading Solution:

  • Check file paths (use relative URLs)
  • Ensure assets are in the correct folders
  • Verify baseurl setting

Custom Domain Issues

Problem: Custom domain not working Solution:

  • Wait for DNS propagation (up to 48 hours)
  • Check DNS records are correct
  • Verify SSL certificate is active

Best Practices

  1. Always test locally before deploying
  2. Use version control for your site
  3. Set up automatic deployments
  4. Monitor your site after deployment
  5. Keep backups of your content
  6. Document your deployment process

Conclusion

Choose your deployment method based on your needs:

  • GitHub Pages: Great for beginners and simple sites
  • Netlify: Best for advanced features and flexibility
  • Vercel: Excellent for modern development workflows
  • Manual: For complete control and custom requirements

Remember to test thoroughly and monitor your site after deployment. Most issues can be resolved by checking the build logs and testing locally first.

For more detailed guides on specific platforms, check out their official documentation: