This is part 1 in a series on set­ting up your per­sonal space on the web:

• Part 1: Setting up a Github Project Page
• Part 2: Setting up an Octopress site for you blog and portfolio

Set­ting up a per­sonal space on the web is eas­ily one of the best things I’ve done this year. If you’re new to Web Design/De­vel­op­ment and you want to know what the single best thing you can do is, I’m going to lay it all out for you right here.

So be­fore we get star­ted, a few dis­claim­ers:

1. These are my suggestions. There’s a lot of flexibility here. You can use different tools, different hosting, whatever.
2. Some of this stuff may seem complicated or excessive. I’ll try and cover the “why” of each step in an aside, in case you’re curious. However, some of these tools have entire books dedicated to them, so I’ll try and redirect you to a better source if you’re still puzzled.
3. I’m assuming some familiarity with these tools (especially Git). If something seems crazy, I’ll link to more documentation, but I’m going to be moving at a bit of a brisk pace.
4. None of these steps matter, as long as in the end you achieve the following:

You need to have a place on the web that you can call your own. Ideally, it should be:

• A place where, if an idea strikes you, you can immediately build it and share it.
• A place where, if someone wants to see real examples of your work, all your weekend projects and little experiments are on display.
• Hosted in such a way that it won’t keel over if you get a couple thousand hits from Hacker News.

I posit that the best way to do this is to get an oc­to­press blog on git­hub pages on a per­sonal do­main, and then de­velop all your pro­jects with a gh-pages branch so you can share them eas­ily. After about a year of hav­ing this easy pub­lish­ing at your dis­posal, you’ll sud­denly real­ize that you now have an eas­ily share­able on­line port­fo­lio. Awe­some.

If you want to see the code for my per­sonal web­site (which should in­clude the file with this blog post) I’ve up­loaded it here. This is the kind of thing you’re going to end up with at the end of all this.

Getting your environment set up

For this first part, all you need is a ter­minal (I use the Mac OS X Ter­minal that comes with any Mac), and an in­stall of git (which comes with every Mac).

You should also have your text ed­itor of choice. Any text ed­itor will do, al­though I highly rec­comend Sub­lime Text and/or Brack­ets.

Let’s talk about Github pages

So Git­hub is a great web­site that lets you up­load your code to share with oth­ers. There are tons of great code­bases on there, and you could spend days just por­ing over the code in some of the really great pro­jects. However, what we’re really in­ter­ested in here is Git­hub Pages.

Ba­sic­ally, Git­hub will host your site for free. Yes. Free. The catch is that your site has to be static. It has to be a folder full of html, css, javas­cript and image files that the server can throw at someone if they ask for them by name. No data­base, no backend logic, just a folder full of files.

There are huge ad­vant­ages to hav­ing a site like this. Even if you don’t use Git­hub Pages, you can eas­ily find cheap host­ing for a static site. There’s also the fact that static sites are really cheap and easy to serve, so your site can stand up to mon­strous amounts of traffic. As of today, I’ve never heard of any­one’s Git­hub Pages site going down due to too many re­quests, and Git­hub never comes after your credit card.

And it gets bet­ter. With Git­hub Pages you can eas­ily make a page for any of your pro­jects. If one of your Git­hub re­pos­it­or­ies has a branch called gh-pages, and that branch has an index.html file, you can eas­ily get to it at {yourname}.github.io/{repository-name}. These pro­ject pages are the best part of this whole thing, so let’s get that squared away right now.

Let’s publish a project

To start out, go to Git­hub and make a new re­s­pos­it­ory. Call it HelloWeb, de­cide whether you want a README file and a .gitignore file (you can start with one or make one later, it doesn’t really mat­ter) …al­right good. Now go into your Ter­minal, find a nice cozy part of your hard drive (I re­com­mend mak­ing a ~/Development dir­ect­ory to keep all your dev stuff in) and type the fol­low­ing com­mand:

1

git clone https://github.com/{yourname}/HelloWeb

This will down­load the git re­pos­it­ory and store it in a dir­ect­ory named HelloWeb. USe the com­mand cd HelloWeb to go in­side the re­pos­it­ory. Now, you’ll start off on the master branch, so you’ll need to make a gh-pages branch where you’ll be doing your cod­ing.

1
2

git branch gh-pages
git checkout gh-pages

So far so good, now fire up your text ed­itor and make a file in ~/Development/HelloWeb called index.html. You can keep it simple:

1
2
3
4

<h1>Hello!</h1>
<script>
    alert('Hello Hello!');
</script>

Save that, head back to the Ter­minal, and add this file to your re­pos­it­ory:

1

git add index.html

Now make a com­mit to “save” what you’ve done:

1

git commit -am "Added index.html"

Now push the gh-pages branch up to Git­Hub (they take care of set­ting up a lot of the re­mote stuff)

1

git push origin gh-pages

Now go to {yourname}.github.io/HelloWeb. There’s your page! (It may take a minute or so the first time)

The hard part is done. You have an HTML file on your com­puter. You can put any HTML, CSS or Javas­cript in there, and it will show up, as you wrote it, to any­one, on any com­puter, any­where in the world (if they visit your web­site).

Feel that? That’s what power feels like.

Now let’s try something else. Let’s take someone else’s pro­ject, make some changes to it, and up­load it to our site.

Make your own 2048

Let’s say you really like the game 2048, and you want to make a spinoff that works a little dif­fer­ently. A lot of my pro­jects start off like this— I’ll see something cool, ima­gine a dif­fer­ent way it could work, make some changes, and then share it (giv­ing credit to the per­son who had the idea of course).

You may have no­ticed, 2048 is on a github.io do­main. The guy who made it pushed it to the gh-pages branch of a repo named “2048”. This will be pretty easy. First, go to https://​github.​com/​gabrielecirulli/​2048 and click the but­ton in the upper right part of the screen labeled “Fork”.

Once you’ve forked the repo (that is, you’ve made a per­son­ally copy of it that is now under your name) down­load it to your ~/Development/ dir­ect­ory:

1
2
3

git clone https://github.com/{yourname}/2048
cd 2048
git checkout gh-pages

Ready to go? Al­right, make a change to one of the files in there. Do any­thing. Make the back­ground pink. Use CSS fil­ters to make the num­bers blurry. Put your name on the page as an <h1>, any­thing. When you’re done, do this:

1
2
3

git add {any new files you made if you made any}
git commit -am "{write a description of your change}"
git push origin gh-pages

Boom. It’s up there. Now you can show any­one your “Pink, blurry, per­son­ally branded 2048”. If you go to http://​chrisuehlinger.​com/​2048/​ you’ll see my ver­sion. I tried to write an AI that would beat the game. I did that be­cause I was bored one af­ter­noon, and now it’s part of my port­fo­lio, and I can bring it up on my iPhone in the middle of an in­ter­view.

So now you’ve got an easy way to pub­lish any­thing you do. But what would really help would be a cent­ral­ized site with a blog, and a port­fo­lio page, and other good­ies. I’ll cover that in my next post.

A few last goodies

You’re going to want a way to run your site on your com­puter, so you don’t need to push to Git­hub every time you want to check if somethings work­ing. I highly rec­comend the Node.​js mod­ule http-server. If you already have the Node pack­age man­ager npm, type this to in­stall the pack­age:

1

npm install -g http-server

Then go to the dir­ect­ory where the HTML files are and type:

1

http-server -p 1234

Your web­site should now ap­pear at http://localhost:1234. Any­time you change something, just re­fresh the page and you’ll see the change.

I also HIGHLY rec­comend the node app called ungit. It’s a GUI that makes it much easier to use git. To in­stall it, type:

1

npm install -g ungit

Go to the dir­ect­ory where your re­pos­it­ory is and type:

1

ungit

Now vis­it­ing http://localhost:9000 will show you the app.

This is a con­tinu­ation of my post on get­ting your per­sonal space on the web set up.

• Part 1: Setting up a Github Project Page
• Part 2: Setting up an Octopress site for you blog and portfolio

So at this point, you should be able to visit {yourname}.github.io/HelloWeb or {yourname}.github.io/2048 and see the pages you made. But what if you visit plain old {yourname}.github.io? You get a 404 error. We need to get you set up with a github.io re­pos­it­ory and a Je­kyll static site.

This is going to get a bit more in depth, but stick around and you’ll have a really solid per­sonal port­fo­lio.

A refresher on Github Pages

So, Git­hub Pages lets you up­load static pages that get served up from your github.io sub­do­main. One thing I didn’t cover, is that if you make a re­pos­it­ory called {yourname}.github.io and push it to Git­hub, they will ma­gic­ally take whatever is in there and serve it up at your site.

If you have a file in this re­pos­it­ory called index.html that file now be dis­played if you go to {yourname}.github.io (it has to be in the master branch, which is the de­fault one, NOT the gh-pages branch). If you have a file called about.html, it will be vis­ible at {yourname}.github.io/about.html. If you have folder called contact that con­tains a file called index.html, it will be vis­ible at {yourname}.github.io/contact/.

But we can do a bit bet­ter than just plain old HTML, and that’s where Je­kyll comes in.

Let’s talk about Jekyll

Static pages sound cool, until you start to miss a lot of the cool things you get with dy­namic web­sites:

• What if you want the same header on every page?
• What if you want to tag and categorize your blog posts, or have their URLs be in /year/month/day format?
• What if you want the ability to swap out themes?
• What if you want to write your posts in easy to read/write Markdown, instead of verbose, annoying HTML?

For­tu­nately, there’s Je­kyll, a static site gen­er­ator that gives you a lot of this stuff. You can read about it here.

I was really con­fused when I first heard of Je­kyll, so here’s a quick run­down of how it works:

1. You download some ruby tools
2. You make a directory full of templates
3. You make some pages (using either html or markdown)
4. Jekyll “compiles” everything together, slotting all your pages into the templates (so they all have the same header, or whatever) and arranging the posts in your _posts directory so that their URLs will correspond to the dates when they were posted.
5. It puts this compiled site into the _site directory

Even bet­ter, when you do a git push, Git­hub will handle steps 4-5 on their own and will serve up the _site dir­ect­ory auto­mat­ic­ally.

But be­fore you go ra­cing after Je­kyll, I want to stop you (for bet­ter or worse) from mak­ing the same mis­take I did.

Octopress

So as you start learn­ing about a lot of cool web tech­no­lo­gies, your Je­kyll con­fig­ur­a­tion will get more and more com­plic­ated.

Let’s say you want to use Sass in­stead of plain old CSS, or you want to use Haml in­stead of HTML? What if you have a Grunt work­flow that does all kinds of crazy stuff to your javas­cript every time you save?

Well, Je­kyll has tons of plu­gins to ac­co­mod­ate for a lot of this stuff, but un­for­tu­na­tel Git­hub will only run a few cer­tain plu­gins with their auto­matic Je­kyll thing. They’ve got­ten bet­ter about sup­port­ing Sass and Cof­feescript, but there’s no guar­untee they’ll ever have all the things you need.

But wait… what if you wrote your site in one branch, com­piled it with Je­kyll using all the plu­gins you want, switched back to the mas­ter branch and se­lect­ively copied over the _site dir­ect­ory to the master root dir­ect­ory then pushed to Git­hub?

If you were as con­fused and re­vol­ted by that last sen­tence as I was, you’ll be glad that the Oc­to­press guys have figured this all out for us. The truth is, if you stick with Je­kyll and don’t use Oc­to­press, you’ll end up mak­ing it your­self (and if you’re like me, it won’t be nearly as well thought out).

Al­right, we’ve covered a lot of ground without cod­ing any­thing. That bugs me. Let’s get to work.

Setting up your environment

You may have done some of this stuff be­fore, this is just to make sure you’re on track.

So I’m work­ing on a Ret­ina Mac­Book Pro; these in­struc­tions will be tailored to Mac OS X users.

First, get homebrew up and run­ning. homebrew is ba­sic­ally the pack­age man­ager that con­tains all the other pack­age man­agers. It al­lows you to keep all your pro­gram­ming re­lated stuff or­gan­ized and up to date. Get­ting it set up is a bit of a task, so I’ll let the homebrew guys them­selves ex­plain it.

Once you have homebrew, use it to grab a bunch of im­port­ant things:

1
2
3
4

brew install git
brew install ruby
brew install rbenv
brew install node

git is a ver­sion con­trol sys­tem that helps you or­gan­ize your code.

Ruby is a pro­gram­ming lan­guage that has a bunch of use­ful tools we’re going to use. We won’t ac­tu­ally be writ­ing any Ruby code today. Ruby comes with gem, a pack­age man­ager for stuff that’s made using ruby. rbenv is a tool that let’s you keep track of which ver­sion of Ruby you want to use in which folder (this may seem overkill, but we need rbenv in order to in­stall Oc­to­press).

Node.​js is a frame­work for mak­ing things with javas­cript. The Node pack­age man­ager is called npm, and has lots of good javas­cript re­lated stuff.

Now that you have ruby and gem, let’s grab a bunch of other things we’ll need:

1
2

gem install bundler
gem install jekyll

Bund­ler is a spe­cial ruby pack­age in­staller (I’m not sure why ruby needs a pack­age man­ager AND an in­staller… there’s a joke about ruby pack­ages and light­bulbs in here some­where) and Je­kyll is needed so you can com­pile Je­kyll sites loc­ally on your com­puter.

Setting up your github.io project

So I’d rec­comend start­ing with the Oc­to­press doc­u­ment­a­tion, this is a little com­plic­ated.

• Getting Started will show you how to download octopress
• Deploying Octopress is about hooking up Octopress to your github.io repository. They also cover setting up a custom domain (like chrisuehlinger.com).
• Configuring your blog describes different ways you can configure your blog. You should get around to this at some point.
• Blogging Basics covers how to create new posts or new stand-alone pages. For reference, what you’re reading right now is a “post”. If you click the “About” link in my header, it will take you to a “page”.

Once you’re all set up, check out some of the Oc­to­press themes avail­able. In my opin­ion, too many people stick with the de­fault theme. Right now I’m using a mod­i­fied ver­sion of the mnm­l­press theme, al­though that may change by the time you read this.

Prepare for being famous

Chances are good you won’t be­come fam­ous. Sorry.

However, once you share something on the web, you never know when someone might ran­domly see it, post it on so­cial media site, and drive thou­sands of people to your site over the course of a day or so. If you haven’t done your pre­par­a­tion, you won’t even know that this happened. If you’ve prop­erly pre­pared, this op­por­tun­ity could net you a new job, a bajil­l­ion twit­ter fol­low­ers or even just a bunch of people say­ing “Thanks”.

You want people to be able to eas­ily con­tact you if they like your stuff. Eas­ily is an un­der­state­ment. The very IN­STANT their brain chem­ic­als form into “like” con­fig­ur­a­tion, they should be able to con­tact you with 0 ef­fort. You don’t need a float­ing “so­cial media ice­berg” on the side of your page, but you should def­in­itely have:

• A “Contact” page that can be accessed from your header, with your email, Twitter handle and Github account
• A “You can follow me on Twitter” link at the bottom of every post. (Even if you aren’t hugely into Twitter, a lot of people will be sharing your stuff through it, so I’d advise you to get one)
• Disqus comments enabled so people can give feedback.

Set up Dis­qus and put your Dis­qus ID in your _config.yml file. Oc­to­press will add Dis­qus com­ments to the bot­tom of your posts. It’s super easy, and often the most dir­ect way you can re­ceive feed­back.

Since you’ll no doubt have tons of pro­jects ac­cess­ible on your site, or­gan­iz­ing them into a “port­fo­lio” page and link­ing to that page in your header is also SO WISE.

Oc­to­press comes with Google Ana­lyt­ics bundled in. You should set up a Google Ana­lyt­ics ac­count, and put your Google Ana­lyt­ics ID in your _config.yml file. You should also make sure you in­clude the Google Ana­lyt­ics “magic javas­cript snip­pet” in EVERY HTML file in every pro­ject you post.

Do all this stuff NOW. Mak­ing stuff people like is hard enough, turn­ing those likes into men­ing­ful con­nec­tions doesn’t have to be.

Happy Trails!

Hope­fully you now have a per­sonal space on the web where you can post any­thing. You still have to make cool things, there’s no get­ting around that. But now:

• Random things you make on a lazy afternoon can instantly become part of your portfolio
• Simply by existing, this page is “passively promoting” you on the internet. Anyone who googles your name will hopefully end up here.

If you’re feel­ing un­in­spired, here are a bunch of the out­land­ish things you can do with just HTML, CSS and Javas­cript:

• The Web Audio API lets you make synthesizers, vocoders and DJ equipment using JS
• WebRTC is an amazing piece of technology that lets you make a video or audio chat client in the browser using just javascript
• Mike Bostock has tons of crazy visualizations he made using his D3.js library. All of these are on Github for you to play with.
• Hakim El Hattab always has tons of cool stuff to check out, a lot of it using CSS 3D transforms and WebGL.

I hope these art­icles have helped, good luck!