vimwiki
how and why i use vimwiki for keeping notes and tracking tasks
2022-01-21
Contents
- Introduction
- Motivation
- Installing
- Configuring
- Syntax
- Cheatsheet
- Tasks
- Searching and References
- Methodology
- Diary
- 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:
<Leader>ws: āwiki selectā. You only really need to use this if you have more than one wiki.
<Leader>ww: open the index page of your wiki
<Leader>wt: open your wiki in a new tab. I donāt really ever use tabs, but I can appreciate the use case of being deep in work and wanting to quickly log something or look something up, and just quickly opening the wiki in a tab instead of doing what I would do and just pop open a new tmux window.
Diary:
<Leader>w <Leader>w: open a ādiaryā page for today. I use this for all my daily notes, most of which I then later migrate to other pages.
<Leader>wi: Open the diary index page.
<Leader>w <Leader>i: reindex the diary page (when youāre on the diary index page.)
<Leader>w <Leader>y: Open yesterdayās diary page
<Leader>w <Leader>m: Open toMorrowās diary page
Linking and navigating:
<Enter> (Normal mode, cursor on a word): Turn a word or selection into a link
<Enter> (Normal mode, cursor on a link): Follow a link
<Backspace> (Normal mode, after following a link): Go back to the parent page
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
- like this
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:
- 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:
Todo: a backlog of things I gotta get done
In Progress: what it says on the tin
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
Waiting On: move tasks here when Iām blocked by somebody/something. Follow up on these at an appropriate cadence.
Follow Up: uh-oh, people are waiting on me! Better get back to them quick!
Other Indices and Lists:
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.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.
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:
People: who did I meet, or meet with? How are my relationships doing? Do any of my people need extra support? Is there any conversation Iām avoiding that I need to have?
Process: Think about my tools and processes. Can some process be made more efficient, or even removed? Do I need to invest some time in becoming better with my tools?
Product: How is the health of the thing Iām working on?
Learning: What did I learn this week? What did I accomplish?
Opportunities/Goals: Where can I improve? What can I do next week in order to improve?
Coming up: Scan next weekās agenda. Create some quick notes if you can. E.g., if I see I have a one-on-one Monday morning, go jot down some questions and stuff now. Take a look at that Someday/Maybe list. Is it time to start on one of those tasks?
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.