7/22/2013 - 11:55 AM

How to use Pelican on GitHub Pages

How to use Pelican on GitHub Pages

How to use Pelican on GitHub Pages

Author: Josef Jezek

Install on Ubuntu

Installing Python tools

sudo apt-get install python-setuptools
sudo easy_install pip
sudo pip install virtualenv virtualenvwrapper

vi ~/.bashrc (maybe is in other location, change if necessary)

# Virtualenvwrapper
export WORKON_HOME=$HOME/.virtualenvs
source /usr/local/bin/

Load file .bashrc

source ~/.bashrc

Create virtualenv with virtualenvwrapper

mkvirtualenv blog
workon blog

And to leave


Installing Pelican

sudo pip install pelican markdown ghp-import shovel

Upgrading Pelican

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

Creating a blog on GitHub Pages

We need to make a respository. For example blog, so our blog url will be If you want to set a custom domain see link: Setting up a custom domain with Pages

Prepare git

git config --global "John Doe"
git config --global
git config --global core.editor vi

Clone git repository

git clone
cd blog

Create in the root folder a file .gitignore

vi .gitignore



# C extensions

# Packages

# Installer logs

# Unit test / coverage reports

# Translations

# Mr Developer

Download Themes

Clone pelican-themes repository

git clone --recursive themes

Create Pelican settings file

Create settings file called from sample

wget -O

Add this variables

THEME = 'themes/bootstrap2'
OUTPUT_PATH = 'output'
PATH = 'content'

Period archives work best when the final path segment is index.html, see URL Settings

ARTICLE_URL = 'posts/{date:%Y}/{date:%m}/{slug}/'
ARTICLE_SAVE_AS = 'posts/{date:%Y}/{date:%m}/{slug}/index.html'

Custom Home page

Add this variables to

# Custom Home page
DIRECT_TEMPLATES = (('index', 'blog', 'tags', 'categories', 'archives'))
TEMPLATE_PAGES = {'home.html': 'index.html',}

Duplicated the index.html to blog.html in your template folder and add this lines:

{% set active_page = "blog" %}
{% block title %}{{ SITENAME }} - Blog{% endblock %}

Create home.html or use page override feature to use a Markdown page as your home page.

vi home.html

{% extends "base.html" %}
{% block content %}
<div class='page'>
  <div class="page-header"><h1>Home</h1></div>
  <div class="page-content">Content</div>
{% endblock %}

Creating post

mkdir -p content/posts/2013/07
vi content/posts/2013/07/
Title: Welcome All
Slug: welcome-all
Date: 2013-07-22 19:19
Category: Python
Tags: pelican, publishing
Author: Josef Jezek
Summary: Short version for index and feeds

This is the content of my blog post.

Generate blog

To generate the static html we use:

pelican -s

This will take all the settings and apply, but if we want to override some settings we could do. For example to specify the ouput we use -o:

pelican -s -o /tmp/blog


  • WARNING: LOCALE option doesn't contain a correct value see Ubuntu Locale

Then we have a new directory named output, our blog is there, so, to test it , insert there and run a simple server:

cd output
python -m SimpleHTTPServer 8000
# For Python 3
python -m http.server 8000

Point your browser to localhost:8000 and you will see the blog.

Deploying the blog

Point your browser to , Awesome!!!