Why I Chose Pelican for my Blog

Posted on Thu 07 December 2017 in Python

Welcome to my blog. For my first post I thought I would explain why and how I created this site. If you want to skip the personal background and just get to my tips on Pelican, jump down to Tips and Tricks.

Why not WordPress?

I recently created a blog site for work using Wordpress.com. It is very easy to set up a site this way and there are lots of themes and options that you can use.

I set that site up primarily as a way to test sending updates to a WordPress site using XML-RPC. At the time we had a new client that required updates be sent to their site this way. Getting our own site set up was an added benefit. XML-RPC is a way to connect remotely to a WordPress site. It stands for XML Remote Procedure Call. So I had to write a simple script that makes an http connection and sends an XML file using XML-RPC.

For our own site, I wrote a Python script to automate daily updates from JSON files. This worked well except for the fact that I did not have a lot of control over the look and feel of the site aside from the features available in the theme I had chosen.

A second issue with the WordPress site is that I noticed a lot of traffic coming from countries in Eastern Europe. While I trust the folks at Wordpress to deal with security, you have to wonder why so many non-English speakers would be coming to the site. I have since learned that enabling XML-RPC opens up your site to security issues including brute force attacks and denial of service attacks. Hmm, maybe that's what all those Eastern Europeans were up to.

Choosing Pelican

I have been working mainly with Python for the last two years, so I wanted to use a technology that worked with Python. I thought about learning PHP, but I really don't know Python well enough to start down the path of another language. Maybe some day, but not now.

Besides being written in Python, the other advantages with Pelican are:

  • Creates static HTML files - This makes security much less of an issue since there is no database or moving parts to interact with.

  • Hosting for free on Github - Again the security is key here since there is no need to set up a host on a cloud provider. Pelican is not the only way to do this, but it is one of the easiest to use if you want to use Python. Free is pretty good too!

  • There are tons of open source themes available based on Bootstrap - The one I use is called Flex.

  • Easy to create your own Bootstrap theme - Something I will probably try in the future, but for now using a pre-made theme is a no brainer.

Setting Up Pelican

There are a lot of resources available to help with setting up Pelican, so I am not going to go into too much detail on the basics. Here are the ones that I used and found the most helpful.

Pelican Docs

Full Stack Python

Making a Static Blog with Pelican

How to set up Pelican blog

Configuring Pelican Static Blog

For tips on Markdown:

Markdown Language Reference

ReText (A Markdown editor built in Python)

Tips and Tricks

Using a Different Theme

While it is really easy to get Pelican running (I use Ubuntu 16.04 LTS), my biggest issue was with changing the preset theme.

There is a command line tool for managing themes in Pelican. You can see a list of the installed themes using:

pelican-themes -l

To install a theme use:

pelican-themes -i [theme-path]

While I tried using this command, it didn't seem to make a difference with regard to what theme was used when generating the site. What is most important is that what ever directory you put all of the theme files (by default this is called theme), you reference that directory when you generate the site.

You can use Make to generate the site, but I choose to use the Python command that allows you to set the specific settings to use including the theme.

The command is:

pelican -s pelicanconf.py -o output -t [theme sub-directory] content

Initially, I was confused with this command since the sub-directory containing the default theme is called "theme".

You can copy all of your chosen theme's directories and files into the theme sub-directory or, as I did, give it another name and make sure it is under the main directory for your site.

The file structure will look like this:

project name
|    fabfile.py
|    Makefile
|    pelicanconf.py
|____content
|____output
|____theme

Since I am using the Flex theme, I added another sub-directory named "Flex" and cloned the files from the theme's Github repo. I wanted to keep the default theme in case I made a mistake.

This led me to some confusion typing the following command:

pelican -s pelicanconf.py -o output -t theme Flex content

instead of:

pelican -s pelicanconf.py -o output -t Flex content

Of course I kept getting the default theme. Maybe this was a newb mistake, but since I didn't get any error message with my incorrect command, it took me a while to figure this out.

So either overwrite your new theme into the theme directory or point to your new theme's directory. Don't do both!

Whether to Use the Pelican Development Server or Not

The first time I ran through the example from Full Stack Python I used Makefile to run the development server. I found it to be a little confusing since you can't just Ctrl+C out of it.

Using the regular production server was the easiest for me. I would just switch between building the static HTML files with the Pelican command above and then the following command:

python -m http.server

This starts server as a local host on port 8000. You just need to point your browser to localhost:8000.

Two things to keep in mind when doing this:

  1. Make sure you cd to the output sub-directory from your main directory. You can start up the server in the main project name directory, but what you will see in your browser is your file directory, not your HTML files.

  2. Make sure to comment out the SITEURL setting in your pelicanconf.py file. I found that I was not able to access updated HTML files from the local server in the browser if this line was not commented out. I think this is due to the fact that I had RELATIVE_URLS = True. Once I changed the setting to False, it worked fine. When you publish your site, it is advised that you set RELATIVE_URLS to True again and uncomment the SITEURL setting.

And that's it. Overall, I think Pelican is a great way to create a static blog. You can also use it to easily create any kind of static web site without dealing with adding the complexity and security issues of a CRUD site that connects to a database and requires more sophisticated hosting.

Pelican markdown