Turning a personal Vimwiki into a full-fledged site

Wednesday, Nov 4, 2015

Following Ruslan Osipov’s post I decided to improve the appearance of my personal wiki, and at the same time, insert some useful links in a sidebar, allowing quick navigation and preparing the site to become what Phil Windley describes as a Personal Learning System.


Personal wiki screenshot - before

I mostly interact with the wiki in its original form, as a series of files with .wiki extension; exporting the entire wiki in HTML format was a matter of running the :VimwikiAll2HTML command, but I rarely opened the resulting files.

As Ruslan Osipov notes, the main defect that this simple method has, is that the navigation between pages is limited to the back button on your browser. This leads to the site feeling like a collection of separate pages, instead of a unified tool.

Enter the Read Only template, by HTML5UP. A simple, and modern style with a large sidebar on the right, and a couple of graphics to add flair, and it’s also responsive!

After setting the location, name and extension of the default template in the Vimwiki section of my .vimrc file, I copied and modified the sample index file from HTML5UP, replacing all of the main content with a single %content% tag.

I’m fine with the simple HTML that Vimwiki produces, even though it limits the styles that can be applied by the template. The option to delve into the parser and add new tags to the files is there, in case you feel up to it.

At this point, I have a nice looking wiki, with links to its main sections, and also some buttons to sites that I use often.


Personal wiki screenshot - after

Automating the deployment

The command to convert the entire wiki to HTML from outside vim is:

vim -c VimwikiAll2HTML -c q wiki/index.wiki

I made a simple bash file that runs that command, followed by an rsync of all the files in the wiki, and point the Apache server to the folder where HTML files are written. This folder is protected, since I occasionally write personal details in the daily log (phone numbers I need to call, account numbers and the like).

Further changes

A simple change that could add variety to the site is to use the %template tag in a few key files, in order to have them stand out from the rest of the site, by using a slightly different template.