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 'https://rubygems.org'
    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`
      end
    end
    
  5. Add the following lines to the _config.yml file:

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

    require 'rack/jekyll'
    require 'yaml'
    run Rack::Jekyll.new
    

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.