We already discussed in a previous post how easy it is to create, publish and mantain a repository hosted on github.com by only using Mercurial and TortoiseHG without additional software – including Git. Here we’ll go a step further and illustrate how to adopt the same method to set up additional branches, including the gh-pages branch used by GitHub website to handle one of its most useful feature: the project pages.
Introducing GitHub Pages
Chances are that you already know what a GitHub page is: if not, start with reading the official guide. GitHub pages are essentially static web pages hosted on GitHub servers to publish your account or project related stuff. There are basically two types of GitHub pages:
- Project Pages: these are pages bound to a specific GitHub project. You can either create them manually by using the Git command-line or automatically by using the automated page generator software service powered by GitHub. In both cases you’ll end up adding a new branch to your repo, namely gh-pages, where you will be able to put one or more web pages that will be openly accessible through the following URL: http(s)://<username>.github.io/<projectname> . You can use these pages to create a website for your project: description, usage instructions, how-tos, demo, examples, documentation, APIs, and so on.
Just a quick word regarding User & Organization Pages: we won’t be talking about these. As a matter of fact we already did that, since they use the master branch of their own dedicated repository you can already manage sticking to what we already wrote in our previous post. This post is focused around Project Pages, which require us to create a specific gh-pages branch: let’s see how to handle this.
Create Project Pages using the Automatic Page Generator
The most simple way to achieve our goal is by using the Automatic Page Generator powered by GitHub. Open your project URL on GitHub and go to the Settings page:
Click to the Automatic Page Generator button in the lower-right corner.
Author your content in the Markdown editor and click on Continue when done. Preview your content using the free themes offered by GitHub and click on Publish Page when ready. The gh-pages branch will be added to your repository.
Create Project Pages manually
If you prefer to use the command-line, you can add the gh-pages using Mercurial or Git in the following way:
hg clone git+https://github.com/Darkseal/my.hggit.project.git
hg rm -f .
echo "Home Page" > index.html
hg add index.html
hg bookmark gh-pages
hg commit -m "First pages commit"
hg push origin -B gh-pages
git clone github.com/Darkseal/my.hggit.repository.git
git checkout --orphan gh-pages
git rm -rf .
echo "Home Page" > index.html
git add index.html
git commit -a -m "First pages commit"
git push origin gh-pages
For a full reference guide on each step we suggest reading the official GitHub documentation.
After completing the aforementioned task of your choice you should’ve been able to add the gh-pages to your remote GitHub repository. Now you just need to synchronize it to your local Mercurial repository on your hard-disk drive: you can do that using the same approach we wrote in our previous post. Open the contextual menu by clicking the right mouse button over your project’s folder and launch the Synchronize command. Type in (twice if needed) your GitHub credentials and you’re done!
If you want to track your results, launch the TortoiseHG workbench and look to your local repository info:
You should see a couple bookmarks like those shown in the screenshots: master and gh-pages, each one corresponding to the GitHub branch with the same name: that’s good, since they serve the same purpose. You can change your bookmark at any time with an hg update from the command-line or using the TortoiseHG contextual options.
Just remember to use the master bookmark when you need to work on your project files, and switch to the hg-pages bookmark when you feel like working on its Project Pages.