Set up your RPG Campaign details in vimwiki

I found this Getting started with Vimwiki blog post by Chris Mague a good and thorough guide to the installation and use of vimwiki. So, I will shamelessly emulate his approach and put together a similar guide for anyone who seeks to install and use vimwiki for RPG campaign detail management.

The goal of this document is to install vim, configure vim, and set up a pair of vimwiki installations. One vimwiki is labelled vimwiki and contains information for both players and the Gamemaster. The second wiki labelled private contains information intended only for the Gamemaster. The second wiki links to the first. There are no links from the first (public) wiki into the second (private) wiki.

Prerequisite: Install Vim

Everything after this assumes 1) you have already installed vim and 2) you are familiar with using vim.

If you run Mac OS X, you will probably prefer to use MacVim rather than fire up Terminal (or iTerm2) and work with vim inside the Command Line Interface (CLI).

If you run Linux yet the gvim command does not work, you probably want to install vim-gtk or vim-gnome or a similar variant to get a vim GUI.

If you have vim, but you would appreciate a tutorial, try vimtutor. On Linux, you can install vimtutor with yum install vim-enhanced (RedHat) or apt-get install vim-runtime (Ubuntu)

If you have questions, one place to find answers is the vi and vim site on the Stack Exchange collection of sites.

Install Vimwiki

1. First, add these lines to your ~/.vimrc file

    set nocompatible
    filetype plugin on
    syntax on

Without them Vimwiki will not work properly.

2. There's at least three different ways to install vimwiki. Arguably the easiest way to get the most current copy is described on the vimwiki github page which I will reproduce here:

   • download the zip archive and extract it in ~/.vim/bundle/
   • Then launch Vim, run :Helptags and then :help vimwiki to verify it was installed.

The git archive does not work

If the git archive does not work, there's a vimball from 2013 on vim.org. Download this, and unpack it as says on that page:

1. Open vimwiki-N-N.vba.gz with Vim. (N-N is version number i.e. 2-1)
2. Source it with the command :so %
3. Run :help vimwiki to confirm that the plug-in loaded correctly.

Use vundle

Vundle is a plug-in manager for vim. The Getting started with Vimwiki blog has details about how to add both vimwiki and the Calendar plug-ins. The short summary:

1. Install vundle
2. Add Calendar and vimwiki to the vundle file. My vundle configuration is done from my ~/.vimrc

    Bundle 'mattn/calendar-vim'
    Bundle 'vimwiki'

3. Run :help vimwiki to confirm that the plug-in loaded correctly.

Configure Vimwiki

1. Many of the commands used by vimwiki start with the leader key. If you have not changed it, your leader key is most likely the backslash ("\"). You can find what it is, and remap it if you choose.
2. Put these lines in your .vimrc to set up the public and private wikis

    " vimwiki 
    let wiki_1 = {}
    let wiki_1.path = '~/vimwiki/'
    let wiki_1.path_html = '~/vimwiki_html/'
    let wiki_2 = {}
    let wiki_2.path = '~/private/'
    let wiki_2.path_html = '~/private_html/'
    let g:vimwiki_list = [wiki_1, wiki_2]

You now have two wiki installations, the first labelled vimwiki and the second labelled private

Use Vimwiki

1. Start up vim.
   • In the examples below, I use gvim. You can use vim from a terminal instead.
2. You can use the Vimwiki menu to look at the links to the index pages. However, there's no data there yet, and the directories are not created yet. The commands in the next steps will build the directories and data.

Figure One: Vim with vimwiki menu links and an otherwise empty screen

3. Type \ws to show the list of two wikis. Choose the first one, the public one named vimwiki

Figure Two: Show vimwiki command line links

4. The directory vimwiki does not exist. Vim can tell this, and prompts you to create it. Click 'Y'

Figure Three: Create vimwiki directory

5. Enter the text of the index page. Be sure to add the search term Foobar for this page. We're going to want to search on a unique string in some but not all of the pages. That's what Foobar provides, here.

Figure Four: Create index page. Now With Foobar.

6. To turn text into links, surround the text with a pair of square brackets [[ and ]]

Figure Five: Create a link from the text 'Capital City'.

7. Save the file.

8. Move the cursor on to the link text. Press <S + CR> (Hold down the Shift key and press Return).

   • This opens the target of the link in a horizontal split window.

9. Add content to the new page in the split.

   • I've added some population information to Capital City as an example.

Figure Six: Open link target in split.

10. We want a second, Gamemaster only, wiki. To create this second wiki in a new tab, type 2\wt You are prompted to create the second directory (named private here)

Figure Seven: Create new directory.

11. Add content to the second private wiki index page.

    • In the image below, the private wiki is in a new tab.

Figure Eight: Add content.

12. Add a link to the first wiki by prefacing the link with the wiki number.

    • The first wiki in the link list (the public wiki) is wiki0. This means the link starts with wiki0.
    • There's no problem with a space in the wiki text name between Capital and City

Figure Nine: Add interwiki link from private wiki back to first (public) wiki.

13. Save the file. Put the cursor on the interwiki link and press Return. This follows the link from the private wiki and takes you to the public wiki target.
14. Press Backspace to go back a link. You return to the private Gamemaster page.
15. You can search one wiki with :VWS /term/ but that search does not extend across multiple wikis. It only searches one wiki at a time.

Figure Ten: Vim Wiki Search

Build a Chronicle using vimwiki diary function

The assumption here is that your <leader> key is set to ("\")

1. \ws lets you select 1 to open the public wiki.
2. press \w\w to create a new chronicle entry.
   • This uses the vimwiki diary function and shows up in the subdirectory vimwiki/diary
   • The file name of the wiki chronicle entry is derived from the current date.

Figure Eleven: Create a wiki chronicle entry

3. press \wi to go to the index of all chronicle entries.
4. press \w\i to update the links to of all chronicle entries.
   • You must be on the index page to run \w\i

Figure Twelve: Update the links to all chronicle entries

One campaign fills two vimwiki installations

I will run a campaign for friends in the coming months. A big campaign.

This idea is fraught with peril for several reasons. The first two that come to mind:

1. The setting is large. Large continent with large number of people. Many of the opponents have large schemes.
2. The players who will participate in this campaign setting are smart. And by that, I mean "graduate degree in Engineering Physics" smart. Like "I have multiple patents to my name" smart. Like "I am a moderator on BoardGameGeek.com and I have played, owned, or reviewed every tabletop game ever made by humanity and some made by subhumans." So putting together a campaign that is interesting, let alone challenging, is going to require some detailed brain work on my part. I'm going to have to get up very early in the morning several years in advance to get ahead of these players.

This means I need a tool that can keep track of a large number of details.

It'd be best if those details are stored in plain text. That way I can search the content quickly using existing tools. Storing those details in a specific binary format or a database locks the details down and makes transformation a challenge.

Those details are to be shared. Descriptions of people, places and things in the campaign are meant to be shared with the players. I like the idea of putting together electronic books and sharing the details in one unified book with an edition date. Most of my players can use the Apple offering iBooks which means ePub format, but one or two will probably prefer to use Kindle which means either MOBI or KF8 format... maybe both.

It might be easier to put all those details up into a wiki like Mediawiki, and access those details through the Internet. The Mediawiki allows collaborative editing which I want for my players (assuming my players have the time to add details! Everyone gets so busy....) This assumes we'll always be gaming somewhere with Internet access.

Paper handouts of non-player character details could come in handy. That means transforming text into PDF format. Any sort of positioning of those details needs some sort of word processor or layout tool. If I have to make one single handout I could put the details in Pages or OpenOffice or something else, but if I have to make three or more I would look at wrapping the details in LaTeX and transforming those files to PDF.

That sounds like a number of different formats. Plain text also lets me transform and format the content quickly.

But wait! There's more! Not all the details will be shared with the players. My intent is to build one campaign world, but some of the details will be shared and other details will be for GM eyes only.

I could try hiding some of the Gamemaster details in comments, but I don't trust that I can keep commented details secret and/or up-to-date. I'd work with more confidence if I had all the game master secret details secured in a special secure location. The default is public. Anything not secured is assumed to be public details in a collection the player characters can (and hopefully will be excited to) look at.

That sounds like two wiki installations. Sometimes I get part of an idea, and I'd like to capture it somewhere. Two and a half wiki installations? There's also a need for a "PC log" or chronicle of what the players encounter and do. So that sounds like two wiki installations, maybe three, plus some sort of record organized by date.

Enter vimwiki.

Vimwiki will store all the details in plain text files. This means I can subsequently use pandoc to group a dozen of those files together and transform that group into one electronic book in ePub format. Pandoc can also transform text into PDF.

Plain text files means that the wiki can be stored in git. Stored in git means version control and distributed copies (also known as backups). It might not be a big selling feature for most people, but my use of plain text files also means I'm not tied to a vendor or a cloud. I don't have to worry about Obsidian Portal going offline, or running out of disk space on Google Drive nor iCloud nor Azure. I don't have to fear that the Internet connection is down; I can make a backup locally or to the cloud.

Vimwiki can manage two wiki installations: one for the GM and a second one for the public player information. Details can be cross-linked between the two wikis, so the GM wiki can link to the public site without dropping too much information. I heard about this first on a reddit post.

There are tools to sync files to and from a Mediawiki site. Vimwiki has its own wiki syntax, but it also has an option to use the Mediawiki syntax. So, the player wiki will be set up with Mediawiki syntax and the files posted to the public Mediawiki. You might be reading this and thinking "How are you going to keep the two in sync?" Given how busy my players are with other tasks, and given that there might be a dozen people globally that want to contribute to this wiki, I do not foresee a locking nor a synchronization issue.

Vimwiki has a diary function. I'm not one for "Dear Diary: today I plan to take over the world!" type entries. However, the diary function is a great way to open a new file for today, jot down some half-baked thought, then continue. Those half-baked ideas can be stored, searched days later, then pulled into either of the first two wiki installations.

Another term for diary is chronicle. The diary of the public wiki can be used for the chronicle of what the players encounter.

The example above has one gvim instance open with four windows in that instance.

The top row has one entry for the public vimwiki. The path is~/vimwiki/diary/2016-08-05.wiki and the entry shows a public chronicle of what the players did. Better luck against the vegepygmies next time, players!

The middle row is divided into two columns. The column on the left is the public wiki page for a race of creatures known as Fieldfolk. The path to the file is ~/vimwiki/Fieldfolk.wiki and that page has one visible link to a second public wiki page where the link text is Cede.

The column on the right has line numbers showing, lines 1 to 5. The cursor is on the middle of a link in line three, on the pipe | character that separates the link on the left from the link text on the right. This is an example of the private wiki linking to the public wiki (the Fieldfolk.wiki page in the left column). The file is in the private wiki as shown by the path ~/private/index.wiki

The third, bottom, and final row has a link to the diary of the private wiki, which I'm using as a "Gamemaster's journal for raw notes." The path to the file is ~/private/diary/2016-07-31.wiki and the file has been modified but not saved (as indicated by the plus sign to the right of the file path name). I've also mis-spelled the word "vegepygmy" to show that the spell check is working and has highlighted the mistake.

I used to keep all the reference details for my campaign, something like three hundred names, places and events, in a wiki contained as a separate single HTML file stored on a jump drive. This worked until the browser vendor tightened security and prevented the javascript of the wiki HTML file from working on one OS platform. I moved everything to vimwiki and never regretted it.

References

1. vimwiki cheatsheet
2. Getting started with Vimwiki