How I use vimwiki in neovim

This post is currently in-progress, and is more of a brain-dump right now. But I like to share as often as I can otherwise I’d never share anything 🙂

Please view the official Vimwiki Github repository for up-to-date details of Vimwiki usage and installation. This page just documents my own processes at the time.

Installation

Add the following to plugins.lua

use "vimwiki/vimwiki"

Run the following two commands separately in the neovim command line:

:PackerSync
:PackerInstall

Close and re-open Neovim.

How I configure Vimwiki

I have 2 separate wikis set up in my Neovim.

One for my personal homepage and one for my commonplace site.

I set these up by adding the following in my dotfiles, at the following position: $NEOVIM_CONFIG_ROOT/after/plugin/vimwiki.lua. So for me that would be ~/.config/nvim/after/plugin/vimwiki.lua.

You could also put this command inside the config function in your plugins.lua file, where you require the vimwiki plugin. I just tend to put all my plugin-specific settings in their own “after/plugin” files for organisation.

vim.cmd([[
  let wiki_1 = {}
  let wiki_1.path = '~/vimwiki/website/'
  let wiki_1.html_template = '~/vimwiki/website_html/'
  let wiki_2 = {}
  let wiki_2.path = '~/vimwiki/commonplace/'
  let wiki_2.html_template = '~/vimwiki/commonplace_html/'
  let g:vimwiki_list = [wiki_1, wiki_2]
  call vimwiki#vars#init()
]])

The path keys tell vimwiki where to plave the root index.wiki file for each wiki you configure.

The html_template keys tell vimwiki where to place the compiled html files (when running the :VimwikiAll2HTML command).

I keep them separate as I am deploying them to separate domains on my server.

When I want to open and edit my website wiki, I enter 1<leader>ww.

When I want to open and edit my commonplace wiki, I enter 2<leader>ww.

Pressing those key bindings for the first time will ask you if you want the directories creating.

How I use vimwiki

At the moment, my usage is standard to what is described in the Github repository linked at the top of this page.

When I develop any custom workflows I’ll add them here.

Deployment

Setting up a server to deploy to is outside the scope of this post, but hope to write up a quick guide soon.

I run the following command from within vim on one of my wiki index pages, to export that entire wiki to html files:

:VimwikiAll2HTML

I then SCP the compiled HTML files to my server. Here is an example scp command that you can modify with your own paths:

scp -r ~/vimwiki/website_html/* your_user@your-domain.test:/var/www/website/public_html

For the best deployment experience, I recommend setting up ssh key authentication to your server.

For bonus points I also add a bash / zsh alias to wrap that scp command.

General plugins I use in Neovim

I define a “general plugin” as a plugin that I use regardless of the filetype I’m editing.

These will add extra functionality for enhancing my Neovim experience.

I use Which-key for displaying keybindings as I type them. For example if I press my <leader> key and wait a few milliseconds, it will display all keybindings I have set that begin with my <leader> key.

It will also display any marks and registers I have set, when only pressing ' or @ respectively.

use "folke/which-key.nvim"

Vim-commentary makes it super easy to comment out lines in files using vim motions. So in normal mode you can enter gcc to comment out the current line; or 5gcc to comment out the next 5 lines.

You can also make a visual selection and enter gc to comment out that selected block.

use "tpope/vim-commentary"

Vim-surround provides me with an extra set of abilities on text objects. It lets me add, remove and change surrounding elements.

For example I can place my cursor over a word and enter ysiw" to surround that word with double quotes.

Or I can make a visual selection and press S" to surround that selection with double quotes.

use "tpope/vim-surround"

Vim-unimpaired adds a bunch of extra mappings that tpope had in his own vimrc, which he extracted to a plugin.

They include mappings for the [ and ] keys for previous and next items. For example using [b and ]b moves backwards and forwards through your open buffers. Whilst [q and ]q will move you backwards and forwards respectively through your quickfist list items.

use "tpope/vim-unimpaired"

Passive plugins I use in Neovim

These plugins I use in Neovim are ones I consider “passive”. That is, they just sit there doing their thing in the background to enhance my development experience.

Generally they wont offer extra keybindings or commands I will use day to day.

You can view all the plugins I use in my plugins.lua file in my dotfiles.

Vim-lastplace will remember the last edit position of each file you’re working with and place your cursor there when re-entering.

use "farmergreg/vim-lastplace"

Nvim-autopairs will automatically add closing characters when opening a “pair”, such as {, [ and (. It will then place your cursor between the two.

use "windwp/nvim-autopairs"

Neoscroll makes scrolling smooth in neovim.

use "karb94/neoscroll.nvim"

Vim-pasta will super-charge your pasting in neovim to preserve indents when pasting contents in with “p” and “P“.

use({
  "sickill/vim-pasta",
  config = function()
    vim.g.pasta_disabled_filetypes = { 'fugitive' }
  end,
})

Here I am passing a config function to disable vim-pasta for “fugitive” filetypes. “Fugitive” is in reference to the vim-fugitive plugin that I will explain in another post.

Nvim-colorizer will highlight any colour codes your write out.

use "norcalli/nvim-colorizer.lua"

How I use Neovim

I try to use Neovim for as much development-related work as possible.

This page serves as a point of reference for me, and other people interested, for what I use and how I use it.

Feedback is welcome and would love to know how you use Neovim too!

My complete Neovim configuration files can be found on Github.

  1. How I organise my Neovim configuration
  2. Passive plugins I use in Neovim
  3. General plugins I use in Neovim
  4. Development plugins I use in Neovim – coming soon
  5. Database client in Neovim (vim-dadbod and vim-dadbod-ui) – coming soon
  6. REST client in Neovim (vim-rest-client) – coming soon
  7. Personal Wiki in Neovim (vim-wiki) – coming soon