Grunt Github Pages

Publish your project's pages on Github with one command.

A Grunt task that enables you to publish to the gh-page branch with one command line.

Getting Started

npm install grunt-github-pages --save-dev

Preparing your repository

You need to create a folder and add it to your .gitignore file. In that folder you have to clone the same repository again and point to the gh-page branch.

Assume the target folder is named _site/ and our github repository is named project:

$ ls -la
.
..
.git
.gitignore
index.md

We add the _site folder in .gitignore and clone the current repository ( project ) to _site:

$ git clone [e-mail]:thanpolas/project.git _site
 
$ cd _site

A full copy of the project repository now exists in the _site folder. We now need to point it to the gh-pages branch and we are good to go:

$ pwd
project/_site/
 
$ git checkout --orphan gh-pages
# Creates our branch, without any parents (it's an orphan!) 
Switched to a new branch 'gh-pages'
 
$ git rm -rf .
# Removes all files from the old working tree 
rm '.editorconfig'
rm '.gitignore'
…

The gh-pages branch won't appear in the list of branches generated by git branch until you make your first commit.

$ echo "Testing Grunt Github Pages" > index.html
$ git add index.html
$ git commit -a -m "First pages commit"
$ git push origin gh-pages

Your repository is now ready to start using the Github Pages task!

The githubPages Task

Edit your Gruntfile and add the githubPages task:

  githubPages: {
    target: {
      options: {
        // The default commit message for the gh-pages branch
        commitMessage: 'push'
      },
      // The folder where your gh-pages repo is
      src: '_site'
    }
  }
 
  /* ... later on, after grunt.initConfig() call, create an alias: */
 
// create an alias for the githubPages task
grunt.registerTask('deploy', ['githubPages:target']);

So when you issue grunt deploy on your command line this is what will happen:

1. The Current Working Directory will change to _site.
2. The command git add . will be performed.
3. The command git commit -am "push" will be performed.
4. The command git push origin gh-pages will be performed.

The src Option

The src option must be a single string that represents a directory. The API is weak at this point but use cases need to be presented before a solution is attempted as there are a few intricacies involved. So do create an issue if you need globbing patterns here.

The dest Option

There are some cases, like building a Jekyll site, that the destination folder _site will get overwritten by the generation of static pages, along with the .git folder. For these kind of cases a trick would be to maintain one more ignored directory where the .git folder is retained.

The second ignored directory should be the dest option in your config file:

  githubPages: {
    target: {
      // The folder where your gh-pages repo is
      src: '_site',
      // The second ignored directory with the .git folder
      dest: '_site_git'
    }
  }

In this case, when you issue grunt push this is what will happen:

1. All the contents of _site folder will be deep copied to _site_git overriding.
2. The Current Working Directory will change to _site_git.
3. The command git add . will be performed.
4. The command git commit -am "auto commit" will be performed.
5. The command git push origin gh-pages will be performed.

Other Options

commitMessage

Type: string Default: auto commit

The default commit message for the gh-pages branch.

remote

Type: string Default: origin

The name of the remote to be used when issuing git push.

pushBranch

Type: string Default: gh-pages

The name of the branch to be used when issuing git push.

Release History

• v0.0.1, Mid Mar 2013
  • Big Bang

License

Copyright (c) 2013 Thanasis Polychronakis Licensed under the MIT.