James Gregson's Website

Sep 02, 2018

Using the Pelican Static Website Generator

Here is an overview of how I am using the pelican static website generator. This assumes that you're working on Ubuntu 16.04. The overall process loosely follows this process

Installation & Setup

I chose to install using virtualenv under python3. Setup was simple:

mkdir website
cd website
virtualenv -p python3 venv
source venv/bin/activate
pip install pelican markdown

To actually create the site, I ran the following from the website directory. All commands from here on in are relative to this website folder...


Answer the questions to generate the structure for the site. I then made directories for the content,

mkdir posts
mkdir pages

and created an initial 'About me' page, 'about-me.md', in the pages directory to populate the site.

title: About Me
date: 2018-09-02

I am a Vancouver based developer specializing in numerical methods and imaging. 
Over the years I've worked on everything from computational fluid dynamics to 
geometry processing to inverse problems.

To generate the page for the first time, I ran

pelican content

which prints out some summary information about the website, followed by

cd output   
python -m http.server

and loaded the page for the first time by opening http://localhost:8000 in a browser. The first result is pretty ugly but, not to fear, there are plenty of themes available.

Installing a Theme

There are plenty of themes available for pelican, available at https://github.com/getpelican/pelican-themes. I ended up using a slightly modified version of the blue-penguin theme coupled with a slightly modified version of the friendly pygments syntax highlighter from the pelican-bootstrap3 theme.

I ran the following to get and install the theme:

mkdir themes
cd themes
git clone https://github.com/jody-frankowski/blue-penguin.git

This makes a blue-penguin directory under themes. To enable the theme, I added the following line to pelicanconf.py:

THEME = './themes/blue-penguin'

which assumes that the 'themes' directory is a subdiretory of the top-level webpage directory.

The few small changes that I made were:

  • I felt the solarized color scheme for syntax highlighting did not complement the blue-penguin theme, so I swapped the default static/css/pygments.css file of the theme for the static/css/pygments/friendly.css syntax highlighter color scheme
  • The default color for heaading elements in the blue-penguin theme is black, which I don't care for. I used gpick under Ubuntu to select the main color and then lightened it by adding color: rgb(121, 186, 216) to the static/css/screen.css file:
h1, h2, h3, h4, h5, h6 {
    font-family: sans-serif;
    font-weight: bold;
    color: rgb(121, 186, 216)

This results in the color scheme seen in the following snippets:


def hello( a, b ):
    return a+b


class test_class {
    typedef int         index_type;
    typedef test_class  this_type;

    inline index_type add( const index_type a, const index_type b ) const {
        return a+b;

Enabling Math

I enabled math display using the render_math plugin. Clone the pelican-plugins repository under the root website directory:

git clone https://github.com/getpelican/pelican-plugins.git

Then add the following lines to pelicanconf.py to locate the plugins and activate the render_math plugin:

PLUGIN_PATHS = ['./pelican-plugins']
PLUGINS = ['render_math']

After that, add some math inline (\(a=b+\frac{c}{d}\)) by enclosing it between $ delimeters ($a=b+\frac{c}{d}$) or as separate equations:

$$ \begin{bmatrix} a \\ b \end{bmatrix} = \begin{bmatrix} m_{1,1} & m_{1,2} \\ m_{2,1} & m_{2,2} \end{bmatrix} {\bf \hat{x}} $$

by enclosing it between $$ at the start and end:

a \\
\end{bmatrix} = \begin{bmatrix}
m_{1,1} & m_{1,2} \\
m_{2,1} & m_{2,2} 
\end{bmatrix} {\bf \hat{x}}

Wrap Up

That's about all it takes to statically generate a simple website.

posted at 00:00  ·   ·  Pelican