Intro
I'm always on a quest for a better organizational system. I've oscillated wildly between walled garden apps (after seeing the power of Omnifocus) to just plain text todo lists after the style of todo.txt.
While I seem to have temporarily settled on a combination different apps and techniques to record and organize my life... I am never satisfied. I have always been intrigued by the organizational power of Emacs' Orgmode, but as I refused to give up on my Vim modal superpowers, it never made sense to have my organization in one full featured editor and my work in another. (Although I certainly tried!) Several months ago I was browsing through someone's vimrc and I discovered a link to vimwiki. Vimwiki promised a simple but powerful personal wiki that would allow me to build an organizational system inside my favorite editor, right alongside my work and code.
I have been using it happily for a few months now and I think I'm hooked, it has become indispensable to my daily productivity. I presently use it:
- To keep up with a nested contextual todo list (more on this later).
- To maintain a daily journal of meeting notes and context for decisions.
- To write documentation and blog posts
- To store semi-permantly smalls scripts and scratch documents related to projects.
Setup
I have Vimwiki setup using the following lines in my .vimrc or init.vim if you are rocking Neovim:
" vimwiki/vimwiki
let g:vimwiki_list = [{'path': '~/vimwiki/', 'syntax': 'markdown', 'ext': '.md'}]
It sets up Vimwiki in my home directory and uses the optional markdown syntax
instead of the default
Mediawiki syntax. I write a
lot of markdown documents, my Middleman blog takes markdown documents, and my
email client will let me use markdown, my Github code reviews and gists support
markdown, so writing my wiki in markdown allows me to move content out of and
into my wiki more easily. I have the ~/vimwiki/ directory symlinked to
Dropbox for syncing between computers and backup. I suppose that I could
maintain a git repo for my wiki... I'm curious about what that'd be like for a
team.
Using the markdown mode will disable a few features (mostly exporting your wiki to HTML), but for my uses the trade-off is worth it.
Vimwiki has the ability to have maintain separate wikis if you need separation for different contexts, jobs, etc.
My Workflow
You bring up your current wiki's index with <leader>ww. At first, your brand
new wiki is a blank slate for you to define your organization system. Over
time mine has evolved into the one seen above.
I have a few things for helping me set my day in order and give me current
context, like the Scraps section, but for me the heart and soul of my wiki
is the awesome linked todo list.
Lists
Lists are a core part of any organizational scheme. To create a list you can use any list style supported by your syntax, unordered, bullets, etc. I typically use markdown's unordered lists.
You can transform any list item into an todo list item by pressing <C-Space>
in normal mode, or by adding the [ ] characters manually. After a list item
has been transformed into a todo item, you can press the same <C-Space> to
toggle it completed/uncompleted.
Nested items will update their parent with the percentage of their completion, as seen in the gif above. Vimwiki supports nested lists either manually through indentation, or if you end a todo list item with a colon, the following items will be indented automatically.
Links
Where the wiki concept comes into its own is the ability to make any text
into a link! You can either type the syntax for a link manually, or hit
<Enter> on any selection or word in Normal mode. When making the link, your
omnicomplete in vim will load any
documents that already exist.
(If you haven't played with Omnicomplete, it's <C-x><C-o>. You really should
play with it, it's awesome!)
Diary Pages
Vimwiki also has bindings to quickly create and view diary pages. This at first
seemed fairly useless to me, but now I can't live without them. By pressing
<Leader>w<Leader>w, you are taken to a page named for the current date.
I use this page to record notes on meetings, to store context copied from emails that has informed decisions, as a scratch page for random code snippets for discussion, regexes I found useful... the list goes on and on.
I make use of the Vimwiki tagging system (a word that begins and ends with a colon like :music:) in order to categorize things by meetings, notes, scraps, etc. Just like the links, the Vim omnicompletion system will listen to and complete your tags as well. I often will simply ripgrep/ack the whole folder.
If you press <Leader>wi, you will be taken to a special Diary Index page, and
by pressing <Leader>w<Leader>i you will generate an index of all your diary
pages, which will be titled by the first header in the file, or by the date...
very cool for answering the ever troublesome question: Just what exactly did I
do this week?
My Workflow
After spending some time in the system, I started to realize the power of the wiki system. As bland list items turn from upcoming reminders to projects that contain context, documents, and decisions, the list item becomes a link to a project hub page that starts to collect and organize nested todo items and information.
This blog post itself began as a todo list item. Then I then linked to this wiki page where I created a rough outline and started gathering notes. As I worked in Vimwiki, I'd occasionally remember a topic I wanted to include, and the rough outline started to be fleshed out with content and subsumed the todo list until it hosted the draft of the post itself. The todo list stayed a constant representation of my tasks and priorities, and the blog post went through a full planning/execution cycle on its own page. Super cool!
If a diary entry from a meeting or scrap is related to a task in my todo list, then I will use the linking system to make a link back and forth from the task to the diary that provides context.
For instance, recently I had a meeting where we discussed the priority of upcoming features. It was relatively involved, but I took notes in my diary. When the meeting was done, I reordered the priority of the todo items related to that project, with a link to the meeting notes for context. Weeks later, someone asked me why we chose to prioritize Project B over Project A, and I had all the documentation at my fingertips.
Conclusion
I hope this has been somewhat helpful, I feel that I have only scratched the surface of what Vimwiki is capable of. It has transformed my prose writing for documentation and blogging, because I can link the todo item directly to the draft of the document, and keep it tied to it. I can link to external files, webpages, and documents. I kind of want to try and write fiction in it. I could foresee being able to jump to a character's page and bio to keep track of their goals and motives, or jump out to a worldbuilding document. I'm pretty enamored at this point, and I hope it'll be helpful to you.
