A collection of grunt tasks for simplifying development and deployment of Jekyll-powered sites on GitHub pages.


A collection of grunt tasks for simplifying development and deployment of Jekyll-powered sites on GitHub pages.

Follows best practices for fast development, easy maintenance, and high performance websites. Google Page Speed, YSlow, your users, and you will be very happy with the end result.

  • Lints your CSS and JavaScripts (using JSList and CSSList)
  • Concatenates and minifies CSS and JavaScript files (using Uglify)
  • Optimizes images (OptiPNG, pngquant, jpegtran and gifsicle)
  • Minifies HTML pages (using html-minifier)
  • Cache busting of static files
  • Easy local development workflow
  • Easy deployment to GitHub Pages

Getting Started

In a nutshell:

  1. Update Gruntfile.js to use this plugin.
  2. Update package.json with the required settings.
  3. Use package.json instead of _config.yml.

This plugin requires:

  • Jekyll
  • node & npm
  • Grunt ~0.4.1
  • GitHub account


If you haven't used Jekyll before, be sure to checkout the Quick-start guide and the Documents.

As you know, Jekyll requires a _config.yml file which defines project settings and site variables.

This plugin creates and overrides this file by converting package.json to _config.yml. If you already have a _config.yml file be sure to define these settings in package.json before you proceed.


package.json holds all your project settings, Jekyll config values, and site variables. See Settings for settings required by this plugin and the Jekyll docs on configuration.

If you don't have a package.json file in your root directory go ahead and create one. If you are not familiar with this kind of file, be sure to checkout this introduction.

You can see an example under examples/package.json.


If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-jekyll-ghpages --save-dev


This plugin provides a set of tasks based on other grunt plugins so all you have to do is make sure you extend your grunt configuration to include these tasks.

Once the plugin has been installed update your gruntfile to something like this.

var extend = require('extend'),
    jgh = require('grunt-jekyll-ghpages');

module.exports = function(grunt) {
  grunt.initConfig(extend(jgh.config, {
    pkg: grunt.file.readJSON('package.json'),
    // your grunt config here

  // Load all available grunt tasks at once
  // so you don't have to do grunt.loadNpmTask(...)
  // for each plugin you use.

  // Shortcuts to jekyll_ghpages tasks (optional, but recommended)
  grunt.registerTask('default', ['jekyll_ghpages_dev',]);
  grunt.registerTask('serve', ['jekyll_ghpages_serve',]);
  grunt.registerTask('deploy', ['jekyll_ghpages_deploy',]);

You can see and modify these tasks in node_modules/grunt-jekyll-pages/tasks/jekyll_ghpages.js line 11.


Specify these settings in your package.json file.


The current release version of the website. A git tag is created with the version of your site when you deploy.


The name of the project (string, no whitespace).


The root directory of the website (string, no trailing slash).

If only hosting on GitHub pages this should be your project's name, eg /jekyll-template.

If using a custom domain this should be the domain name in the following format: //[subdomain.]


The name of the folder in which Jekyll will build the site.

Default: _site


The name of the folder in which to build the site when serving locally (via grunt serve) prior to deploying.

Default: .serve


The name of the folder were your static assets will live.

Default: static


A dictionary specifying the directories for images, styles, and scripts.


"assets": {
    "images": "/static/images/",
    "css": "/static/css/",
    "js": "/static/js/"

Available Tasks

Normally you would only need to use the jekyll_ghpages_dev, jekyll_ghpages_serve, and jekyll_ghpages_deploy tasks (in that order).

You can also call tasks using the format grunt jekyll_ghpages:[task] (eg. grunt jekyll_ghpages:dev or grunt jekyll_ghpages:deploy).


Prepares your Jekyll site for development and serves it from

It also watches for changes and rebuilds the site.


Prepares your Jekyll site for deployment and runs it from so that you can make sure everything works as expected.

Internally it calls the build, lint, and static tasks.


Deploys the site on GitHub (gh-pages branch). Internally it calls the build, lint, and static tasks.


Calls config task and builds the site with jekyll build.


Converts package.json to _config.yml for Jekyll.


Runs JSList and CSSList on your static assets.


Prepares your static assets for release.

  • Runs JSList and CSSList on your static assets
  • Concatenates and minifies CSS and JavaScript files
  • Optimizes images
  • Updates references to static assets to break the cache
  • Minifies HTML pages

How to

Use a Custom Domain

  • Specify the baseurl property in package.json to be the domain name of your choice to //[subdomain.]
  • Specify the domain in the CNAME file (eg. [subdomain.]

Update your DNS records following the instructions provided by Github.


In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History

(Nothing yet)