A nerd pretending to be a software engineer.

Setting Up My GitHub Pages

Written on

Previously, I had been hosting this site on Heroku. It was pretty simple to setup, I can just create an index.php file, then add another .htaccess file to the root of the site, push, and done. In this case, I maintained two separate repositories, one that contains the Pelican project, including the configuration file, the build script, etc. The other repositories contains the generated HTML files.

Now, I recently wanted to try hosting the site on GitHub Pages. Hosting on GitHub pages requires the content of my site to be in the root of gh-pages branch. Of course, this would be simple enough if I just keep the project files and the generated HTML files in separate repositories just like I did before, but I would like to keep them in the same repository, and have a build script to do everything for me.

Turns out, it is not that simple to achieve that. The most straightforward way to do this is to create or checkout the gh-pages branch, generate the HTML files on the same directory, commit, and push as usual. But this would make the gh-pages branch contains some of the project files. Not a big problem, but it just doesn’t feel too clean of a solution. I also tried other methods, but none of them feels satisfactory. Ideally, I wanted to have a solution similar what was done with ghp-import, but there are some problems that prevents me from using it. I tried looking at the source of the project, in attempting to understand how it works and try to do the same things manually, but well, it seems like my Git-fu are insufficient to understand it. In the end, ended up doing the things similar as what outlined here. Basially, I am keeping the branches of the same repository in separate directories, but instead of keeping the as a siblings, I made the gh-pages branch as a child of the child directory of the project. Here is the fabric file I used to build the post:

from fabric.api import *
import configurations as conf

output_dir = conf.OUTPUT_PATH
remote_git = ''
activate = 'env\\Scripts\\activate.bat'

def init():
    local('mkdir {0}'.format(output_dir))
    with lcd(output_dir):
        local('git clone -b gh-pages {0} .'.format(remote_git))

def update(commit_msg='update'):
    local('git add -A')
    local('git commit -m "{0}"'.format(commit_msg))
    local('git push origin master')
    local('git push bitbucket master')

def pub(commit_msg='Post update'):
    # Update master branch
    local('git add -A')
    local('git commit -m "{0}"'.format(commit_msg))
    local('git push origin master')
    local('git push bitbucket master')
    # Generate posts
    with prefix(activate):
        local('pelican -s -v')
    # Update gh-pages branch
    with lcd('output'):
        local('git add -A')
        local('git commit -m "{0}"'.format(commit_msg))
        local('git push origin gh-pages')

That seems to work pretty cleanly so far. One problem is when creating a new project and its gh-pages branch for the first time. In my case, I dealt with it by creating the a new branch as usual, and then deleting the project files in the gh-pages branch manually, but I think it can be done by creating an orphan page with the git checkout --orphan gh-pages command as well. Anyway, this needs to be done only once, so it shouldn’t be too much of a problem.

comments powered by Disqus