30 Apr 2013


There comes a time in every Github user’s life, when they begin to assume that other people might give a damn about the code they have written. While this assumption is by and large wrong, every so often someone produces something worth wrapping a marketing homepage around. Or they might want to dress up their GitHub page enough that their coworkers are willing to treat their reinvention of the wheel as a first class framework.

For the rest of this doc I’ll be writing to the latter group (since that’s the category I fall into) but the steps should be the same in either case.

Getting Started

We’re going to need to get a few things going before we get started:

 Setting up a github repo for  your site

Follow along here, or get more details on setting up your user pages on github from their docs: https://help.github.com/articles/user-organization-and-project-pages

  • Create a new repository using the convention:

so if your github username is bobloblaw, you’re be creating a new repo called “bobloblaw.github.io”

Creating a "src" branch to maintain your javascript app in

If i leave something out, yeoman talks a little about this step here: http://bit.ly/13GXzmz

Basically, the trick here, is GitHub wants to host the root of your “master” branch as your doc root, and yeoman wants your docroot to be hosted out of the “dist/” folder. So what we’re going to do it set up a “src” branch to hold our yeoman development environment, and publish (git subtree push) the contents of dist/ to the root of our master branch.

  • Clone your new repo & create a "src" branch so we can add in some Yeoman!
    $ git clone git@github.com:bobloblaw/bobloblaw.github.io.git
    $ git branch src
    $ git checkout src
    $ echo "#github pages src branch" > README.md
    $ git commit -am "adding a readme so i can add this branch to my repo on github"
    $ git push -u origin src


At this point,  we need to get our Yeoman on so we have something to publish. Even though the possibilities are virtually endless and yeoman could be the topic of several tutorials, let’s just assume you’re into AngularJS:

  • from your checkout of the src branch, scaffold out your application with Yeoman
    $ npm install generator-angular generator-karma
    $ yo angular

Now you’ve got  a brand spankin new angular app thats just itching to be built and deployed to GitHub

  • build your project
    $ grunt build
  • tweak your .gitignore file to allow committing the dist folder we just built (remove "dist" from the file)
    nano .gitignore
  • commit stuff and push!
    $ git commit -am "bob loblaw's github account is about to get snazzy"
    $ git push origin src

Get it in the interwebs!

Now that we’ve got our app built and you’ve sorted out how to acquire npm which i pretended you just had, you’d think we would be pretty close to seeing something on your github page. But first we have to install a shiny new tool for your git client. Or maybe you’re lucky and running “git subtree” doesn’t spit back:

"git: 'subtree' is not a git command. See 'git --help'."

If you’re running Ubuntu or HomeBrew on OS X,  this should help you: http://bit.ly/ZYfJgB If you’re running port on OS x, give this a try:

$ git clone https://github.com/git/git.git
$ cd git/contrib/subtree/
$ make
$ sudo cp git-subtree /opt/local/libexec/git-core/

No Really, Get it in the interwebs!

Ok ok, now it really is just a command away:

  • push your dist folder to the master branch
    $ git subtree push --prefix dist origin master

Bask in the glory

Did it work? http://bobloblaw.github.io should be hosting your angular app now… but there’s always a chance it isn’t.

If it is, then that means that your open source gem is at last being properly represented. With a crisp looking page declaring “‘Allo!” to anyone who will listen, it’s only a matter of time before the forks come rolling in and you start gaining notoriety as not just a hacker, but someone who can see the role marketing plays in programming.

Added bonus: at the next dinner party you attend you can stop sheepishly replying “I’m just so busy!” when your fans implore you to start publishing your code.

comments powered by Disqus