A personal wiki for the command line
Command Line – Vimwiki
![© Lead Image © Nmedia, Fotolia.com © Lead Image © Nmedia, Fotolia.com](/var/linux_magazin/storage/images/issues/2020/241/quick-wiki/po-20709-fotolia-nmedia_fotolia-webspace_resized.png/777564-1-eng-US/PO-20709-Fotolia-Nmedia_Fotolia-Webspace_resized.png_medium.png)
© 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).
![](/var/linux_magazin/storage/images/issues/2020/241/quick-wiki/figure-1/777567-1-eng-US/Figure-1_large.png)
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
![](/var/linux_magazin/storage/images/issues/2020/241/quick-wiki/figure-2/777570-1-eng-US/Figure-2_large.png)
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
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters
Support Our Work
Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.
![Learn More](https://www.linux-magazine.com/var/linux_magazin/storage/images/media/linux-magazine-eng-us/images/misc/learn-more/834592-1-eng-US/Learn-More_medium.png)
News
-
Endless OS 6 has Arrived
After more than a year since the last update, the latest release of Endless OS is now available for general usage.
-
Fedora Asahi 40 Remix Available for Macs with Apple Silicon
If you've been anticipating KDE's Plasma 6 for your Apple Silicon-powered Mac, then you're in luck.
-
Red Hat Adds New Deployment Option for Enterprise Linux Platforms
Red Hat has re-imagined enterprise Linux for an AI future with Image Mode.
-
OSJH and LPI Release 2024 Open Source Pros Job Survey Results
See what open source professionals look for in a new role.
-
Proton 9.0-1 Released to Improve Gaming with Steam
The latest release of Proton 9 adds several improvements and fixes an issue that has been problematic for Linux users.
-
So Long Neofetch and Thanks for the Info
Today is a day that every Linux user who enjoys bragging about their system(s) will mourn, as Neofetch has come to an end.
-
Ubuntu 24.04 Comes with a “Flaw"
If you're thinking you might want to upgrade from your current Ubuntu release to the latest, there's something you might want to consider before doing so.
-
Canonical Releases Ubuntu 24.04
After a brief pause because of the XZ vulnerability, Ubuntu 24.04 is now available for install.
-
Linux Servers Targeted by Akira Ransomware
A group of bad actors who have already extorted $42 million have their sights set on the Linux platform.
-
TUXEDO Computers Unveils Linux Laptop Featuring AMD Ryzen CPU
This latest release is the first laptop to include the new CPU from Ryzen and Linux preinstalled.