Creating a Blog with Python Pelican

on June 06, 2012 in technology about

Let’s move beyond the when and why of a personal blog of a web developer and discuss the what and how. The current trend seems to favor the static site generation route and I agree whole-heartedly. Static pages are easier and faster to host and less vulnerable to security issues of other database-driven tools such as Wordpress.

One of the more popular tools for static site generation is Octopress, dubbing itself “A blogging framework for hackers.” While I think Octopress looks great, I am not a Ruby guy. Thus, my search for a python equivalent ended with python pelican. We’ll dive right in and create a virtual environment to keep pelican and its dependencies isolated:

virtualenv /path/to/pelican_env
source /path/to/pelican_env/bin/activate
pip install pelican markdown
pelican-quickstart

pelican is now installed. Note that I am using markdown (pelican gives you the choice between markdown or reStructuredText or both). Go through all the guided steps following the command pelican-quickstart. This should give you a basic structure of:

output/        src/    pelican.conf.py

You may also add a few more directories:

# all .md files in the markdown/ directory will be used to generated articles
markdown/
# all .md files in the pages/ directory will be used to generate pages
pages/
# a few static directories to be copied into output/static/ (more on STATIC_PATHS setting below)
img/    css/    js/

At this point, running the command “pelican -s pelican.conf.py .” in the directory would generate all static files for the blog using the default theme notmyidea into the output/ directory. Just serve this directory as you would any other static html files.

If you’re like me, you’re probably interested in creating your own theme. If this is the case, you can create your own theme from one of the default themes, I suggest simple.

I am creating a directory and calling it theme and copy pelican/themes/simple/templates into theme. In your settings file pelican.conf.py add the following line:

THEME = 'theme' #or whatever name you chose for your theme

(NOTE: you could also simply create a templates directory in your theme directory with the following files: index.html, article.html, page.html, category.html, tag.html and a base.html for your common layout)

Here are a few more useful settings:

# static files to copy into root, very useful for robots.txt
FILES_TO_COPY = (
   ('extra/robots.txt', 'robots.txt'),
   ('extra/humans.txt', 'humans.txt'),
)
# directories to be copied into output/static/
STATIC_PATHS = ['img', 'css', 'js']
# very useful for debugging purposes
DELETE_OUTPUT_DIRECTORY = True

The basic idea is that pelican will be using the template files in your theme/templates/ directory to generate all static html files. pelican uses Jinja for is templating language, which should be quite familiar for Django developers. In these templates, you should have access to all variables from pelican.conf.py as well as template-specific variables (please refer to the “Template and Variables” section of the documents for more information).

Make appropriate edits to the template files and run “pelican -s pelican.conf.py .” again. You should now see your changes in the html files generated in output/ directory.

Hopefully this post motivated any developers or engineers still on the fence about starting a personal blog to finally make it happen. Good luck and have fun blogging!