Setup a free static blog with Pelican hosted on Github User Pages

ven. 09 juin 2017 by Mick Cherry

The association of Pelican and Github Pages allows for an (almost) easy setup and free-hosted static blog.

There are several Github Pages types. The one I chose to use is names User Pages.

The main steps to setup a new blog are:

  • Install the dev environnment (editor, Pelican generator, tool for easy Github Pages integration, ...)
  • Create and setup the Github Pages git repository
  • Create and configure the empty Pelican blog
  • Setup the workflow (new post, publish)

Most of this setup has been ~~forced~~ advised to me by @MoAdiBFr :D

Install the development environnment

Check that you have python installed

$ python --version
Python 2.7.13

Get pip if you do not have it installed yet

$ wget https://bootstrap.pypa.io/get-pip.py
$ sudo python get-pip.py
$ rm get-pip.py
$ pip install -U pip

Get Pelican, Markdown and ghp-import (a tool for commiting the output folder to the proper branch, see below)

sudo pip install pelican
sudo pip install markdown
sudo pip install ghp-import

Get an editor (I use vim or Sublime Text).

Here are the steps to get Sublime Text:

$ wget -qO - https://download.sublimetext.com/sublimehq-pub.gpg | sudo apt-key add -
$ echo "deb https://download.sublimetext.com/ apt/stable/" | sudo tee /etc/apt/sources.list.d/sublime-text.list
$ sudo apt-get update
$ sudo apt-get install sublime-text
$ subl

Get Sublime Text Package Control

wget -P /home/etienne/.config/sublime-text-3/Installed Packages https://packagecontrol.io/Package%20Control.sublime-package

You can now install Sublime Text packages (like MarkdownPreview or MarkdownExtended) that will prove useful for editing the blog posts.

Setup the git repository

In order for a Github User Pages website to be properly served, it needs to resides on the master branch of a special repository that you must name username.github.io (here, username means your Github username). This job will be done by the ghp-import tool.

We still need a way to track and save the actual blog sources. Some people create two repositories, one for the generated content, and one for the source files.

Here, we are going to use a solution that only uses one repository (the username.github.io mandatory repo for Github User Pages) and two branches of it.

You can read Pelican tips for more details.

Start by creating a new repository on Github with the exact name username.github.io where you replace the username part with your own Github username. Do not add a README file or a .gitignore file when Github asks you about it.

# Make sure you already created the repository on Github
$ git clone git@github.com:username/username.github.io.git blog
Cloning into 'blog'...
warning: You appear to have cloned an empty repository.
$ cd blog

Create the Pelican blog

To create your blog, go to your blog folder and follow the steps from pelican-quickstart

$ cd blog
$ pelican-quickstart 
Welcome to pelican-quickstart v3.7.1.

This script will help you create a new Pelican-based website.

Please answer the following questions so this script can generate the files
needed by Pelican.


> Where do you want to create your new web site? [.] 
> What will be the title of this web site? Mick Cherry\'s Serious Series
> Who will be the author of this web site? Mich Cherry
> What will be the default language of this web site? [en] 
> Do you want to specify a URL prefix? e.g., http://example.com   (Y/n) n
> Do you want to enable article pagination? (Y/n) 
> How many articles per page do you want? [10] 
> What is your time zone? [Europe/Paris] 
> Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n) 
> Do you want an auto-reload & simpleHTTP script to assist with theme and site development? (Y/n) 
> Do you want to upload your website using FTP? (y/N) n
> Do you want to upload your website using SSH? (y/N) n
> Do you want to upload your website using Dropbox? (y/N) n
> Do you want to upload your website using S3? (y/N) n
> Do you want to upload your website using Rackspace Cloud Files? (y/N) n
> Do you want to upload your website using GitHub Pages? (y/N) y
> Is this your personal page (username.github.io)? (y/N) y
Done. Your new project is available at /home/etienne/dev/blog

Nothing to add here except for the last question: answer yes in the case of a Github User Pages, no if this is project/organization Pages.

Now we generate the first (default) content to initialize the master branch

$ cd blog
$ make github
pelican /home/etienne/dev/blog/content -o /home/etienne/dev/blog/output -s /home/etienne/dev/blog/publishconf.py 
WARNING: Feeds generated without SITEURL set properly may not be valid
WARNING: No valid files found in content.
Done: Processed 0 articles, 0 drafts, 0 pages and 0 hidden pages in 0.04 seconds.
ghp-import -m "Generate Pelican site" -b master /home/etienne/dev/blog/output
git push origin master
Counting objects: 38, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (36/36), done.
Writing objects: 100% (38/38), 23.99 KiB | 0 bytes/s, done.
Total 38 (delta 5), reused 0 (delta 0)
remote: Resolving deltas: 100% (5/5), done.
To github.com:ecastanie/ecastanie.github.io.git
 * [new branch]      master -> master

The command make github generates the static default files to the output folder, commit and push them to the remote origin/master branch.

Now that the master branch is setup, we create a new branch named source (or anything else except master) which will contain the whole blog sources (Markdown posts, config files)

$ cd blog
$ git checkout -b source
$ git status
On branch source
Untracked files:
  (use "git add <file>..." to include in what will be committed)

        Makefile
        develop_server.sh
        fabfile.py
        output/
        pelicanconf.py
        pelicanconf.pyc
        publishconf.py
        publishconf.pyc

nothing added to commit but untracked files present (use "git add" to track)

This branch will be your working branch, and master will only be populated with the static generated content of the blog.

Create-Publish Workflow

Now that the git repository is created, the Github Pages activated, the empty blog created, it is time to write a first article and publish it!

Again, check that you are in the source branch (you should never have to checkout master again).

$ cd blog
$ git checkout source
$ echo "Title: First post yay!" > content/First-Post.md
$ echo "Date: 2020-04-09" >> content/First-Post.md
$ echo "Category: Noob" >> content/First-Post.md
$ echo "" >> content/First-Post.md
$ echo "First!" >> content/First-Post.md

In order to save and track the source files, we need to add/commit/push these files to the source branch.

Modify the Makefile target github in the following way:

$ tail Makefile 

github: publish
        git checkout source
        ghp-import -m "Generate Pelican site" -b $(GITHUB_PAGES_BRANCH) $(OUTPUTDIR)
        git push origin $(GITHUB_PAGES_BRANCH)
        git add .
        git commit -am "Update source files"
        git push origin source

...

Now just run make github to see your blog generated, its sources commited+pushed, and the output folder pushed to the master branch

$ cd blog
$ make github

Congratulations! You now have finished the setup and first post publishing of your own Pelican blog on Github Pages!