Deploying Harp.js Builds To Github Pages

code | 3-25-2014

About a month ago, I switched from running my blog using Poet.js on Nodejitsu to using Harp.js to compile it as a static site. There are several benefits to taking this approach. First of all, I can host the site using any server environment. When I build it, all that I have are HTML, CSS and JavaScript files and they can be hosted with Node, Apache, IIS or any other server. Another benefit is that there are several places where I can host my blog for free.

I ended up choosing to go with Github pages because this is a web development blog and I thought it was well-suited for their platform. This is how I got it working.

First of all, it should be noted, that Github pages have to be served from the root of your project. For example, your would serve up ./index.html. So, to begin with, I put all of my templates, css, javascript and markdown files in a subfolder named "_harp".

Serving Harp Locally

Next, I opened my .profile file in the terminal and created an alias to start up the server without needing to manually navigate into the _harp directory:

alias tyson_run='cd ~/Sites/apps/; harp server;';

With that done, I just needed to call tyson_run and a server would be spawned at port :9000 with my blog. I know this part isn't really related to serving the site on Github Pages, but it is important to have a local testing environment.

Setting Up Github Pages

Github has a ton of documentation about how to set up and run Github pages, so I won't attempt to rewrite what's already been written.

I will say that you need to remember to create a branch in your repository called gh-pages to push your blog to. Github will be looking for that branch to serve from.

Building and Deploying

I found myself repeating several steps every time I wanted to deploy my blog. First of all, I noticed that when I compiled my code, the static assets such as images, javascript files and the CNAME file, which is important for telling Github to use a custom domain were all missing. It was easy enough to copy them up a directory in the terminal, but it was needlessly tedious.

I also found that with me being the only person with push access to my repo, I was never going to need to manage merge conflicts, so adding the files, committing them and pushing was needlessly verbose.

Because of all that, I ended up writing a function in my .profile file that compiles harp, copies the static assets that harp misses, adds the files to the git branch, commits the files with whatever message I pass in as an argument and pushes the code.

function tyson_deploy () {
        cd ~/Sites/apps/;
        harp compile _harp ./;
        cp -r _harp/images images;
        cp -r _harp/js js;
        cp _harp/CNAME CNAME;
        git add .;
        git add -u;
        git commit -m "$1";
        git push origin gh-pages;

Now, I just need to run tyson_deploy and my code is pushed to the gh-pages branch. Any code in that branch is automatically served by Github, which means that after I push, my code is deployed.

I have been really happy with harp as a solution. There are a few features I'd love to see integrated, such as static paging but in the meantime, it works really well for my needs.

Now, excuse me while I type "tyson_deploy" into my terminal...

About the Author

Tyson Cadenhead is a Senior JavaScript Developer at Aloompa. He lives in the greater Nashville area. His specialty is writing large, scalable JavaScript applications on the client and server side. His passions are for good design, usability, and clean, reusable code.

Tags: html node terminal

Related Posts:

comments powered by Disqus

Don't Miss Anything!

Sign Up For My Email Newsletter

I Wrote a Book!

Popular Posts