🔍
Creating a personal wiki with Vimwiki and Gollum

One of the reasons for the Web’s triumph over the Gophernet in the early 90s is its superior organisational structure. Hypertext links allow any one page to be linked from any other page without regard for hierarchy or location,1 but you can still define hierarchy and location like you would in a filesystem. Early on, in 1994, Ward Cunningham invented the wiki, a sort of mini-web that leveraged the associative power of hypertext linking within a single website. This was good, and it paved the way for the creation of the world’s greatest encyclopedia.2

Hypertext is an incredibly powerful tool for organising information because it allows you to organise things not only in traditional hierarchies and lists, but also lets you make arbitrary links between material. Using Wikipedia, if you want to switch from an article on Colonel Sanders to one on the Great Depression, you click the words “Great Depression” as they appear in the summary of the Colonel’s life rather than, say, jumping back to an index page or doing another search.

Good wiki software provides an easy-to-use interface for making these sorts of connections by letting you link with syntax less verbose than <a href="urlofpage">Nameoflink</a>. Ergo, the best encyclopedia in the world is a wiki and the best way to organise your notes is in a personal wiki.

Making a personal wiki

I use Vimwiki, a feature-rich plugin for Vim that allows you to create a plaintext wiki with all the usual Markdown formatting, todo lists, syntax-highlighted codeblocks and even a diary for making daily notes.

Vimwiki is easy and intuitive. In Vim, you can open the index page of your wiki at any time with <leader>ww. From there, creating additional pages is a matter of writing a single-word page name and pressing Enter on it. Navigating to the previous page is done by pressing Backspace (in normal mode of course).

So Vimwiki is great for plaintext notes, but sometimes you want pictures, or at least to read something in better typesetting than that afforded by a terminal-based text editor. That’s where Gollum comes in.

Gollum is a wiki built on top of the Git source control management system. Source control management (or version control) systems are best known for dealing with programming code, but can be used for anything that mostly involves plaintext files.3 Gollum is small and lightweight, but manages to implement everything you could reasonably want from a wiki: links between pages, basic text formatting, page creation, modification and deletion, full text search, and a substantial number of text formatting options.4

Step 1: Preparation

Install Vimwiki through your favourite Vim plugin manager (I recommend Vundle), and install Gollum by typing gem install gollum (first install Ruby, preferably through RVM or rbenv). This can all be done on Linux, Mac or Windows, but if you’re using Windows and don’t hate yourself more than average, do it through WSL.

Once both are installed, it’s time to conjoin them. For interoperability with Gollum, configure Vimwiki to use Markdown formatting5 by specifying the following in your ~/.vimrc:

let g:vimwiki_list = [{'path': '~/vimwiki/', 'syntax': 'markdown', 'ext': '.wiki'}]

In the above directive, I’m setting the location of my Vimwiki to /home/USER/vimwiki/. Change the value of ‘path’ if you’d like it somewhere else. Make sure to create the directory – we’ll need it soon.

Here we set the markup syntax for your wiki to Markdown but leave the extension for wiki files as the default .wiki. If we were to change it to .md, Vim would start seeing all .md files as files of type vimwiki rather than of type markdown, which we (or at least I) don’t want.

It’s fine, we can do this – file extensions are meaningless. But once we add Gollum into the mix, we hit a snag. Gollum decides on what markup to use on a given page from its file extension – file extensions are meaningful. It does this by passing rendering duties to github/markup, a gem made for the express purpose of rendering different markups depending on file extension. Despite what this page may lead you to believe, it is impossible to make the system believe that your .wiki file quacks like a .md file.

Impossible, that is, without altering the library code. In order to get full file extension/markup language decoupling, you’ll need to apply my (gross, hacky) patch to Gollum’s markup rendering filter (find the gem to modify in /your/ruby/gems/directory/gollum-lib-4.2.7/).

From e26e841c5b1175f13cac0e2b6b35eb3e99d7368c Mon Sep 17 00:00:00 2001
From: David Yates <[email protected]>
Date: Wed, 23 Aug 2017 22:58:46 +0200
Subject: [PATCH 1/1] Determine markup format from format name rather than
 filename

---
 lib/gollum-lib/filter/render.rb | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/lib/gollum-lib/filter/render.rb b/lib/gollum-lib/filter/render.rb
index baa3060..6555869 100644
--- a/lib/gollum-lib/filter/render.rb
+++ b/lib/gollum-lib/filter/render.rb
@@ -3,7 +3,12 @@
 class Gollum::Filter::Render < Gollum::Filter
   def extract(data)
     begin
-      data = GitHub::Markup.render(@markup.name, data)
+      format = Gollum::Markup.formats[@markup.format][:name]
+      format = "rest" if format == "reStructuredText"
+      format = "org" if format == "Org-mode"
+
+      # format is determined from file extension
+      data = GitHub::Markup.render("."+format.downcase, data)
       if data.nil?
         raise "There was an error converting #{@markup.name} to HTML."
       end
@@ -17,4 +22,4 @@ class Gollum::Filter::Render < Gollum::Filter
   def process(data)
     data
   end
-end
\ No newline at end of file
+end
-- 
2.7.4

Or you could just specify .md as the extension for your Vimwiki files and not bother with any of this patching nonsense.

But assuming you did apply the patch, the last step before we can create our wiki is to tell Gollum which format we want to use and what file extension should be associated with it.6 Do this by creating config.rb in ~/vimwiki/ (or wherever you want your wiki) and filling it with:

# always include this:
Gollum::Page.send :remove_const, :FORMAT_NAMES if defined? Gollum::Page::FORMAT_NAMES

# first remove all markups:
Gollum::Markup.formats.clear

# and then define the sole markup to be supported:
Gollum::Markup.formats[:wiki] = {
  :name => "Markdown",
  :regexp => /wiki/,
  :reverse_links => false
}

Step 2: Creation

Now we can actually create the wiki. In your wiki’s root directory, initialise a Git repository. Gollum will use this to track your wiki’s history, so you can never lose text or whole files from a single fat-fingered accidental deletion:

git init

Then we can start Gollum with:

gollum --config=config.rb 

Leave the flag off if you didn’t need to write a config.rb.

Navigate to the webserver Gollum starts at http://localhost:4567 and you’ll be prompted to create a homepage for your new wiki. This page will be stored as Home.wiki and will serve as an entry-point for your wiki. You’ll probably want to make it an organised table of contents. For now, put some placeholder text there and save the page.

This homepage presents something of an interoperability snag with Vimwiki, as Vimwiki recognises index.wiki as the wiki’s homepage, rather than Gollum’s Home.wiki. Rather than having two homepages for the same wiki (though this is a perfectly viable option if you prefer it), let’s symlink Home.wiki to index.wiki.7

ln -s Home.wiki index.wiki

Now we can bring in Vimwiki. Open Vim and press <leader>ww (if you haven’t encountered Leader before, it’s /). Write some text to index.wiki, and then run:

git add --all .
git commit -m "First use of Vimwiki!"

Refresh the Gollum homepage in your web browser to see your changes reflected.

Tada!

Step 3: Customisation

The obvious next step is to create some wiki pages. Depending on your mood, this can be done through Vim in Vimwiki or through the web interface in Gollum. Note that you will have to manually git add and git commit file creations and changes done in Vimwiki for them to be recognised by Gollum – I recommend a script like this (and maybe a cron job to go with it):

#!/bin/sh

git add --all .
git commit -m "Changes"

# more descriptive/dynamic commit messages left as an exercise for the reader.

We can also apply some neat customisations to our new wiki, both in the Vimwiki and Gollum views.

Customising Vimwiki

We can get code syntax highlighting in code blocks for any language known to Vim by specifying these languages in ~/.vimrc. Here’s mine:

let wiki.nested_syntaxes = {'ruby': 'ruby', 'python': 'python', 'c++': 'cpp', 'sh': 'sh', 'racket': 'racket'}

Codeblocks to highlight are written like this:

```ruby
Gollum::Markup.formats[:wiki] = {
  :name => "Markdown",
  :regexp => /wiki/,
  :reverse_links => false
}
``` 

As a bonus, if Pygments is installed on your system, this syntax highlighting will automagically work in Gollum as well.

We can also tell Vimwiki to use pretty, alternating colours for different heading levels (as in the top screenshot on this page) by adding this to ~/.vimrc

let g:vimwiki_hl_headers = 1

Customising Gollum

We can write custom CSS for Gollum by creating a custom.css file in our wiki’s root directory and running Gollum with the additional flag --css.

A few of my own style changes – smaller headings, different font, background colour, less button-y buttons, etc.

Gollum also lets you create custom macros, useful for specifying often-used, complex formatting not supported by Markdown. For example, you’d want to define a macro to create image captions, or something like the yellow pop-out info boxes I used above.

Step 4: Preservation

Beyond version history and the timey-wimey shenanigans of branching and merging and rebasing, Git also provides distributed backups. Create a repo with your favourite Git host(s) (and/or your own server), set it as a remote and remember to git push every now and then. This will also allow you to keep an up-to-date version of your wiki on multiple devices.

In practice

I do most of my writing and editing in Vimwiki (them keybindings, man), and use Gollum for reading and browsing around, especially for pages with pictures and/or lots of formatting. I imagine the setup could also be useful for wikis with multiple editors, where one person wants to use Vim and another person prefers the web interface.

Lastly, I should mention that Vimwiki provides its own impressively robust functionality to generate HTML output from wikis (:Vimwiki2HTML), but it only supports the default syntax, and doesn’t have many features Gollum provides such as graphical history and site search. So if you just want HTML conversion and don’t care for Markdown, that might be the better way to go.


  1. This caused some controversy in the early days of the web.
  2. The Digital Antiquarian provides a more comprehensive survey of the history of hypertext in this post .
  3. I use Git for everything from my code to this blog to the novel I’m slowly, painfully writing.
  4. Authentication is provided through a separate project, OmniGollum
  5. Vimwiki defaults to a custom markup that’s not quite MediaWiki, not quite Markdown. It’s not horrible to use, but you’ll never see it anywhere else.
  6. By default, Gollum provides a large array of syntax options, all of which can be used in the same wiki. I prefer to stick with one.
  7. It’s best to use index.wiki as a symlink to Home.wiki rather than the other way around if you want to be able to edit the homepage in both systems. Vimwiki will invisibly follow symlinks, but Gollum will overwrite them with files.