👩‍💻 chrismanbrown.gitlab.io

vimwiki

how and why i use vimwiki for keeping notes and tracking tasks

2022-01-21

Contents

  1. Introduction
  2. Motivation
  3. Installing
  4. Configuring
  5. Syntax
  6. Cheatsheet
  7. Tasks
  8. Searching and References
  9. Methodology
  10. Diary
    1. Daily Log
    2. Weekly Review
  11. Conclusion

Introduction

I recently started a new chapter in my work life and have decided that this is an opportune time to recommit to using vimwiki to keep track of tasks and notes. I’ve messed around with it in the past, but it didn’t really stick. But I think I now have both the setup and the understanding of the tool to stick with it this time.

Motivation

I’m a big note-taker.

I maintain several different blogs mainly just as places to house my personal note-taking on niche subjects. I maintain a personal knowledge base of notes and bookmarks and references. I have +16k words of notes for my D&D campaign alone. Etc. You get the picture.

The one place, for some reason, that I haven’t been as obsessive with note-taking is at work. Don’t get me wrong, I take meeting notes and one-on-one notes, and I share summaries via email after meetings. That kind of stuff, I’m good.

But I haven’t been able to keep up any kind of reflective journaling at work, which is one of the main ways that I learn and grow. And I haven’t really successfully used any kind of todo list or task management system outside of jira or whatever we happen to be using to track individual pieces of work for a project.

I’d like something a little more holistic and a little more personal.

Installing

I use the Plug plugin manager, so I added the following line to my list of plugins:

Plug 'vimwiki/vimwiki'

…and then run :PlugInstall.

Configuring

This is the vimwiki configuration in my vimrc.

"" vimwiki {{{2
"""""""""""""""
let g:vimwiki_global_ext = 0
let g:vimwiki_listsyms = '✗○◐●✓'

" knowledge = my personal knowledge wiki
let wiki1 = {}
let wiki1.name = 'knowledge'
let wiki1.path = '~/knowledge'
let wiki1.auto_toc = 1
let wiki1.syntax = 'markdown'
let wiki1.ext = '.md'
let wiki1.index = 'Home'

" work wiki
let wiki2 = {}
let wiki2.name = 'work'
let wiki2.path = '~/vimwiki'
let wiki2.auto_toc = 1

let g:vimwiki_list = [ wiki1, wiki2 ]

I have two wikis. My aforementioned personal knowledge database, and my new work wiki.

vimwiki provides tools for managing multiple wikis effectively, such as a <Leader>ws command to open a wiki selection UI, and more.

Syntax

This is probably the best place for me to address what is probably the biggest downside to vimwiki, and it’s a kind of minor one at that.

It has its own markup syntax.

It’s markdown-ish, but headers, links, and bold and italics, among other things, are different.

You can set it up to work with markdown, as you can see I did with wiki1 above. But markdown support is incomplete: you can’t export to HTML if your wiki is in markdown.1

When I first tried using vimwiki, I already had an extensive collection of markdown files in my knowledge base, and I was tacking vimwiki on top of it to test drive it. At the time, I didn’t feel like it brought that much to the table, so I stopped using it.

For my new work wiki, I decided to embrace the defaults and use the vimwiki syntax and the default .wiki filetype.

It’s not even an issue really. I don’t use emphasis in my own notes if I’m not writing for the web. I can’t even tell you what the syntax is for italics, bold, etc. Headers look like == this == and are not annoying at all. There’s a keyboard shortcut for increasing and decreasing header level, so you don’t even have to type out the syntax if you don’t want to. Same for linking, which makes sense because that’s one of the primary features of a wiki: you just press Enter on a word and it either creates a new link or follows an existing link. You rarely have to type out the syntax. (It looks like [[this]].)

So yeah, the syntax is not markdown. But it hardly matters to me in practice. The syntax really seems to just get out of the way and allow me to type. Probably more so that markdown does, honestly.

Cheatsheet

Here’s a quick cheatsheet

Opening your wiki:

Diary:

Linking and navigating:

Tasks

Tracking tasks is one of the main things I use vimwiki for, but it works so well that there’s not really much to say about it.

You just make a list item

And then you can C-space on it to mark it as complete or incomplete.

If tasks are nested, then completing child tasks progressively marks the parent task as more and more complete, which I think is neat. So you get feedback on when a parent task is one-quarter, half, or three-quarters complete.

You can customize these markers as you can see I did in my config above.

See more about how I use task lists in methodology.

Searching and References

Two things I feel more confident about now after spending some time in :help vimwiki are searching and references.

When I tried vimwiki before, I had a lot of tasks and todos spread across many files, and I never felt all the way sure that I wasn’t letting something slip by. But now I know that the :VimwikiSearch commands can let me do stuff like :VWS - \[x\] to open a location list of all incomplete tasks.

And I also never felt like I had a good way to figure out “what links here”, but now know that :VWB (short for :VimwikiBacklinks) does just that. It too populates a location list so you can jump around the references.

Methodology

At this point my workflow is sort of a mix of Getting Things Done, with which I was briefly obsessed in the 2000s, and bullet journal, with which I was briefly obsessed in the 2010s.

My main page has the following sections:

  1. General: kind of a “main nav” section with links to pages like Jargon (acronyms, abbreviations, and jargon unique to the company or project), You (stuff related directly to my position, career growth, and goals), and other things.

Tasks:

  1. Todo: a backlog of things I gotta get done

  2. In Progress: what it says on the tin

  3. Done: I don’t delete things from my todo list. I migrate the items to ‘Done’ and timestamp them, and maybe add a followup note or two, so I have a list of accomplishments

  4. Waiting On: move tasks here when I’m blocked by somebody/something. Follow up on these at an appropriate cadence.

  5. Follow Up: uh-oh, people are waiting on me! Better get back to them quick!

Other Indices and Lists:

  1. Tags: A generated list of all tags. This is something I’m using now that I hadn’t used in the past. I can tag meetings with project names or with :one-on-one: or whatever. Then I can generate a list of all tag links, and see what’s where.

  2. Projects: an index of project pages a la bullet journal. Obviously the actual project(s) I’m working on go here, but also anything else that stands on its own as a context like Book Club or Front End Guild. Any standalone recurring meeting is probably a Project.

  3. Someday/Maybe: kind of a junk drawer of ideas and stuff for the future.

Diary

Most of my interaction with my wiki happens in the diary. Namely in the daily log, and the weekly review.

Daily Log

Every morning, I open up and skim yesterday’s diary page for unfinished tasks or anything else that needs to be carried over. Then create a new page for today.

Look at my calendar, and create a page section for each meeting and maybe jot down a few notes ahead of time so I am ready.

Throughout the day, fill in time between meetings with notes about what I’m working on. Good notes document a process or something I’ve learned or something I’m stuck on. Lacking anything interesting, at minimum log number of hours or pomodoros, etc, spent on a task.

At the end of the day, create a new summary section at the top of the page and surface highlights for skimming later. Tag content as necessary. Open tomorrow’s diary page and carry over any notes or unfinished tasks.

At the end of the week, it is time for the weekly review, in which I look back on the week, reading the daily summaries, and reflect on what I accomplished and what still needs doing.

Weekly Review

The weekly review happens every Friday morning, and happens at the bottom of that day’s daily log.

It gets a :review:weekly-review: tag (you can chain tags like that: :one:two:) so I can find all my reviews quickly later when I, say, want to do a monthly review.

In my weekly review, I usually make the following sections:

Conclusion

vimwiki is surprisingly robust and powerful. It has a ton of features that I didn’t touch on here like dynamic tables, and metadata and templating for exporting HTML pages, and more.

:help vimwiki is a treasure trove of information. I feel like I’ve only scratched the surface of what it can do, but I also feel like with just what I’ve got so far, I’m going to be a lot more productive and successful.

I think I’m going to enjoy bringing a little more journaling into my work life. Writing is hugely important to me for organizing my thoughts and making realizations and making connections.


  1. You can. But it’s still not supported. https://gist.github.com/enpassant/0496e3db19e32e110edca03647c36541↩︎