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