A personal wiki for the command line
Command Line – Vimwiki

© Lead Image © Nmedia, Fotolia.com
Vimwiki, a Vim add-on, offers a simple and effective command-line wiki with a choice of markup languages.
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).

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:
- Enter a name for it on the index page.
- Move the cursor to the start of the first word of the name.
- Press the Enter key to create a Vimwiki link around the first word. The link is indicated by double square brackets.
- 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.
- Save the new page.
- Press the Backspace key to return to the index.
- 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.
Table 1
Navigating Wikis
[number] <leader> wt |
Open wiki index file in new tab |
:<leader> ws |
List and select available wikis |
:<leader> wd |
Delete current wiki page |
:<leader> wr |
Rename current wiki page |
:<Enter> |
Follow/create wiki link |
:<Tab> |
Find next wiki link |
:<Shift-Tab> |
Find previous wiki link |
:<Backspace> |
Return to previous wiki link |
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
Listing 1
Basic Default 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

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.
Infos
- Vimwiki: http://vimwiki.github.io/
- Installation: https://github.com/vimwiki/vimwiki#commands
- calendar.vim: http://www.vim.org/scripts/script.php?script_id=52
- Markdown summary: https://www.markdownguide.org/cheat-sheet
- MediaWiki summary: https://www.mediawiki.org/wiki/Help:Formatting
- External export tools: https://vimwiki.github.io/vimwikiwiki/Related%20Tools.html#Related%20Tools-External%20Tools
Buy this article as PDF
(incl. VAT)
Buy Linux Magazine
Direct Download
Read full article as PDF:
Price $2.95
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters
News
-
An All-Snap Version of Ubuntu is In The Works
Along with the standard deb version of the open-source operating system, Canonical will release an-all snap version.
-
Mageia 9 Beta 2 Ready for Testing
The latest beta of the popular Mageia distribution now includes the latest kernel and plenty of updated applications.
-
KDE Plasma 6 Looks to Bring Basic HDR Support
The KWin piece of KDE Plasma now has HDR support and color management geared for the 6.0 release.
-
Bodhi Linux 7.0 Beta Ready for Testing
The latest iteration of the Bohdi Linux distribution is now available for those who want to experience what's in store and for testing purposes.
-
Changes Coming to Ubuntu PPA Usage
The way you manage Personal Package Archives will be changing with the release of Ubuntu 23.10.
-
AlmaLinux 9.2 Now Available for Download
AlmaLinux has been released and provides a free alternative to upstream Red Hat Enterprise Linux.
-
An Immutable Version of Fedora Is Under Consideration
For anyone who's a fan of using immutable versions of Linux, the Fedora team is currently considering adding a new spin called Fedora Onyx.
-
New Release of Br OS Includes ChatGPT Integration
Br OS 23.04 is now available and is geared specifically toward web content creation.
-
Command-Line Only Peropesis 2.1 Available Now
The latest iteration of Peropesis has been released with plenty of updates and introduces new software development tools.
-
TUXEDO Computers Announces InfinityBook Pro 14
With the new generation of their popular InfinityBook Pro 14, TUXEDO upgrades its ultra-mobile, powerful business laptop with some impressive specs.