Jekyll on Heroku

Jekyll is simple static content compiler popularized by GitHub Pages. If you use Jekyll in a GitHub repo a static website will automatically be created for you by running Jekyll on your content sources (e.g. Markdown). That works well but there are cases where it is nice to deploy a Jekyll site on Heroku. After trying (and failing) to follow many of the existing blogs about running Jekyll on Heroku, I cornered my coworker Terence Lee and got some help. Turns out it is pretty simple.

Not interested in the details? Skip right to a diff that makes a Jekyll site deployable on Heroku or start from scratch:

Deploy on Heroku

Here are the step by step instructions:

  1. Add a Gemfile in the Jekyll project root containing:

    source ''
    ruby '2.1.2'
    gem 'jekyll'
    gem 'kramdown'
    gem 'rack-jekyll'
    gem 'rake'
    gem 'puma'
  2. Run: bundler install
  3. Create a Procfile telling Heroku how to serve the web site with Puma:

    web: bundle exec puma -t 8:32 -w 3 -p $PORT
  4. Create a Rakefile which tells Heroku’s slug compiler to build the Jekyll site as part of the assets:precompile Rake task:

    namespace :assets do
      task :precompile do
        puts `bundle exec jekyll build`
  5. Add the following lines to the _config.yml file:

    gems: ['kramdown']
    exclude: ['', 'Gemfile', 'Gemfile.lock', 'vendor', 'Procfile', 'Rakefile']
  6. Add a file containing:

    require 'rack/jekyll'
    require 'yaml'

That is it! When you do the usual git push heroku master deployment, the standard Ruby Buildpack will kick off the Jekyll compiler and when your app runs, Puma will serve the static assets. If you are starting from scratch just clone my jekyll-heroku repo and you should have everything you need.

To run Jekyll locally using the dependencies in the project, run:

bundle exec jekyll serve --watch

Let me know how it goes.

  • Love me some Jekyll and Heroku; only better together.

  • I had to add a file that runs the Jekyll Rack, in order to make it work Otherwise I always got a Puma error at launch that said : ERROR: [2] No application configured, nothing to run.
    Concerning the rest of the tutorial, nothing to say, awesome stuff !

    • Thanks! Not sure how I missed that step. But I’ve added it to the instructions.

  • For anyone else trying to do this now, I found that my CSS wouldn’t work unless I specifically used the latest version of the rack-jekyll gem from Github:

    gem 'rack-jekyll', :git => ''

  • Perfect! I’ve just been toying with Jekyll recently and migrating my posts from Squarespace

  • aeroblade

    If you want all of the Jekyll files in a single nested directory (such as `pwd`/web), a couple files need to be changed:

    Rakefile (line 3):
    puts `bundle exec jekyll build -s web -t`
    require ‘rack/jekyll’
    require ‘yaml’

    • I’m not sure. The build instructions look pretty involved.

  • Anshul Sahni

    is someone facing any issue like `Jekyll is currently rendering the site.
    Please try again shortly.` after deploying the app on heroku. full issue described here

  • carc1n0gen

    This guide was spot on, it just worked!

  • ty