You (probably) don’t need Vimwiki
Why are you using Vimwiki?
Probably to make notes, right?
Well did you know that you don’t need a plugin for this?
Of course you did!
Let’s go through some of Vimwiki’s features and dispel them in place of vim
alternatives. Vimwiki states the following features:
1. Organise notes and ideas
When I used to use Vimwiki, I loved the ability to link files to each other but
I have two letters for you;
gf allows you to edit the file under the
cursor (assuming it’s in your path). (see
With a sensible directory structure, you can easily organise your notes and
ideas. Take a look at my repo and come
back here when you’re done. That repository is just a dumping ground of
articles that I may or may not write at some point but the point is, it’s
entirely navigable with vim. The directory structure is:
README.md is the ‘entrypoint’ that most devs would open up straight away and
contains a link to our main page,
index.md is just a table of contents hyperlinking to all other articles and
looks like this:
- article-1.md - A description of what article-1 is
- article-2.md - A description of what article-2 is
- article-3.md - A description of what article-3 is
- article-4.md - A description of what article-4 is
(this can be generated from within vim by going into insert mode and doing
From here, you can easily browse articles by pressing
gf to edit the file
your cursor is on.
I usually use the jumplist (
:help jumplist for more) to
go back and forth between the article and index page.
2. Manage todo lists
I am a fan of todo lists but that is one thing that I do not use vim for.
There’re a few different kinds of TODO lists, and I treat them differently:
TODOs in code
There are two approaches I take to this:
1) Make your TODO a github issue (The formal approach).
This allows everyone to see it and I find the best and easiest way to track
things. It’s what I do with all of my projects. (Here’s an
If you’re averse to issue tracking, you can still track them in a separate file
if that’s what you’re into.
grep -Ri todo . > todos
2) Scatter TODOs everywhere and consolidate afterwards (The informal approach).
If you have TODOs such as
// TODO make this polymorphic, then the easiest
thing you can do to consolidate these is just grep for them in your project.
(Your mileage may vary depending on your grepprg, see
TODOs in life
I am a big fan of todo lists and mine are constantly changing. So much so that
having them in a versioned text file would be impractical, for this I use Google
Keep (I have moved away from it many times but always find myself coming back to
If you’re adamant on using Vim, I like a good old fashioned bulleted list and
- Pay bills
- Write "You don't need Vimwiki article"
To me though, this just sounds awkward.
3. Write documentation
There are two thoughts that go through my mind with this one:
1) You can easily write documentation in any editor,
you don’t need Vimwiki or anything else.
Infact, I’m not sure what Vimwiki brings to the table here (Ironically, there was nothing in their documentation).
2) I would prefer something built for this purpose such as readthedocs
I have since read a comment on
that sparked my interest on using Vim’s built-in help system as a documentation
system. This works perfect for me (so far) but I imagine
if you are working within a team, you’d want to use something more ubiquitous
and user friendly.
4. Maintain a diary
Ok, Vimwiki wins here, I have no idea how you’d do this without too many lines of vimscript.
5. Export everything to HTML
Again, two points here:
1) The entire point of markdown is that it’s easily editable and readable as is,
write your notes in markdown and you won’t even need to render it to HTML.
2) If you want to render stuff to HTML, just use pandoc its entire purpose
is converting files from one format to another and will do what you need here.
A mapping to convert the current markdown file to HTML could look like:
nnoremap <leader>r :!pandoc % --to=html5 > %.html
Vimwiki boasts that you can ‘tag’ pages, well, this is pretty easy depending on
how you want to do it.
You could either tag pages on the index page, or on the post itself.
If we were to tag our index page, it might look like this
- article-1.md - A description of what article-1 is [programming]
- article-2.md - A description of what article-2 is [vim, programming]
- article-3.md - A description of what article-3 is [sql]
- article-4.md - A description of what article-4 is [programming]
Then you can just use
lvimgrep to search for your tags.
In our case, looking for the
vim tag would look like:
lvimgrep '\[vim.*\]' %
And now we have all pages tagged
vim in our location list and we can
gf to the article in that location list.
Alternatively, if you’re going the ‘vim help’ route, then you have a built-in
tag system at your finger tips! (See
This is too much work
If you think all of what I’ve said is just the hard way around, then continue using Vimwiki.