How to use Pelican on GitHub Pages

Install on Ubuntu

Installing Python tools

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

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

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

Load file .bashrc

source ~/.bashrc

Create virtualenv with virtualenvwrapper

mkvirtualenv blog
workon blog

And to leave

deactivate

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 user.github.com/blog. If you want to set a custom domain see link: Setting up a custom domain with Pages

Steps to publish a post

In parenthesis is the git branch we are working on:

(master) Create the post in rst or md (rst and md are abbreviations for resTructuredText and markdown)
(master) Generate the HTML
(master) Check the post in a local server
(master) We could delete the output but dones't matter if we don't because git will ignore with our gitignore file
(gh-pages) Merge master branch
(gh-pages) Generate the HTML
(gh-pages) push all the files (normally all the new HTML)
(master) push all the files (normally only one post)

Clone git repository

git clone [email protected]:user/blog.git
cd blog

Create in the root folder a file .gitignore

vi .gitignore

#Custom
output

#Python
*.py[cod]

# C extensions
*.so

# Packages
*.egg
*.egg-info
dist
build
eggs
parts
bin
var
sdist
develop-eggs
.installed.cfg
lib
lib64

# Installer logs
pip-log.txt

# Unit test / coverage reports
.coverage
.tox
nosetests.xml

# Translations
*.mo

# Mr Developer
.mr.developer.cfg
.project
.pydevproject

Download Themes

Clone pelican-themes repository

git clone --recursive https://github.com/getpelican/pelican-themes themes

Create Pelican settings file

Create settings file called settings.py from sample pelican.conf.py

wget -O settings.py https://raw.github.com/getpelican/pelican/master/samples/pelican.conf.py

Add this variables

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

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 settings.py

# Custom Home page
DIRECT_TEMPLATES = (('index', 'blog', 'tags', 'categories', 'archives'))
PAGINATED_DIRECT_TEMPLATES = (('blog',))
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>
</div>
{% endblock %}

Creating post

mkdir -p src/posts/2013/07
vi src/posts/2013/07/welcome-all.md

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 settings.py

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 settings.py -o /tmp/blog

Issues

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

We start the process in the master branch:

git add .
git commit -m "First post: Welcome All"

Push it to master (remember, this doesn't deploy the page, this is our source):

git push origin master

If we havent the gh-pages branch we create:

git branch gh-pages

Change to gh-pages and merge the master branch:

git checkout gh-pages
git merge master

Now generate the HTML. But wait! github doesn't know that our webpage is in output dir, so we need to put our generated HTML in the root of the project, to do that we replace the settings outputdir in the command:

pelican -s local_settings.py -o ./

We are ready to deploy, commit all and push:

git add .
git commit -m "Publish Welcome All post"
git push origin gh-pages

We change again to our master branch and we are done :):

git checkout master

Point your browser to you.github.com/blog , Awesome!!!

zunction/how-to-use-pelican.md