Most people I know in academia have personal websites—it’s expected. And most of those sites haven’t been updated in ages. It’s no wonder; editing HTML or maintaining CMS takes considerable work and requires keeping up to date with the technologies involved. We just can’t realistically afford the time it takes.

During the past few weeks I set up a new website using Pelican. This time my primary criteria for choosing a website building tool were minimal maintenance burden and maximal portability. It does involve compromises, but it’s no good having a website that never gets updated, right? I am hoping that this system will be easier to maintain in the long run, and this website won’t fall out of repair, like my previous attempts did …

Pelican is a static site generator, which means that it pre-generates all HTML for the website. Thus the hosting requirements are minimal: no PHP is needed, no database backend is needed, it’s not necessary to fuss with file access permissions, etc. It can be hosted anywhere, and migrating to a new host should be as simple as copying the files over.

Posts and pages are written in MarkDown, which I am already familiar with. MarkDown is so much easier to write (or read!) than HTML.

Math can be included as well, using the familiar \(\LaTeX\) syntax:

This is thanks to Barry Steyn’s render_math plugin.

When looking for website building tools of this sort, I first came across the popular Jekyll (and Octopress), but these are written in Ruby while Pelican is written in Python. It seems unavoidable to become familiar at least with the package distribution mechanisms of these languages when using the tools written in them. Since I don’t know Ruby, but I do use Python (which has a large following among people doing scientific computing), Pelican seemed a better choice, in accordance with my minimal long-term maintenance burden requirement. If something gets broken there’s a higher chance that I can work around it if using Pelican.

Unfortunately using Pelican wasn’t without hiccups. Plugins are useful and sometimes very needed, but they can break functionality. The system is controlled by configuration files, so features are not discoverable without reading the documentation, yet the documentation is not complete (but still quite good as open source projects go). Despite these stumbles, I’m sticking with Pelican, and hoping that it will work out for the best in the long term.

For future reference (for myself and others considering Pelican for an academic site), I made use of these plugins and settings:

• render_math adds MathJax support without letting Typogrify (see below) break math. Initially I encountered some problems with the plugin, but its author, Barry Steyn, responded amazingly quickly and fixed them. Thank you Barry! Note: full compatibility with Typogrify requires Pelican 3.5 (not yet released as of October 2014).

• interlinks helps set up custom links, which I used for DOI, e.g. doi>10.1103/PhysRev.106.620 links directly here. This plugin needs to be included before render_math to avoid a conflict.

• Putting TYPOGRIFY = True in the Pelican configuration will improve typography, e.g. -- and "quote" become — and “quote”.

• Pelican has built-in support for Disqus comments. After creating a Disqus site, just add DISQUS_SITENAME = "..." in the configuration and fill out the site name.

• Any attachments or downloadable files must be placed in a folder listed in the STATIC_PATHS setting.

• Pelican will try to apply syntax highlightig to code blocks by default. Should this cause problems, it can be disabled by removing markdown.extensions.codehilite from the extension_configs keys of the MARKDOWN setting. Altnernatively, it can be instructed to simply output the programming language name as a CSS class and leave highlighting to JavaScript libraries such as prettify. Within the codehilite options, set 'use_pygments': False, which disables highlighting using Pygments, and set 'css_class': 'prettyprint', which prettify will recognize; unfortunately this does not work with fenced code blocks though.