Pelican and Vimwiki

I’ve managed to get Pelican to work with Vimwiki so that I can publish my personal wiki directly to this site. I’ll explain here what I did, why, and how I did it.

Why

I have never been a prolific (or noteworthy) writer, but every now and again I feel like giving it a try. Over the years I have used various means of publishing my drivel. Back in the day I claimed my GeoCities address and put up an embarrassing page about Kate Moss and Nine Inch Nails. Later, I switched to a Blogger.com account, and posted little pieces of nerdiness gathered from around the World Wide Web. Of course, as a programmer, I wanted to write my own blog software. So I did. Over and over again.

These days I don’t have the time to repeatedly reinvent the wheel. Instead I prefer to clumsily lash existing programs together to make a ramshackle raft of software just good enough to get the job done. Just for myself, of course, not for clients.

Pelican

Recently I’ve been hearing a lot about JAMstack (Javascript, APIs and Markup), which proposes a way to build web sites using client-side Javascript for dynamic functionality such as making requests to APIs, and serving static HTML files rather than running web application software that build pages on request. This fits quite nicely with my software MacGyver ambitions, and I already have some experience with Jekyll to generate static HTML for my personal site.

For no good reason other than tribalism, I wanted to use a Python based static site generator instead of Jekyll, which is written in Ruby. I found Pelican which seems to support all of my current requirements, being

1. Written in Python. Flimsy rationalization: I am comfortable with Python and I may want to write plugins
2. Handles Markdown. I don’t want to learn another markup language.
3. I like pelicans.

Vimwiki

I use Vim for editing text. I’ve been using it for about 20 years and I just can’t be bothered to try anything else, so I won’t bore you with the details of what makes Vim such a good editor.

Vimwiki is a handy plugin for Vim that provides an interface to treat a bunch of text files as a wiki. Having a personal offline wiki is a useful way of storing notes and ideas in an interlinked way, rather like a mind-map. These text files can be in several formats, one of which is Markdown. Aha!

How

Vimwiki and Pelican can both make use of Markdown files, so it is quite easy to get them to work together.

First I created my Pelican blog:

mkdir blog
cd blog
pelican-quickstart

This creates the following directory structure:

blog/
  content/
  output/
  Makefile
  pelicanconf.py
  publishconf.py
  tasks.py

Pelican treats any Markdown file in the content directory as a blog post. If you want non-blog pages (for example, an “About” page or a contact form page), you can put them in content/pages.

By contrast, Vimwiki defaults to putting diary entries (which I want to be blog posts) in a subdirectory called diary and non-diary pages in the wiki root directory.

As a compromise, I put posts and pages in sibling directories, respectively diary and pages.

I edited the pelicanconf.py file and added the ARTICLE_PATHS setting, which is where it looks for blog post files:

ARTICLE_PATHS = ['diary']

Then I added the Vimwiki settings in my .vimrc file:

let g:vimwiki_list = [
    \ {'path': '~/blog/content/pages/',
        \ 'ext': '.md',
        \ 'syntax': 'markdown',
        \ 'diary_rel_path': '../',
    \ },
    \ {'path': '~/vimwiki'},
\ ]

I left the default Vimwiki in the list, as it allows multiple wikis.

Finally, to enable wiki links, I configured the wikilinks Markdown extension in pelicanconf.py:

MARKDOWN = {
    "extension_configs": {
        "wikilinks": {
            "base_url": "/pages/",
        },
        "markdown.extensions.codehilite": {
            "css_class": "highlight",
        },
        "markdown.extensions.extra": {},
        "markdown.extensions.meta": {},
    },
    "output_format": "html5",
}

So What

This setup allows me to start a new blog post in Vim with \w\w . I can write in Markdown and have Pelican convert it to HTML and even push it to Github Pages.

I can use [[WikiLinks]] to link pages both in Vim and to generate links on my website.

All without writing a line of code and just editing a couple of configuration files.

It certainly beats writing, quickly tiring of, rewriting, finessing and eventually abandoning yet another blog application. Now I have more time to get good at writing.