Command Line – Vimwiki

Wikis have been a mainstay of free software development ever since they were first developed by Ward Cunningham in 1994. Today, they are best-known from sites like Wikipedia. As a collection of notes, to-dos, announcements, or even journals, a wiki remains ideal for project development, whether for a group or for an individual. Vimwiki [1] is a simple but effective wiki engine, flexible in its choice of markup and relatively quick to learn once it is set up.

Like other Vim add-ons, Vimwiki's installation depends on what plugin manager, if any, you use. Vimwiki's GitHub page offers a summary of all the different ways to install it [2]. However, one of the easiest ways is to install a Vim package and then generate the help tags:

git clone https://github.com/vimwiki/vimwiki.git ~/.vim/pack/plugins/start/vimwiki
vim -c 'helptags ~/.vim/pack/plugins/start/vimwiki/doc' -c quit

All of the installation methods require that your home directory include a .vimrc file with the following lines:

set nocompatible
filetype plugin on
syntax on

These lines enable Vimwiki's integration into Vim. Whichever installation method you choose, you can confirm a successful installation by entering

:help vimwiki

to display the online help. While you have the online help displayed, you can do yourself a favor by reading the help before you begin using Vimwiki (Figure 1).

Figure 1: Vimwiki comes with extensive help.

In addition to the .vimrc file, you need to know the leader key that prefaces each keybinding. If you do not know the leader key, you can read it by using the command

:echo mapleader

to display the leader key in the lower left corner. Many distributions like Debian ship with the leader key undefined, so you can set it with:

:let mapleader="KEY"

The leader can be any key, but popular ones are a comma (,) or backslash (\).

Note: If you are less experienced with Vim, remember that commands are entered in Vim by pressing the Esc key to switch into command mode and then preface each command with a colon (:). You can quit Vim with the command q! or with wq if you want to save what you have just written.

Getting Started

A vital piece of information that is missing from most Vimwiki documentation is how to start working with it. However, the solution is simple once you know it. The first time you use Vimwiki, enter the command:

vim -c VimwikiIndex

and press the y key to create the Vimwiki directory in your home directory. To add an additional page to your wiki, do the following steps:

1. Enter a name for it on the index page.
2. Move the cursor to the start of the first word of the name.
3. Press the Enter key to create a Vimwiki link around the first word. The link is indicated by double square brackets.
4. Press the Enter key a second time to create a new blank buffer where you can enter information for the new page. Each page can contain its own subpages, but the structure will be easier to remember if no more than three levels are used. Each page can also be added to the index.
5. Save the new page.
6. Press the Backspace key to return to the index.
7. Repeat as needed.

Alternatively, to make a link that contains multiple words, press the v key to enter Vim's visual mode, and select the words for the link and press Enter.

Multiple wikis can exist as subdirectories of the same directory by defining each in .vimrc, giving each a unique number and name, a file extension, and – if desired – specifying the syntax used (see the "Syntax Types" section). For example, if you have two wikis, one for work and one for personal projects, such as:

let wiki_1 = {}
let wiki_1.path = '~/vimwiki_work/'
let wiki_1.syntax = 'default'
let wiki_1.ext = '.wiki'
let wiki_2 = {}
let wiki_2.path = '~/vimwiki_personal/'
let wiki_2.syntax = 'markdown'
let wiki_2.ext = '.md'

You should follow the above lines with:

let g:vimwiki_list = {'path': '~/vimwiki/'}

to tell Vimwiki to list the wikis.

If all wikis use Markdown or MediaWiki, instead of specifying the syntax for each one, you can save time by using a single line, such as this one for defaulting to Markdown:

let g:vimwiki_ext2syntax = {'.md': 'markdown'}

Once the wikis exist, you can navigate and edit them using the basic commands shown in Table 1. For a full list of commands, see the Vimwiki help.

Another built-in Vimwiki feature is the diary section. A new entry for the current day can be generated with the command :<Leader>w<Leader>w. All diaries can be organized with an index with the command :VimwikiDiaryGenerateLinks or :<Leader>w<Leader>i. If you install calendar.vim and add the option to .vimrc, you can create an entry for a date by selecting it from the calendar [3].

Syntax Types

Vimwiki supports three markup languages: its own default syntax, Markdown [4], and MediaWiki [5]. All three are similar in structure. In fact, Vimwiki's default and MediaWiki are almost identical. Both, for instance, start and end a first-level heading with an equal sign (=) and bold text with an asterisk (*). By contrast, Markdown indicates a first-level heading with a number sign (#) and bold text with two asterisks (**). However, in many ways, all three have similar structures, such as indicating a second-level heading with two of the characters that indicate a first-level heading. This similar but different structure can make which syntax you are using easy to forget, so in most cases users should stick to a single syntax in their wikis to avoid typing nonsense. Unless you need compatibility with another application, this single syntax should probably be Vimwiki's default – if for no other reason than it is the only one that has built-in export to HTML via the command :VimwikiAll2HTML. The other two require an external export tool [6].

Listing 1 shows examples of Vimiwiki's basic default syntax. Figure 2 shows that some tags are color-coded. There are many other choices, including some specialized ones, that are listed using the command:

:h vimwiki-syntax

= Header1 =
== Header2 ==
=== Header3 ===
*bold* -- bold text
_italic_ -- italic text
[[wiki link]] -- wiki link
[[wiki link|description]] -- wiki link with description
* bullet list item 1
    - bullet list item 2
        * nested bullet list item
1. numbered list item 1
    a) nested numbered list item

Figure 2: A sample of Vimwiki's default syntax with color-coding.

In addition to the syntax, some keywords are formatted automatically to emphasize them, such as TODO, DONE, STARTED, FIXME, and FIXED. You can also create a table using the command:

:VimwikiTable COLUMNS ROWS

For example, VimwikiTable 3 3 produces the following:

|   |   |   |
 |---|---|---|
 |   |   |   |
 |   |   |   |

The top row is the table heading. Similar to most computer-generated tables, you can press the Shift key to move around the table. Pressing Enter will create a new row.

Other Features

Vimwiki also includes numerous advanced features – too many to be mentioned here. They include such features as custom keybinding, folding lists to temporarily hide some items, and adding comments and placeholders. Most of these features involve adding lines to .vimrc to enable them.

However, Vimwiki's setup and the structuring of a wiki is enough to keep most users busy for a while. Unlike many Vim plugins, Vimwiki is much more than a simple add-on. Rather, it is a program in its own right, as complicated as many other engines for personal wikis.

Admittedly, the initial setup can be difficult, especially for those unfamiliar with Vim. But once Vimwiki is set up, the keybindings and syntax are easy to learn. Because Vimwiki runs from the command line, you have a wiki engine that is faster than most. As an advantage, you can use Vimwiki almost entirely without your fingers leaving the keyboard – the sole exception being when you switch into visual mode to create a link for multiple words. These are significant advantages and more than enough reasons to explain why, for many, Vimwiki is a major reason for running Vim.