I build software with Python, Django, ReactJS & React-Native. Every day. All day long.

Blogging with Pelican and GitHub

Note: This Post is Outdated. Link to new post is in the text.

While it took me indeed just four lines of code and thirty minutes to setup the first version of this blog, I couldn't resist to geek over it for a few more hours and create a nice and clean approach to publishing this blog with Fabric, Pelican and GitHub.

IMPORTANT: This post is outdated. Please see my new post about blogging with Pelican

What to expect

When you follow these instructions, you can expect the following:

  • A simple static blog website with a simple yet beautiful theme.
  • Possibility to change any aspect of the site as you wish.
  • Writing your blog posts in the editor of your choice with Markdown.
  • All your content is under version control on GitHub. This means that people can send you pull requests and suggest improvements to your posts, which is just awesome.
  • Publishing your posts by simply calling fab publish:'Commit message'.
  • Free hosting on GitHub. I guess you don't need to worry to make it to the front page of Hacker News.

I should mention that Pelican is a Python project and therefore it wouldn't hurt if you knew a bit about Python. I will assume basic Python knowledge here. Let's get started:

Activate GitHub Pages

Just create a new repository called username.github.com. Whatever you place in here will be served at http://username.github.com. For more information please see the GitHub Pages Documentation.

Setup your repository

First create a folder on your disk for the new project:

1
2
mkdir $HOME/Projects/myblog
cd $HOME/Projects/myblog

Next setup your source folder. This is the folder where you will write your articles and call pelican to generate your static html output:

1
2
3
4
5
6
7
mkdir source
cd source

# We will steal some files from my own repo here:
wget https://github.com/mbrochh/mbrochh.github.com/raw/master/source/requirements.txt
wget https://github.com/mbrochh/mbrochh.github.com/raw/master/source/fabfile.py
wget https://github.com/mbrochh/mbrochh.github.com/raw/master/source/settings.py.sample settings.py

The sample settings.py you just got from my own repo will need some changes now. Have a look at it and edit it so that it fits your needs.

Setup your virtualenv

If you have never used virtualenv and virtualenvwrapper before, now is the time to learn about it. Usually this is what you need to do to install it:

1
2
3
4
5
6
sudo easy_install pip
sudo pip install virtualenv
sudo pip install virtualenvwrapper
export WORKON_HOME=~/Envs
source /usr/local/bin/virtualenvwrapper.sh
# also add export WORKON_HOME=~/Envs to your .bashrc file

We will use virtualenv to install fabric and pelican:

1
2
3
mkvirtualenv -p python2.7 blog
workon blog
pip install -r requirements.txt

Create your first post

Now is the time to create your first post:

1
2
3
4
5
# make sure to be in the source/ folder
mkdir -p posts/2012/02/  # insert appropriate year and month here
cd posts/2012/02/
touch hello-world.md
nano hello-world.md

To learn more about how to write your articles with Markdown or reStructuredText for Pelican, have a look at writing articles using pelican.

Your article should look similar to this:

1
2
3
4
5
6
Date: 2012-02-20
Title: Hello world
Category: Blog
Tags: blogging, test

Lorem ipsum

I like to create meaningful commit messages for the edits of my .md files and separate them from the changes that the Pelican output generates, therefore now it is a good time to create a commit:

1
2
git add .
git commit -am "Created my first post."

Publish your first post

This is the interesting part! You will use Pelican now to generate the output for your blog:

1
2
3
# make sure to be in the source/ folder
pelican . -o ../ -s settings.py
git status

When you run git status you will see that Pelican generated a whole bunch of files in your root directory. Open your index.html and have a look at your new blog.

If you see that something went wrong, you might want to destroy the generated output:

1
2
3
# make sure to be in the root folder and be sure that your .md file changes
# have been committed
git clean -df

Now you can edit your .md files again and generate the output again. If you are happy with your output, it is time to publish it:

1
2
3
4
# make sure to be in the root folder
git add .
git commit -am "Pelican output"
git push origin master

Publishing with fabric

As you have seen, the workflow of editing your posts is always the same. First you edit your .md files, next you commit your changes and give a meaningful commit message and at last you generate the output and commit it with a standard commit message. Finally you push to Github which will make your changes visible.

To make this workflow easier, I have created a little Fabric script. Now you can just edit your .md files and once you are done, call Fabric:

1
fab publish:'My commit message'

Setting up a custom domain

As if all this isn't awesome enough, GitHub makes it really easy to create custom domains for your GitHub page. All you need is to place a file called CNAME in the root of your project and add the following content:

1
yourdomain.com

Then point the A record of your domain to the IP address of GitHub. For more information have a look at the instructions about custom domains on GitHub.

How to embed images?

If you need to embed images, you can just add them to the folder source/images/ and link to them in your .md files like so: ![Alt text](./static/images/yourimage.png).

Thanks!

That's it. I hope I didn't forget anything. I would like to thank Alexis Metaireau for the great work on Pelican. There is a small and friendly group sitting at #pelican on Freenode and while I was writing this post, I submitted a pull request to Pelican which got merged almost immediately. The project is really worth a closer look!

 
comments powered by Disqus