Building a static blog with Pelican

Yu Cheng 鄭嵎

Jun 10, 2014 4 min read

Once upon a time…

I spent a summer using Microsoft Frontpage to build a website, hosted by my highschool’s server. Then I also had my first experience with PHP, javascript, html, css, cgi (common gateway interface, I haven’t seen such things for a while!) However, some popular free-webpage services just kept popping out the years after, as “blog” became a everyday word. All of a sudden, a vibrant and powerful “blog”, usually implemented with guestbook and albums is just few clicks away. Thus, I stop writing my own webpages. That was ten years ago. Years later, even MS Frontpage is discontinued. End of last summer, every students in RSMAS got an mail about annual progress report, and building your personal page is listed as a requirment. I first cheated by adding a new blog using wordpress, refusing to revisit my old friends, being afraid of spending too much time on such distractions. However, these distractions just won’t dispear even though I tried hard to ignore… Therefore, after the tiring semster with TA and seminar talk, I came back to revisit some other interesting stuffs I’ve had no time to spend on for the past few months.

Pelican: I love this bird!!

I’ve heard about Django quite often, so it was my first try. Lacking of PHP knowledge, and a personal site needs not to have some log-in or user-management functions, I decided to build a static blog. By accident, I noticed that lots of technical blogs are hosted by Github, and powered by Jekyll, Octopress or Pelican. The reason that I chose Pelican, is simply because it’s python/jinja2 based. And I happened to find some very good references:

{% img http://www.allaboutbirds.org/guide/PHOTO/LARGE/brown_pelican_5.jpg 400 500 %}

Overview

Pelican is a static site engine powered by python, using templates based on Jinja2. It supports both reStructuredText and Markdown, as well as asciiDoc and html, which makes writing new posts extremely easy. The center of a pelican-powered site is the configuration.py file, which controls the basic settings of your site, including side bar, navigation bar options, disqus-comments, tags, categories, twitter supports, and PATH. All the original files (including .md, .rst files) are stored in /contents, and all the html generated by Pelican go to /output folder. Simply upload the /output folder to your web-host, and T’ADA, your website is on. For details of installation and deployment, pleace check official Pelican documentation.

http://docs.getpelican.com/en/3.3.0/

Themes

One of the reasons that I chose Pelican is the active community on Github. As mentioned above, pelican templates are generated by Jinja2, which is a template engine powered by Python. A set of themes including templates of different pages and stylesheets. There are many high-quality themes available on github, which can be easily downloaded using following command:

:::bash
git clone https://github.com/getpelican/pelican-themes

This blog is powered by pelican-bootstraps3 theme; few other themes I would also like to try are Pelican-pure, Mockingbird and Notmyidea. Additional stylesheet can be easily integrated by changing the setting in configuration.py. To switch between different themes, just modify this line in your configuration.py.

:::python
THEME = "pelican-bootstrap3"  # or whatever themes you like

Customize

This is a more tricky part, due to my limited knowledge of CSS and Jinja2. So far I’ve only managed to change the background color, font size, line-height and link-hover style of my header. Even though the syntax of CSS is very straightforward, lacking of nested structure, it is very difficult to read the CCS stylesheet by someone else: one must figure out the class/ID names of each elements in the html files, and locate corresponding tags in the minified CSS file. I’ve found a Sublime-Text package to unminify the CSS, yet still find it difficult to change even a single property. Currently, I am attempting to use SASS/COMPASS to rewrite the stylesheet.

Plugins

One of greatest feature of Pelican is to include modular plugins into your static site. Same as Pelican-themes, these plugins can be downloaded easily from github.

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

Curretnly, I am using the Liquid-tags plugin by Jake Vanderplas to enable Youtube video, iPython notebook, code-block and image insertion in my blog posts, as well as the Math-rendering. Other plugins such as Gravatar and internal-links are very easily to be implemented, in fact, just two lines in the configuration.py. The idea of plugins, are similar to the idea of importing libraries in the beginning of every Python scripts.

:::python
# Plugins
PLUGIN_PATH = '/Users/yucheng/Desktop/Other/MyPage/pelican-plugin'
PLUGINS = ['liquid_tags.img', 'liquid_tags.video',
           'liquid_tags.youtube', 'liquid_tags.vimeo',
            'liquid_tags.include_code', 'liquid_tags.notebook','render_math']

Summary

Pelican is a really powerful static-site generator, using Python. All options you may play with are in the configuration.py and the syltesheet.css. The official documentation of Pelican is rather complete, not to mention the active developer-base. If you are a Python lover, it won’t take you too long to setup a really polished and somehow-dynamic static site. So, look no further, among numerous static-site engines, Pelican is definitely one of the best.