Published on

Vimwiki or Why I Stopped Being Afraid and Learned to Love Vim


I have tried every means of keeping my notes organized available for Linux, after coming from Microsoft and being immensely frustrated with OneNote and its promise of me not even needing to worry that my notes were backed up to the cloud only to find (after hours of work) they were lying all along just as I suspected. Each option I explored was eliminated for one reason or another. Either the platform lacked the ability to save outside of its SQL database (which is great when using NextCloud but not for every possible thing) or it lacked some set of features or used a WYSIWYG editor that is far slower and more tedious to use than the Markdown I am so accustomed to writing it has become second nature.

I also discovered a concept I had been intellectually been yearning for since before I could string together coherent thought, the knowledge base, which essentially is a loosely connected 'mind map' way of organizing interrelated notes into what amounts to a wiki of sorts on things one knows. While hardly interested in recording precisely all of the little I actually know, I like the idea for recording technical knowledge I have been accumulating over the years in a format I can later reference and use for a sort of personal set of developer docs to give myself some clue as to what I was thinking when I did various things.

Yet software targeting this particular use case are no better than the notes style editors I have already given up hope on, or if they are (like they are clunky web applications running on the rather that hide most features behind a paywall. Knowledge management applications should be somewhat more fully featured than a semi-related set of directories contained in a user inaccessible SQL database but using the bulky system resources hog electron or its bigger, often bulkier, brethen that are web browsers also seems like significant overkill.

Then the Solution Rushes In: Vimwiki

While Obsidian Research and Foam for VSCode offer something like what I have wanted, they still didn't provide enough of the overall functionality I was hoping for, though Foam came closer than any others, I am still avoidant of anything to do with Redmond, regardless how they presently act and remember vendor lock in is one of their tactics. However, in researching it, I discovered much of this software was of course based on a terminal program that's decades old and I have always preferred for terminal editing: vim.

Yes there is the perfect solution to knowledge management available for vim, its been available for a while even and shaped many of these programs as it is source they are based on even: Vimwiki.

Essentially vimwiki is only providing a few extra features on top of a syntax for composing notes that can interlink to one another in whatever mode the user wants and derives its configuration from the user's vim configuration, which in order to fully realize this notetaking methodology, I was lucky enough to need to dive deeply into the process of configuring of course (more on this coming in a future post).

What this has enabled was all the features offers (since those features merely wrap html5 functionality and this uses Markdown due to my configuration of it specifically), which I have eschewed its own specific format and instead opted for Markdown for portability purposes, which renders within vim in such a way as to enable the seamless creation of notes in the heirarchical formating that I tend to think in, which is primarily enabled due to finely grained control as enabled by vim.

For my tech related notes, this means the arbitrary catalogues of information is stored in the same preportions as I think of it as being within, such as Linux vs. Web Development, which is all within nested subdirectories that begin as defined in my vim configuration in a .vimwiki directory that I have backed up on Dropbox and on Github, which is private for the time being while I work on getting more comprehensive notes in it and then I will render as a site for the world to see and easily referenced by yours truly such that I will not be impaired by clunky interfaces or bad user data business logic again!


As I mentioned already, I have my vimwiki set up to use Markdown, which I did not because I dislike vimwiki's markup language, its actually somewhat more expansive than Markdown, but because I find its much easier overall to use because its already a known markup that I already fully memorized and as such is somewhat less fussy to deal with for that reason alone.

This is enabled by a native option to vimwiki, no need to dive into vim scripting a plugin for it and due to the sheer number of people also opting for this option, there are plenty of examples with a bit of digging on sites like Github. It also enables an easier time using a live hosting script, which I can run out of the directory containing the repo, that uses a single index html file to render my many markdown files into a website if I want to reference the thing myself or in the build up to my releasing the site to public viewing. While I do have experience with Pandoc from the process of coming to vimwiki, which works just as well with vimwiki format (or Org-mode which I also tried and heavily disliked the workflow of), I opted still for Markdown just in case next week I change my mind on org-mode or some equivalent situation emerges, this will ease the adapation of these notes into that other situation.

Knowledge Base Ideologies

My biggest issue with many of the editors I have used was their attempt to conform my notes to whatever their preferred note taking ideology is, be it Zattelkasten, an amorphous blob of interconnected links or what have you. While I appreciate that this provides the intellectual boundaries that one needs to appreciate these formats, I find them all to be foreign to the patterns of my thought and memory. Especially the notion of mind maps that while sure, there exist some degree of interconnection in the way I think about certain subjects, the whole of my knowledge in technical matters actually conforms more directly to a heirarchical, topical pattern that the occainsional crosslink is sufficient for and there is no need to keep all my notes jumbled in one directory, such laziness begets misunderstanding to me, not creative thinking which I seem to be just fine in doing without any such organization pattern to my thoughts.

Additionally, I don't think much more jargon is helpful. I spend enough time as it is explaining away jargon, which is not something helpful to my understanding per se, but a necessity given the absolutely absurd and detached tendency of tech to use such an unnaturally thick jargon (what I suspect is one way of keeping people locked out of it). So my knowledge management system needs not be laiden with superfluous jargon either, which many editors are prone to as well.