Github project website

This is nothing new, but apparently not many Github users know about this feature and I’ve recently learnt an easy way to set it up.

But let’s step back for a second: what are Github pages?

it’s a web space granted to each Github user and project where you can publish anything related to the subject: users might decide to publish their curriculum/resume or contact information while a project might publish a nice looking documentation.

A good set of information is available via a mini site which already guides you through the setup process, so I’m not going to reproduce that here.

Briefly, for a project site, the site contents are going to be hosted withing the project git repository (it does make a lot of sense to me) whitin a dedicated branch gh-pages.

What I wish to share is the set of git commands you can use to setup an existing project to host a clean Github pages setup.

Within the project folder you want to run:

git checkout --orphan gh-pages
git reset
touch .gitignore
git add .gitignore
git commit -m "gh-pages setup"
git push -u --all

You will end up with an almost empty folder (don’t panic, your project is not gone!) apart for the empty .gitignore file.

The project is now displaying what is published on your project’s Github pages, which is nothing at start. You can easily switch between the project contents and the project website by using the git checkout command:

  • git checkout master re-populates your project folder with your project contents
  • git checkout gh-pages brings you back to project website editing

The nice part of the above sequence is the newly created gh-pages branch is not going to share anything with your code branch structure or, if you prefer, master is not a parent for gh-pages!

You can now populate the website with your content using your HTML5 or MarkDown skills, or you can use one of the readily available templates from Github to get a nice looking index.html page to start from.

Also, additional and advanced features are available for multi-page websites via Jekill, but that’s another story.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s