sysid blog

Note-Taking Nirvana

August 28, 2020 ☕️ 6 min read

I hear, I forget. I see, I remember. I do, I understand.

I am a bad memorizer. I need to take notes, quickly, store and find data efficiently. I need it on Windows, Linux and Mac. OS idiosyncracies drive me nuts.

I have tried my share of tools, from handwriting notebook over cloud-based OneNote to powerful but expensive Mindmanager. And anything in between…

noteapps

My pain points:

  • platform dependency
  • tool boundaries (I never found the one-size-fits-all tool)
  • sluggishness, loading times
  • option paralysis, forced context switches
  • cost and vendor lock-in

Requirements

Requirements are simple:

  1. Universal Availability

With the advent of cloud-based solutions this became easy. Many solutions claim to be cross OS platform, but an impedance gap is still there.

  1. Frictionless, Ease of use

Firing up a desktop application only to quickly capture a note is overkill. Relying on a web based tool requires uninterrupted online access, which is not a reality yet. Waiting for loading kills creativity.

The more formatting capabilities a tools provides the more I get distracted by little niggling issues like: Do I want to preserve original formatting, or do I want to apply own formatting.

  1. Knowledge management and Relationships

Data is most valuable in context. Relationships are important and tools need to reflect this. Simple links between pages go already a far way in delivering on this critical requirement.

I used to enjoy the visual data manifestation of Mindmapping, but the cost involved in terms of licence fees and platform inflexibility was way too high.

  1. Active Links

I need the functionality to open applications via links. Inserting not only HTTP URLs, but also file and directory paths and having them opened by the associated application is super effective.

Click the link and the Powerpoint presentation is in front of you.

  1. Screenshots

OneNote excels here not only by taking almost any type of content, but also by saving the respective source link automatically. However, the simplicity of ingesting data often results in big junks of unsorted paste-n-copy data blobs with little benefit for later consumption.

  1. Open Source, no vendor lock-in

Mindmanager is expensive, and your data is locked into an application beyond your control. Same with other tools, they try to lock you in because their business model depends on it. Exporting your data can be difficult if possible at all.
Not a good strategy if you plan to benefit from your knowledge database years down the road.

Vimwiki to the rescue

vimwiki

There is a learning curve involved, not least because Vimwiki is based on Vim. However, this is also one of the most compelling features if you are familiar with Vim. Let’s see how Vimwiki delivers on the requirements:

1. Universal Availability

Vimwiki’s markdown based file structure makes it a prime candidate for Github based storage. Data is synced via Github as you would do with any other code repo.

2. Frictionless, Ease of use

Vimwiki’s text files only need Vim which is my preferred text editor anyway. It’s ubiquity and efficiency allows for the fastest note-taking cycle times I ever experienced. No waiting, no platform specific keyboard shortcuts, … Nirvana.

3. Knowledge management and Relationsships

Vimwiki has full Wiki-link style support. It allows to link bits of data between different pages as you would expect from any modern Wiki knowledge management system. However, to make HTTP links work on Windows Subsystem for Linux (WSL), the default link handling has to be extended . Since WSL is a great idea I wrote an extension to this end (see vimwiki-nirvana).

4. Vimwiki’s Superpower: Active Links

Vimwiki can open arbitrary files. It uses the standard platform specific commands to do so, e.g. Mac’s open or Linux’s xdg-open. The out-of-box behaviour is very similar to just double-clicking a file-link in Windows Explorer.
However, this does not work on Windows Subsystem Linux (WSL) since the default Linux xdg-open cannot open files on WSL. Good old explorer.exe is needed.
Also Vimwiki can not deal with links like smb://bla/blub. But often in an Enterprise settings files are shared via network links and translating these links to your local mount paths can be tedious.

The plugin vimwiki-nirvana comes to rescue (nomen est omen :-). This little plugin provides link translation and allows to choose arbitrary programs for opening files.

5. Screenshots

Since screensots are inherently tied to GUI, handling them in vim cannot be as seamless as in modern GUI based tools. Markdown can handle images, so including screenshots in your Wiki is easy. Granted, it is a little more work than just paste’n’copy, but it is possible and it nurtures a more deliberate workflow: No more willy-nilly paste’n’copy of big data junks just because it is too easy.

Vimwikik can do more

Diary

In combination with the Calendar plugin Vimwiki provides a beautiful calender interface which can be navigated. Just hit ENTER on the date of interest and the diary entry for that date will open. As seamless as Outlook :-).

Tags

The second most important feature in knowledge management after Wiki-links are Tags. Tags are used to mark semantically similar data an make it searchable. Vimwiki can tag your data and even provides autocompletion when typing tags. Searching for tags is possible via a single command.

Todo Lists

Vimwiki provies a simple mechanism to mantain Todo lists based on the built-in list engine. All you have to do is to start a list entry with - [ ] and Vimwiki recognizes the list item as Todo task. Using basic grep allows to quickly create a list of all Todo’s (I use ripgrep for this).

Other

Indices of Tags, Tasks, Wiki- or Diary-entries can be generated with simple commands. Conversion to other formats for publishing, e.g. HTML or PDF comes out-of-the-box. There are people publishing entire websites with vimwiki.

Improvements

I need to use my notes on Windows, Mac and Linux. Since the advent of Windows Subsystem for Linux (WSL) there is no reason not to have the same workflows on Windows as on Unix based-platforms.

An extremly attractive value proposition!

Data is truly available everywhere, anytime on any platform without the mental burden of context switching between different platform-idiosyncracies.

Data is even version controlled.

In order to enable Vimwiki to deal with docx, pptx, … files on WSL, an appropriate link-handler extension is necessary. Vimwiki-nirvana provides the functionality and additionally a convenience function for remotely mounted filesystems on Mac and Linux. As a result it is possible to have standardized ‘Active Links’ on all platforms without the hassle of different path-formats.

Summary

Note-taking is a very personal thing with inherent complexity. I suffered my share on this journey and lost troves of data with every tool change due to incompatibilities or new data formats.

Now I returned to plain text files managed with Vim and Github.

I have the feeling of being at the end of this journey. Data conversion, incompatibilities or vendor lock-in are now things of the past. Simplicity reigns.

Note-taking Nirvana.

Further reading

https://github.com/vimwiki/vimwiki
quick tour
https://gist.github.com/drkarl/4c503bccb62558dc85e8b1bc0f29e9cb
http://jalny.blogspot.com/2018/01/how-to-collect-tags-in-vimwiki.html
Coloring


always be building, by sysid.

© 2022