Integrate Jekyll with Github Pages and Travis CI to automatically build Jekyll site.
Github Pages are a great approach to building websites. Using a Github repository that follows some naming conventions and the Jekyll static site generator we can build fairly sophisticated static websites that remain easy to maintain. Github Pages will automatically generate a website from a repository containing a Jekyll project and we can use the Github Pages Ruby Gem to maintain a local Jekyll environment in sync with GitHub Pages.
Letting Github Pages generate the Jekyll site has three important limitations:
- we can't use jekyll plugins
- we can't use the Pandoc markdown converter
It is understandable that Github Pages doesn't allow the above for security reasons (it uses the Jekyll
--safe flag). The workaround is to generate the site locally and then to push the generated HTML to Github. This works fine for personal blogs or small websites, but doesn't really scale to collaborative projects - and this is what Github is about. What we need for larger projects is a workflow that automatically builds a Jekyll site hosted on Github Pages whenever the Github repo holding the source code is updated.
The main motivation for me was to be able to use the Pandoc document converter, as I usually generate Scholarly Markdown with embedding of references and some other non-standard markdown. And I need to use plugins to enhance Jekyll, e.g. for better integration with knitr and other tools that produce markdown.
The basic idea is to use the Travis CI continuous integration (CI) service. This service is free for open source projects (assuming fair use) and nicely integrates with Github via Service Hooks. For private projects or projects that are not open source please consider their commercial service for private repositories.
The workflow is as follows:
git pullto the Github repo triggers Travis CI
- Travis CI starts up a virtual machine and installs all required software (mostly Ruby gems)
- We use a custom rake task to tell travis CI how to build the Jekyll site and push the updated content back to Github
- Travis CI clones a different branch (either
master, depending on the kind of Github repo) that holds the static HTML pages
- Travis CI runs
jekyll buildwith the destination in the other branch
- Travis CI does a
git pushof the other branch
- Github Pages starts serving the updates site
Depending on the required software that needs to be installed, the whole process takes anywhere between 1 and 5 min and is fully automated.
You can add the example files provided in this repo to your Jekyll project to get started. Please remember the following:
- make sure you have enabled your source repo in the Travis CI admin dashboard so that the webhook is triggered
- install the travis gem (
gem install travis) and generate a secret version of three required
GH_TOKEN(more info in the sample
- make sure you add
vendorto your .gitignore as Travis CI is vendoring the Ruby gems there. The
vendorfolder should also be excluded in the Jekyll
_config.yml(see example file).
- add the following to your Jekyll
- make sure
_config.ymlmatches the path to the destination repo defined above.
- we have seen intermittent timeouts fetching gems from Rubygems.org.
install: bundle installlets Travis CI automatically retry, and we are using
source "http://production.cf.rubygems.org/"in Gemfile to point to a different repository.
- add the contents of
Rakefileto your Jekyll Rakefile (or replace it). The provided
Rakefilehas some additional commands, but the important one here is
- (Optionally) add a Travis CI logo/link to your README.
The following sites use the workflow described above. Please send me a note if you want me to add your site.
- ALM Community Website - the project website for an Open Source software project. Github repo here, the site currently uses Jekyll in
--safemode (Travis CI needs under 2 min to build the site).
- Opening Science - a book on Open Science, Github repo here.