Skip to content

24 ways to impress your friends

Get Started With GitHub Pages (Plus Bonus Jekyll)


Comments are ordered by helpfulness, as indicated by you. Help us pick out the gems and discourage asshattery by voting on notable comments.

Got something to add? You can leave a comment below.

Patrick Grey

Good article, thanks.

It is always good to understand the basics before using framework tools but once you are up and running, it may be worth looking into and the Jekyll generator

It will scaffold out your Jekyll site and also livereload your page when you save files (saving that trip to F5) and optimise your build when you are ready to push to github. It has improved my workflow greatly. It can take some effort to set up but even I got it running on Windows, and I’m an idiot! :-)



I am excited to try Jekyll. Working on this tutorial now. I have successfully installed Jekyll and installed the documents into an orphan git branch. I have “Jekyll serve —watch” running. I can see Jekyll updating in the terminal whenever I make a change in the folder.

Where I am stuck is that http://localhost:4000/ is not found in my browser. I get `/’ not found. I’m searching for a way to get it working and navigate to my project folder via localhost:4000/

Any pointers at this juncture would be appreciated.


Great article!
On a side note, there is an amazing Yeoman generator for Jekyll pages by Rob Wierzbowski, makes building Jekyll sites a breeze.

Paul Mist

Great article, Anna – thank you.

I like Jekyll, but one thing I’d love to find a solution to is stopping Jekyll from rebuild the entire site every time there’s a change.

I understand why it does this, but wish there was a way to override it.

Happy Christmas!


I think the documents on Github and JekyII sucks, I can’t setup my blog from those docs, I need to try a lot to see if it works in this way or the other .

This is a good one, :)


@sudo@ should never be necessary. Once you go @sudo@, you can’t go back. Better to @chown@ everything to yourself, so you never need @sudo@.


Great post and very timely for me. I’ve moved away from WordPress for my personal site and thought I’d give Jekyll/GitHub pages a go.

Getting Jekyll set up and working locally felt like torture. I have an irrational fear of the command line and this seemed like the only way to install it.

After many tears, installations of the latest version of Ruby, Sudo, command line tools in Xcode, JSON and rdiscount I started to wonder why the hell I bothered!

I stuck with it and got through the other side will all my limbs and my sanity intact. I’d say the hassle of initial setup is well worth it.

I’ve got loads more to learn and explore but it feels so nice not having to tip-toe around PHP snippets to build webpages.

Do it today Dessy!


I make a service that is similar to GitHub pages, but without the git portion. It relies on Dropbox, so you just save files (or generate from Jekyll) in Dropbox, and it goes live. It’s called We use a similar approach described here to manage our own blog:, and it works well for us.


Unfortunately this tutorial needs an editor’s note or an update..
People looking to use Jekyll with Github should refer directly to

Otherwise hours down the drain :*(

Alex Weissman

Wow, this is exactly what I was looking for. I’ve been trying to build a website using github pages but I got stuck on the problem of including headers and footers. Thanks so much for spelling it all out.


Thanks for the article. I’d reached my limit with Wordpress after my site was hacked ( again ). Plus I prefer working with HTML, CSS and JS directly, not via PHP, so I was genuinely excited to learn about github pages last week, and have just started building my site there.

I’m experimenting with using Google Spreadsheets combined with TableTop.js to power my blogs. I can write blog entries in markdown in a spreadsheet and use TableTop to read them. I like the potential and flexibility – something of a test for now.

Ed Henderson

Nice writeup. I wish it existed when I first worked this all out. Maybe beyond the scope of this article but if you are throwing recipes onto the Internet you can mark them up super nicely with Microdata / Rich Snippets. Check out:


I implemented them recently at work and it proved to be quite easy but allows you to be a bit more prominent in the Search Engines.


Harry Moreno

Cool I wish I read this when I made mine. I used bootstrap as well the source is here I just push to master and it works for me. Don’t know why you had to change the default.


Really, really well made article and easy to follow.

I had trouble with installing Jekyll though, because of the librari nikigiri (or something like that). I installed homebrew, and then I needed to change the permissions on /usr/local to my current user, unlink the libdiv (or something like that) library and upgrade it. Then, it finally worked.

Also, I needed to restart Jekyll after I changed the .yml configuration of the sub-folder for the site, or else it wouldn’t work.

And, the folder _includes already existed and contained header.html, head.html and footer.html. I deleted them to create the file you mentioned.

But, again, really well written and easy to follow tutorial. I’ll keep it as an example for my own blog! :) Congrats Anna!


Nice post! I’ll give it a try!

At least I need a little php for a comment system and a contact form. Perhaps services like Disqus can provide a comment system in a github-page. But how to handle a contact form? Any ideas?


If you use

gem install jekyll -V

then you get more feedback on the installation process, and it won’t look like it’s stuck…

Impress us

Be friendly / use Textile