Adventures on Planet Earth

Blog creation with Pelican

This is how Pelican can be installed under Ubuntu Linux 12.04 and used to create a blog. It is based on the recommended approach described in the official Pelican documentation website.

The following code is run from the command line. The command line can be accessed using the keyboard shortcut Ctrl-Alt-T.

A Python virtual environment needs to be installed using the apt-get command:

sudo apt-get install python-virtualenv

Administrator access will likely be required and a prompt for the password will be shown.

The installation will take a few minutes and permission to use disk space for the installation will be requested.

Create a Pelican virtual environment:

virtualenv ~/virtualenvs/pelican

Navigate to the new virtual environment and start it:

cd ~/virtualenvs/pelican
source bin/activate

Once the virtual environment is setup for Pelican, install it through the Python package installer tool pip (this should come installed with Ubuntu).

pip install pelican

Create a projects folder to store website projects, for example a homepage, then change directory to this project:

mkdir -p ~/projects/homepage
cd ~/projects/homepage

To quickly generate the site within the homepage directory:

pelican-quickstart

As a guide to answer the setup questions:

  1. Where do you want to create your new web site?[.]
    Type ‘~/projects/homepage’.
  2. What will be the title of this web site?
    Type the name that will appear as the site title and in search engine results.
  3. Who will be the author of this web site?
    Type in an author name.
  4. What will be the default language of this web site? [en]
    For English, type ‘en’.
  5. Do you want to enable article pagination? (Y/N)
    This will create an index page with summaries of blog posts, ordered according to date by default.

There are some finer details on how to setup for site deployment, but the answers above ignore this and assume that the site will be FTP’d through a third party application.

That should be it, the blog is created in the ~/projects/homepage directory.

To see what the default looks like, run the following commands in that directory:

pelican content -s publishconf.py
pelican content

The generated blog will be located in ~/projects/homepage/output and can be previewed with Firefox:

firefox index

Alternatively, the site can be served locally and previewed with Firefox:

make serve

Open up http://localhost:8000 in Firefox afterwards.

The theme will be very simple. To get more themes, install git and download (all) Pelican themes from git-hub into the projects folder:

sudo apt-get install git
git clone --recursive https://github.com/getpelican/pelican-themes ~/projects/pelican-themes

To edit the layout of a theme, the configuration file in the ~/projects/homepage/ directory should to be edited:

gedit pelicanconf.py

To change the theme, THEME = 'XXXX’ should be added to the pelicanconf.py file, where XXXX is the name of the theme, and also the name of the subfolder within which the theme files exist. The themes available are in the ~/projects/pelican-themes folder. There should be some helpful screenshots to help choose between them.

Pelican installs with some default themes:

  1. XXXX = 'simple'
  2. XXXX = 'notmyidea'

To use one of the themes downloaded through git, a chosen theme must be copied from the ~/projects/pelican-themes folder into the ~/virtualenvs/pelican/lib/pythonX.Y/sitepackages/pelican/themes folder, where X.Y is the name of the python version installed (I am not sure if this is the best way to do this, but it seemed to work).

Every time the config file is updated or content is created and updated, the following commands should be run:

pelican content -s publishconf.py
pelican content

It is a good idea to just go ahead and install Markdown for blog posts. This should be done within the Pelican virtual environment:

pip install Markdown

Further details on content creation are in official Pelican documentation website.

Finally, to exit the virtual environment:

deactivate

Tip:

To use LaTeX math when the theme does not support it, the following code should be added to the base.html file just before </head>. This file is located in the theme templates subfolder:

<!-- Using MathJax, with the delimiters $ -->
<!-- Conflict with pygments for the .mo and .mi -->
<script type="text/x-mathjax-config">
  MathJax.Hub.Config({
  "HTML-CSS": {
  styles: {
  ".MathJax .mo, .MathJax .mi": {color: "black ! important"}}
  },
  tex2jax: {inlineMath: [['$','$'], ['\\\\(','\\\\)']],processEscapes: true}
  });
</script>

<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML"></script>

For Markdown blogposts, just sandwich LaTeX math with $$, or $ for in-line equations.