Publishing a project website to Github Pages
I recently was faced with moving the website of one of my Github hosted projects from its current non-Github location to Github Pages.
At first glance publishing a project website to Github pages appears fiddly and error prone because you have to bounce between normal code branches and the Github Pages branch which have completely different files and directory structures. This is even trickier when your project’s build workflow also builds your web pages (as mine does).
I initially tried
git-subtree techniques for GitHub Pages deployment (see here, here and here) but found them brittle and arcane. Then I came across this Github Gist which neatly solved the problem viz. keep your code branches in one local repository and the
gh-pages branch in another. Locate the Github Pages repo on an ignored
gh-pages sub-directory of the local code branches repository.
- Both local repositories use the same remote Github repository: the local code repository contains code branches, the local website repository contains only the
- Typically the project build process generates the project website pages in HTML format which it copies to the local
gh-pagessub-directory (along with any other generated webpage assets).
- To publish the Github Pages repo:
- Change directory to the
- Commit the changes and push them to the
gh-pagesbranch at Github.
- Then cd back up to the project root and continue coding.
- Change directory to the
The steps to achive this are outlined below and were based on this Github Gist (the Gist assumes the
gh-pages branch already exists in the Github repo whereas my example does not).
Before starting it is assumed that:
- Your project code has already been published to Github.
- Your local project repository is up to date with the remote Github repo.
gh-pagesbranch has not yet been created either locally or remotely.
The following commands add a local repo in the
gh-pages sub-directory and then creates a
gh-pages branch which is pushed to Github (
<projectnames> refer to your Github user name and project name respectively):
# Go to local project code repository. $ cd myproject # Code repo ignores the documentation repo. $ echo gh-pages/ >> .gitignore # Make another repo in gh-pages sub-directory. # There is nothing magic about the sub-directory name, it can be anything you like. $ git clone https://github.com/<username>/<projectname>.git gh-pages # Create gh-pages branch and push it to Github. # See https://help.github.com/articles/creating-project-pages-manually/ $ cd gh-pages $ git checkout --orphan gh-pages $ git rm -rf . $ echo "Nothing to see yet, move along..." > index.html $ git add index.html $ git commit -am "First pages commit" $ git push origin gh-pages $ git branch -u origin/gh-pages # Track gh-pages branch on remote. $ git branch -D master # We don't need code branches. $ cd .. # Return to code repo.
The documentation can be viewed at
http://<username>.github.io/<projectname> (keep in mind that it can take up to 30 minutes for the web pages to appear at Github the first time after creating the
gh-pages remote branch).
If your project already has an existing
gh-pages branch the above can be reduced to:
$ cd <projectname> $ echo gh-pages/ >> .gitignore $ git clone --branch gh-pages https://github.com/<username>/<projectname>.git gh-pages
From here on you treat the local Github Pages repo just like any other Github repository except that when you push it to Gitub you use the
gh-pages branch name:
$ git push origin gh-pages
Here’s an example bash script that I use to automate deployment of the
On a side-note, you can use a custom domain name for your project’s Github Pages website by adding a
CNAME file to the
gh-pages branch – see the Github documentation for details.