Host a blog on GitHub Pages

Last modified on 2016-12-30

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 "USERNAME"                                  
git config --global                        
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 …


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
git add
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
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 PagesUser 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

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

Next I edit 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 and for to redirect to the www address.

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

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!