grunt-github-pages

Push to gh-pages no problem

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.

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

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 git@github.com: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!

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 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.

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.

Type: string Default: auto commit

The default commit message for the gh-pages branch.

Type: string Default: origin

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

Type: string Default: gh-pages

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

  • v0.0.1, Mid Mar 2013
    • Big Bang

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