Pelican and Org Mode

Introduction

One of the first things you need to do after deciding to start a blog, is setting one up. So I figured it would be appropriate that the first post of my blog is about how I set this up.

My requirements are fairly simple:

create a static site
be able to write content using Emacs’ org-mode
preferably written in a language I know

This led me down a path of looking at and trying a few different static site generators.

Each static site generator essentially works the same. There is a CLI which allows you to:

scaffold out the site
create content in a folder in some sort of text format, e.g. markdown, rest, org, etc
generate HTML from the content
run a local server to preview the website

After trying out a few different ones, I decided to use Pelican. It seems to be the most popular and actively maintained one written in Python. It’s even used by kernel.org!

Initial setup

First, install pelican (I use pipenv personally).

pipenv install pelican
pipenv shell

Create the folder where you want the website and initialize the site:

pelican-quickstart

This scaffolds out the files and directories needed.

Create a new post in the content folder.

Generate the output:

pelican content

This generates the output into the output folder.

Preview the content:

cd output
python -m pelican.server

If you select “yes” during pelican-quickstart, a Makefile is created. This allows you to use make to automate some of the pelican tasks such as generating the output, publishing, running the server, etc.

Generate and preview the content with make instead of pelican:

make html
make serve

It can also do some other cool stuff like generating the production version of the website, use GitHub’s gh-pages branch, etc. See how to use it from the official docs.

Using org-mode

In order to use org-mode, you need to install a plugin.

To install a plugin, clone the pelican-plugins repo:

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

Add the path and the plugin to your pelicanconf.py:

PLUGIN_PATHS = ['path/to/pelican-plugins']
PLUGINS = ['org_reader']

There are three different plugins to choose from:

org_reader
org_python_reader
org_pandoc_reader

Each plugin uses a different mechanism to convert the .org files to HTML. org_reader uses Emacs, org_python_reader uses the orgco Python library, and org_pandoc_reader uses (you guessed it…) Pandoc.

It seems that org_python_reader is an ‘update’ for org_reader. org_pandoc_reader on the other hand looks to be based off of another plugin, pandoc_reader.

Org Reader Setup

Add the following to pelicanconf.py:

PLUGINS = ['org_reader']
ORG_READER_EMACS_LOCATION = '/usr/bin/emacs'

In order to define the metadata for Pelican, put the following in the org file’s header:

#+TITLE: The Title Of This BlogPost
#+DATE: 2001-01-01
#+CATEGORY: blog-category
#+AUTHOR: My Name
#+PROPERTY: LANGUAGE en
#+PROPERTY: SUMMARY hello, this is the description
#+PROPERTY: SLUG test_slug
#+PROPERTY: MODIFIED [2015-12-29 Di]
#+PROPERTY: TAGS my, first, tags
#+PROPERTY: SAVE_AS alternative_filename.html

Org Python Reader Setup

Add the following to pelicanconf.py

PLUGINS = ['org_python_reader']
ORGMODE = {
        'code_highlight': True,
}

It will not work unless you add ORGMODE. The only option currently is code_highlight which can be set to True or False. This tells the plugin whether to add syntax highlighting to SRC blocks.

This uses the same org headers as org_reader.

One thing to note is that this plugin will always print out line numbers in SRC blocks due to its dependency on orgco.

Org Pandoc Reader setup

In order to use org_pandoc_reader, you need to clone it as the pelican-plugins repo only links to it, it doesn’t include it directly:

git clone https://github.com/jo-tham/org_pandoc_reader.git

Add the following to pelicanconf.py

PLUGINS = ['org_pandoc_reader']
ORG_PANDOC_ARGS = ['--standalone',]

Without --standalone, the SRC blocks don’t have syntax highlighting. Source code blocks are also underlined for me in some themes for some reason. I might take a look at why that is happening later.

org_pandoc_reader also does not use PROPERTY to generate metadata, you just use the name of the setting directly, e.g.:

#+TITLE: The Title Of This BlogPost
#+DATE: 2001-01-01
#+CATEGORY: blog-category
#+AUTHOR: My Name
#+LANGUAGE: en
#+SUMMARY: hello, this is the description
#+SLUG: test_slug
#+MODIFIED: [2015-12-29 Di]
#+TAGS: my, first, tags

Conclusion and Other Thoughts

Using Pelican and org-mode is pretty nice once its set up. Although I did run into some troubles initially, and I was able to fairly easily fix the issues I was having. I even submitted my first issues and PR’s to an open source project that wasn’t my own or a friends!

I am using the org_reader plugin right now, but I’m not sure if I’ll stick with it, pandoc have look pretty nice too.

In my testing of different static site generators, I tried Hugo, written in go, along with the ox-hugo package for Emacs. I really liked it as ox-hugo gives you the ability to have several posts/pages/etc in a single org file. I would ultimately like to set something like that up for Pelican, but that’s a task for a later day.

Some examples of org-mode stuff

this is a task to be done

And this is a completed one

This is a table

c1	c2	c3	c4	c5
5	4	3	2	1

vonpupp/pelican_and_org.org