Skip to Content

Host a blog on GitHub Pages

Posted on

GitHub Pages is a free web hosting service for projects composed of static files (i.e no database). Combine a Pages repository with git version control and a static site generator like Pelican and you have one awesome toolset to build a website.

This is how I configured GitHub Pages to host my blog.

0. Install git

Debian: Install git package and write global configuration variables for USERNAME in ~/.gitconfig …

sudo apt install git git-doc                                          
git config --global user.name "USERNAME"                                  
git config --global user.email USERNAME.EMAIL@example.com                        
git config --global core.editor EDITOR  # I use 'vim'                                     
git config --global merge.tool vimdiff

1. Create git repository

Inside my pelican-powered blog project I create 2 new files: .gitignore and README.rst.

The .gitignore file does exactly what the name implies … it instructs git which files and directories not to bother tracking in version control. For example I do not want to track …

*.pid
*.pyc
output/

For GitHub: Create a README.rst and GitHub will auto-detect and configure it as the project homepage when blog contents are uploaded to the remote repository.

Now I create my local repository, add the items I want to track, and execute my first commit …

git init                                                                      
git add README.rst                                                            
git add .gitignore
git add Makefile
git add content/
git add pelicanconf.py
git add publishconf.py
git status                                                                    
git commit -a -m "first commit"  # '-a' adds all files that are being tracked and commits them 
git log  # to view commit history

2. Create GitHub repository

Sign up for a free account on GitHub and create a new empty repository to hold the blog contents.

Next I connect my local .git repository to my GitHub remote repository …

git remote add origin https://github.com/vonbrownie/circuidipity.git
git remote -v  # confirm local knows about remote 
git push -u origin master

3. Configure Pelican to use GitHub Pages

GitHub offers 2 types of Pages … User Pages and Project Pages. Each GitHub account can host a single User Page and an unlimited amount of Project Pages. Basically they are identical to the end-user and differ only in their configuration.

I chose to make my blog a Project Page and the contents are hosted in the gh-pages branch of my GitHub project repository. Pelican makes it easy to create and configure gh-pages using the ghp-import Python script … which I install via pip …

pip install ghp-import

Finally I publish my blog by pushing the files up to GitHub …

make github

GitHub Pages is now hosting the site at http://USERNAME.github.io/REPOSITORY.

4. Custom domain name

Awesome! But I want to use my own custom domain name … not REPOSITORY.

GitHub enables custom domains by allowing users to create a CNAME file with their domain address that resides in the root directory of gh-pages. Inside my Pelican project folder I create a new extra directory containing a single-line CNAME file with my domain address www.circuidipity.com.

Next I edit pelicanconf.py to recognize CNAME and place the file in gh-pages when I upload my files …

# Static paths will be copied without parsing their contents                    
STATIC_PATHS = ['images', 'extra']                                              
                                                                                
# Shift the installed location of a file                                        
EXTRA_PATH_METADATA = {                                                         
    'extra/CNAME': {'path': 'CNAME'},                                       
}

Upload my changes to GitHub …

make github

4.1 Domain Registrar

Now the domain name registrar needs to be configured to point to the new GitHub address. Gandi is my registrar and while the details will vary between domain services the steps are basically the same to redirect a custom domain.

My objective is for the GitHub Pages repository to resolve to www.circuidipity.com and for circuidipity.com to redirect to the www address.

Using Gandi as an example I will create new CNAME and A records:

  • click on domain name to access admin page and near the bottom select option Edit the zone
  • create new zone file for editing by selecting Create a new version
  • modify/add CNAME www record with value USERNAME.github.io.
  • modify/add A record to permanently redirect the top level domain to www using the Gandi redirect service address 217.70.184.38
  • click Use this version to save all changes and wait a few hours for the DNS modifications to propagate around the world

It is possible to skip web redirection and set the A record value to point directly to a GitHub address but at the loss of dynamic traffic management.

5. Custom 404

Configuring a custom domain allows the option of using a custom 404 page. Simply create a 404.html file in the gh-pages root.

Happy hacking!