Setting up Pelican

Writing a blog can be done in many ways, and there is lots of software available to help you set up the perfect blog for you. A popular piece of software is Wordpress, for which many themes and plugins are available. Together with a lot of information about it on the web to get you started. It’s pretty easy to use once it’s all set up and ready to go, from a user’s point of view.

A downside of Wordpress is that it is a bit more work to install and configure on your own. It is database-driven and is dynamic in nature, so requires MySQL and PHP. These add complexity when you want to host it yourself. This in turn requires you have to keep more software, including Wordpress itself, updated to remain as safe from exploits as possible.

Within the community of IT-minded people there seems to be a trend of moving to static pages. Those are simple, easy to host and also faster as a bonus! And they do not require you to run a database or set up PHP for your web server software. But does that mean you have to resort to writing your own HTML and stylesheets? Not at all!

Nowadays many generators exist for creating static sites. A popular choice seems to be Jekyll combined with Octopress, which calls itself “a blogging framework for hackers”. Sound pretty neat, but Ruby is not a language I’m fluent in, nor do I have it installed on my system. So not really my cup of tea.

Then I bumped into two others: Pelican and Felix Felicis (also called liquidluck). Both written in Python, which I can somewhat read, and have installed on my system already. Both can look great and seem to have a comparable feature-set. I’ve read that Felix Felicis seems to have faster page generation, but I haven’t really tested that myself. Felix Felicis seems to be a younger project, as I couldn’t find as many blogs made with it as I could find ones made using Pelican. The same goes for documentation on setting up and using the software. And as Pelican seemed to be able to satisfy my needs when it comes to a blog, I went with that.

Installing Pelican

Installing Pelican is not very difficult. But having experience working with packages and perhaps Python can come in handy. I’m not exactly a Python wizard myself, I can just read the language and fiddle with it from time to time. But if you do not know it at all, that’s not a problem either. For this HOWTO I will set up Pelican on my laptop, which runs Debian GNU/Linux Wheezy.

Requirements

Because Pelican is written in Python, it requires that to be present on the system. And to install Pelican itself you want to use the Python pip tool for installing/managing Python packages. Using easy_install is also supported and you could also download the source code and use that if you want. But using pip makes it really easy.

So let’s install pip:

$ sudo aptitude install python-pip

Substitude aptitude for your package manager. apt-get would also work here, I just happen to like aptitude.

virtualenv(wrapper)

The Pelican documentation recommends using a virtual environment for Pelican, and suggests virtualenv combined with virtualenvwrapper, so let’s listen to the wise devs and set it up.

We will install virtualenvwrapper using pip which will install virtualenv along with it as a dependency:

$ sudo pip install virtualenvwrapper

Once that’s done we need to make some changes to our environment so we are able to use virtualenvwrapper. We need to tell the shell to set a couple of variables and execute the virtualenvwrapper script on start. When you use Bash as your shell, the default on pretty much any GNU/Linux distribution, you should edit your .bashrc and add the following lines:

export WORKON_HOME=$HOME/.virtualenvs
export PROJECT_HOME=$HOME/proj
source /usr/local/bin/virtualenvwrapper.sh

The WORKON_HOME directory is where virtualenvwrapper places your virtual environments. You do not need to create it, because virtualenvwrapper will create it automatically if it does not exist. The PROJECT_HOME directory is where virtualenvwrapper places project working directories. Your Pelican blog will end up in there, so this is a directory of interest for you. I called mine proj (short for projects) and created it.

$ mkdir ~/proj

Now you should either reload your shell or ask your shell to read it’s configuration file once more. When using Bash this can be done as follows:

$ source ~/.bashrc
virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/initialize
virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/premkvirtualenv
virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/postmkvirtualenv
virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/prermvirtualenv
virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/postrmvirtualenv
virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/predeactivate
virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/postdeactivate
virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/preactivate
virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/postactivate
virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/get_env_details
virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/premkproject
virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/postmkproject
virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/prermproject
virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/postrmproject

If you edited and reloaded your shell configuration file, your output should be similar.

Create a new project

You are almost ready to install Pelican in a virtual environment. But we still need to create that virtual environment. Let’s do that now.

stefan@aether:~$ mkproject blog
New python executable in blog/bin/python
Installing setuptools............done.
Installing pip...............done.
virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/blog/bin/predeactivate
virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/blog/bin/postdeactivate
virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/blog/bin/preactivate
virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/blog/bin/postactivate
virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/blog/bin/get_env_details
Creating /home/stefan/proj/blog
Setting project for blog to /home/stefan/proj/blog
(blog)stefan@aether:~/proj/blog$

Notice how my prompt changed to include the name of the project we just created? You are now in a subdirectory with the name of your project (blog) inside the PROJECT_HOME directory you specified before. Ready to install Pelican in the virtual environment.

Install Pelican using pip

Let’s not wait any longer and install Pelican already:

(blog)stefan@aether:~/proj/blog$ pip install pelican

pip will now go to work, downloading Pelican and any dependencies and installing them in your virtual environment. These dependencies consist of feedgenerator, jinja2, pygments, docutils, pytz, blinker, unidecode and six on my system.

I will also install another package: Markdown. Pelican supports this markup language and I write this blog in it. It’s also possible to use reStructuredText which is available by default. I haven’t used that much myself, perhaps I will in the future, but at the moment I use Markdown.

Another feature I like to use is Typogrify, which is a collection of filters that help to make your text look pretty. The provide an online example so you can see for yourself.

(blog)stefan@aether:~/proj/blog$ pip install Markdown Typogrify

Configuring Pelican

Hurray! Pelican is now installed on your system. Ready to start configuring it, so you can start using it for your blogging pleasure. To help you with this, Pelican includes a program that starts with a short questionnaire, and sets up the current directory for Pelican with your configuration.

(blog)stefan@aether:~/proj/blog$ pelican-quickstart
Welcome to pelican-quickstart v3.1.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.

Using project associated with current virtual environment.Will save to:
/home/stefan/proj/blog

> What will be the title of this web site? sjoosten.nl
> Who will be the author of this web site? stejoo
> 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) y
> What is your URL prefix? (see above example; no trailing slash) http://sjoosten.nl
> Do you want to enable article pagination? (Y/n) 
> How many articles per page do you want? [10] 
> Do you want to generate a Makefile to easily manage your website? (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) 
> Do you want to upload your website using SSH? (y/N) 
> Do you want to upload your website using Dropbox? (y/N) 
Done. Your new project is available at /home/stefan/proj/blog

As you can see, it asks for some basic information. I left a lot of them at the defaults. Partly because I haven’t figured out what I really want some of them to be, and I do my uploading with Git.

Your directory should now look like:

(blog)stefan@aether:~/proj/blog$ ls
content  develop_server.sh  Makefile  output  pelicanconf.py  publishconf.py

You can now also edit pelicanconf.py by hand to make some final adjustments. Take a look at the Pelican Documentation - Settings chapter. This is how I made mine look:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
#!/usr/bin/env python
# -*- coding: utf-8 -*- #

AUTHOR = u'stejoo'
SITENAME = u'sjoosten.nl'
SITEURL = 'http://www.sjoosten.nl'
TIMEZONE = 'Europe/Amsterdam'

DEFAULT_LANG = u'en'
DEFAULT_DATE_FORMAT = ('%Y-%m-%d(%a)')
DEFAULT_PAGINATION = 10

TYPOGRIFY  = 'True'
#THEME = ''

# Blogroll
LINKS =  (('AT Computing', 'http://www.atcomputing.nl/'),
      ('Tweakers', 'http://tweakers.net'),
      ('FreeBSD', 'http://www.freebsd.org'),
      ('Debian', 'http://www.debian.org'),
      ('OpenWRT', 'https://openwrt.org'),)

# Social widget
SOCIAL = (('twitter', 'http://twitter.com/stejoo'),)

It’s possible to add more things like paths/files to include (robots.txt and favicon.ico come to mind), Google Analytics identifier, a Disqus identity so people can react to your blog posts using it, etc… I’m starting off with this one, and I’ll add or change things later on.

Another thing you could do is install themes or start designing your own. Pelican provides a utility to help you with installing themes, it’s called pelican-themes. Read up on it if you are interested in changing the look of your blog using existing themes. If you feel confident enough to create your own theme, take a look at How to create themes for Pelican.

Start blogging

Ready to make your first blog post?

Place your posts in the content directory, this is the directory Pelican uses as a source to build the HTML files. So let’s change to it now and start a new file:

(blog)stefan@aether:~/proj/blog$ cd content/
(blog)stefan@aether:~/proj/blog/content$ vi hello-world.md

Substitute vi with the editor of your choice.

This is what I put in as a first post in Markdown:

Title:Hello world 
Date: 2013-03-07
Tags: awesome
Category: Blog
Slug: hello-world
Author: stejoo

My first blog post.

Save your file and let’s ask Pelican to process it.

(blog)stefan@aether:~/proj/blog$ pelican -s ~/proj/blog/pelicanconf.py ~/proj/blog/content/

If it returns any errors, you will have to try and hunt them down. Make sure you used the right paths and the syntax of your configuration file and post are correct. Often Pelican will tell you whats wrong. Warnings can be ignored, but fixing them too is always better.

View the results

You could point your browser at your output directory:

$ firefox ~/proj/blog/output/index.html

Or you can run Pelican’s little web server, which is intended for the purpose of testing your blog before you copy your newest posts to your web server. It will serve the contents of the output directory at http://localhost:8000. And in the meantime it will watch the content directory for changes, so any change you make there will show up.

(blog)stefan@aether:~/proj/blog$ ./develop_server.sh start

Once you are done viewing your blog, stop the develop_server using:

(blog)stefan@aether:~/proj/blog$ ./develop_server.sh stop

Ready for deployment

You can now upload the contents of the output directory (or the entire project) to a machine running a web server and publish your blog on the internet that way. Because it’s just HTML, pretty much any web server will do. You could even use your Raspberry Pi for this.

Stay tuned for some more blog posts about hosting this on your own server.

blogroll

social