Tue 15 September 2015

Pelican and github pages - a quickstart

Posted by ankur in Tech (514 words, approximately a 3 minute read)

A really quick howto !

Set up a page

To create your github user page, head over to github and create two new repositories - and - as explained here. The src repository will hold the sources of your blog and the repository will contain the output html files that pelican generates. Since we're going to add the output directory as a submodule, initialise it with a readme - I can't seem to add a bare git repository as a submodule in a simple way.

Install Pelican

On Fedora, this is a very very simple command:

sudo dnf install python-pelican

If you aren't on a Fedora system, you'll have to install these packages another way, like with pip. I'd suggest using a virtualenv, but it's up to you:

virtualenv blog_virt
cd blog_virt
source bin/activate

pip install pelican ghp-import #then change to your git repository and continue

Set up the blog with pelican

Pelican provides an excellent quickstart command. Double check that you're working in the source git repository using:

git remote -v

Then, clone the output repository as a git submodule:

git submodule add output #replace the URL with the correct one.

Then, run:


It'll ask you various questions, just answer them. If you're using the latest version of Pelican, it'll ask you if you want to use github pages and so on.

Open the file and set the DELETE_OUTPUT_DIRECTORY variable to False. Otherwise, each time you publish, it deletes your submodule - we don't want that.


There are various tweaks and tips mentioned here that you should look at. One of the more handy ones is the addition of a newpost command in the Makefile.

First post

Write a quick post!!

Build, commit, push, and you're done!

Once done, you build your blog and check if everything is OK:

make html; make serve #creates a demo site and serves it on localhost:8000

This runs a local webserver on port 8000 - direct your browser there to see the results of your work! If everything is OK, generate the website, add your files, commit them, and push to your repositories:

make publish #creates the complete site

# Commit to the output submodule first
cd output
git add .
git commit -m "First post."
git push -u origin master

# The commit the source repository
cd ..
echo '*.pyc' >> .gitignore #don't need pyc files
git add .
git commit -m "First commit."
git push -u origin master
# Sources committed

That's all! Head over the and see the new site you've just created!

Caveats and customisations

Everything can be pretty much customised in Pelican. To start with, there are a set of themes that you can choose from. On top of that, you even have a set of plug-ins that help you add various functionalities to your site. Of course, you can write your own or customise existing plugins and themes.

There's a tool called ghp-pages that the pelican documentation refers to, but as of Pelican 3.6.3 which Fedora 22 features, the tool doesn't work as described in the documentation. It's why I used the submodule method.