Vimwiki for Personal Wiki Site

Vimwiki is great (neo)vim plugin to crate a personal wiki site. I use it for daily note taking, blogging and documentations.

Prerequisite

Vimwiki is a open source plugin for Vim or NeoVim. To install and use Vimwiki, all you will need is have Vim or NeoVim installed on your machine.

Personally, I'm using NeoVim on my Windows 10 desktop. The plugin management tool I'm using for NeoVim is Packer. And I've converted or my NeoVim configuration files to Lua.

Install and Configuration

Following the instructions in Vimwiki's Github page (opens new window), I simply included the following line in my plugins.luafile and then ran PackerInstallto install the plugin.

use {'vimwiki/vimwiki'}

To fit in my daily workflow, I customized the tool in the following ways.

1. Use the markdown syntax instead of the default vimwiki syntax. I never used the default wiki syntax and feel more comfortable just using the markdown. So I changed the syntax option in my settings.lua file.

vim.cmd("let g:vimwiki_list = [{'path': '~/vimwiki/', 'syntax': 'markdown', 'ext': '.md'}]")

2. I previously installed the Edge/Chrome extension Markdown Viewer (opens new window) to easily preview all my markdown files. I bind the preview function to F5 in my settings.lua file.

vim.cmd "autocmd BufEnter *.md noremap <F5> :!start msedge %:p<CR>"

3. I changed the default keybindings for vimwiki using TAB and Shift-TAB to cycle through links in a page. Now I remapped them to Alt-j and Alt-k. The main reason is I want to keep using TAB key for my auto completion plugin. The following lines were added to my vimwiki.vim file in the ftplugin folder.

nmap <A-j> <Plug>VimwikiNextLink
nmap <A-k> <Plug>VimwikiPrevLink

4. Finally I added customized shortcuts in my which-key configuration file.

    w = {
        name = '+VimWiki',
        ct = {'<cmd>VimwikiTable<CR>', 'Create Table'},
        co = {'<cmd>VimwikiTOC<CR>', 'Create Table of Contents'}
    },

Main Features

I just started using Vimwiki so many of the features are yet to be explored. So far, I find the following features extremely useful:

• Well integrated with NeoVim which is my go-to text editors now.
• Easy to add links between different wiki pages (Just hit Enter). And easy to navigate between different pages (Enter to go to the link and Backspace to return).
• Fully support markdown syntax and if I want I can use the html tags to decorate my page.

It seems all the wiki pages will be stored in a single folder by default. Buy you can always create any folder structures by editing the auto-generated links.

Known Issues

1. The auto-generated links didn't include the .md extension. You will need to manually add it if you want to keep the same link when viewing in your browser.

Updates: the following configuration in the settings.lua will fix this issue. vim.g.vimwiki_markdown_link_ext = 1

2. Link generation works out in most cases but I noticed when I have certain special characters such as "-" in my link text, it will somehow modify the text. It is a little annoying but not a big deal to me.
3. I can't absolute path for links on this windows machine. Tried use local: and file: as indicated in the help file but neither of them worked. The buffer will freeze and I have to kill the process.