Christian Long's Blog

Pelican

With a bit of wrangling, I got Pelican working to manage my blog. Pelican is a static site generator written in Python. It can handle reStructuredText, Markdown, or AsciiDoc formats.

The next question is, what theme to use? The Pelican theme gallery is helpful here. I debated between these themes:

• Irfan
• Tuxlite TBS
• Pelican Mockingbird
• Built Texts

For now, I’m using Built Texts. It’s as easy as setting

THEME = /path/to/built-texts

in your pelicanconf.py.

Also, make sure that you set

SITEURL = ''

in pelicanconf.py. Otherwise, your local preview site will try to load resoureces (css, etc.) from the url of your published site.

Pelican Blog Workflow

This blog is running on Pelican. It’s pretty slick, and here are a few tips I use to make writing and publishing faster and easier.

New post¶

I have this shell script accessible via an alias nbp.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

#!/bin/bash

set -eu

DRAFTS_DIR=~/projects/personal/blog/drafts

if [ -z "$1" ] ; then
        FILE_NAME='new_post'
else
        FILE_NAME="$1"
fi

SKEL_FILE=$DRAFTS_DIR/skeleton_post
FILE_PATH=$DRAFTS_DIR/"$FILE_NAME".md

cp --no-clobber $SKEL_FILE $FILE_PATH
vi $FILE_PATH

This copies my posting template to a new file in the drafts directory, and opens it for editing in vim.

Dev server¶

Run this command to start the Pelican development server.

make devserver

This will automatically regenerate the site when files are changed. It will also serve the site at http://localhost:8000.

Run develop_server.sh stop to stop the development server.

Browser auto refresh¶

There are many auto-refresh solutions for the browser, but they don’t work well when you are editing a file on a remote server. live.js is a nice solution that takes care of auto-refreshing in javascript. However, we don’t want to include the live.js javascript file in the published version, just in the local development version. We can modify our theme to include it only when developing.

First edit pelicanconf.py. Add this

IS_DEVELOPMENT_VERSION = True

Also edit publishconf.py. Add this

IS_DEVELOPMENT_VERSION = False

Now, change the theme so that every article page includes the live.js javascript, if we are in development. Find your theme’s template directory. It’s probably at themes/<theme name>/templates. Edit article.html. Look for the head block in the template {% block head %}. Add this to it:

{% if IS_DEVELOPMENT_VERSION %}
  <script type="text/javascript" src="http://livejs.com/live.js"></script>
{% endif %}

Run make devserver, and open http://localhost:8000. Edit one of your articles, and see if it reloads in the browser automatically. Neat!

The nice thing about the live.js solution is that it works even if the files you are editing are on a remote server. It polls the page by making a head request every few seconds. Obviously, you don’t want this polling to happen on your published pages.

More on Pelican themes

The Pelican Themes project gathers together a bunch of nice themes for the Pelican static blog generator.

This is a good case for using git’s submodule feature.

Move to where your Pelican is installed (where your pelicanconf.py file is).

$ cd ~/personal/blog

Make sure you are in a git working copy and the status is clean.

$ git status

Add the pelican-themes repository as a git submodule, and commit the change.

$ git submodule add git@github.com:getpelican/pelican-themes.git themes
$ git commit -am "Add pelican-themes as a submodule"

Now we should see the submodule listed

$ git submodule status

The pelican-themes project is itself made up of git submodules. Let’s take a look. Change to the newly-created themes directory, and look at the submodules defined in there

$ git submodule status

-656296ab29a76d980155427f1f1ffe1892966a2a BT3-Flat
-a74606061d62be0f8508ca840375abe52ae24786 Responsive-Pelican
-bd337dffaa8aca10a1757d17385030e3a9d6b835 alchemy
-4ea9f35b517e67488f330799e8637e2e045d657e blue-penguin
. . . etc.

Here git submodule status prints all the submodules that make up the pelican-themes project, one line for each theme. See the little minus sign before the commit hash on each line? That means that the submodule for that theme is not initialized. We could initialize all the themes, but that would pull down a lot of code I’m not interested in. I just want a few themes.

git submodule init blue-penguin
git submodule init pelican-mockingbird
git submodule update

git submodule init initializes the blue-penguin and pelican-mockingbird themes. Then, git submodule update clones the missing submodules.

Then edit your pelicanconf.py file, and add this line, giving Pelican the appropriate path to your theme.

THEME = 'path/to/your/theme'

I’m using the Blue Penguin theme. I made a few modifications. I’m not justifying the text, and I replaced the dark solarized code formatting with my own format based on the Pygments ‘friendly’ style.

Here’s some code, to show off the syntax highlighting.

from pygments.style import Style
from pygments.token import Keyword, Name, Comment, String, Error, \
     Number, Operator, Generic

class YourStyle(Style):
    default_style = ""
    styles = {
        Comment:                'italic #888',
        Keyword:                'bold #005',
        Name:                   '#f00',
        Name.Function:          '#0f0',
        Name.Class:             'bold #0f0',
        String:                 'bg:#eee #111'
    }