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
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
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 masterre-populates your project folder with your project contents
git checkout gh-pagesbrings 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
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.