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.
- vimwiki
- The plugin vimdoc on github:
:help vimwiki
- The vim theme in the gifs is Gruvbox.