Taking Markdown Notes in Vim

20.04.20    markup    tools and tricks

Taking notes in a single place can be a very useful tool to organize your ideas and concepts so they don't get forgotten. By writing down your ideas and problem solutions, you'll know where to look when you encounter similar use case. The notes can be best kept up-to-date and organized with a unified digital format.

Using Markdown as a format for this has many upsides1. For starters it a plain-text format. It can easily be edited with any text editor. The markup is simple and concise making reading and writing Markdown sources comfortable enough. At the same time it is a very common open standard. Many tools have additional support for Markdown. And it is reasonable to expect that this is not going to change any time soon. By using Markdown you are not locked into a proprietary format or specific service, which might change or be discontinued outside of your control. Instead you can easily combine and change any tools and workflows, making such a plain-text-based setup future proof. Here I present what an arrangement of tools for Markdown note taking can look like.


The main organizational unit is the file. One topic roughly corresponds to one .md file. The notes are saved in a subdirectory of the Notes root directory. Each subdirectory corresponds to one very general category like computer / IT stuff or ideas and concepts. Sometimes I might use deeper nesting of directories. This hierarchical structure is working quite nicely for me. I have not yet found more complex systems like tags necessary.

I edit this files using Vim. But I have found the basic markdown syntax highlighting to be lacking. Here the vim-pandoc plugin and its syntax file help immensely. As a bonus they support pandoc markdown extensions, additional features like correct folding and pandoc compilation integration. I have some additional configuration in my vimrc:

let g:pandoc#syntax#conceal#use=0 "disable conceal feature
let g:pandoc#folding#fdc=0 "disable fold column
let g:pandoc#spell#default_langs=["en", "de"] "set spell languages
let g:pandoc#modules#disabled=["chdir"] "chdir feature is confusing

An additional plugin I employ is wiki.vim. The main functionality I use is the link handling. When the cursor is on a word hitting enter transforms it into a markdown link. Hitting enter again jumps to the file with that name (or creates it if it does not exist yet). This is very useful to connect the notes with each other and easily create new notes while in the editing flow. Links to anchors like this #Write-link can also be created and followed - including to other files! Here is the additional configuration to make this work seamlessly:

let g:wiki_filetypes=['md'] "enable wiki.vim for .md files
let g:wiki_link_target_type='md' "add .md extension to links


I also read the notes in Vim most of the time. The simple nature of markdown formatting together with syntax highlighting makes this comfortable. The aforementioned wiki.vim plugin makes following links while reading easy as well.

The file structure with one file for one topic enables the use of standard file browsing to explore notes. I like to use the terminal-based file explorer Ranger for this. I can navigate the notes in the different directories with the keyboard. The right pane gives a preview of the currently selected note (or contents of the currently selected directory). With one key stroke I can start Vim to view or edit the file.

Pandoc can be used to export Markdown notes, converting them to a multitude of output formats. This includes HTML which enables to view the notes in the browser or print them. My panserver tool streamlines this process, so that I don't have to organize the temporary HTML files.


Because notes are stored in simple directories-of-files format, I can use any general purpose file synchronization service. I have had great experiences with syncthing. It connects my devices into a mesh, so they can directly synchronize files without any outside server. This includes my laptop regardless if it's connected at home or via the university network. And this includes my phone where I can read and edit the notes using the Markor from the Android Playstore.

Yet another device on my mesh is a Raspberry Pi which I occasionally power on. There syncthing synchronizes my notes onto the internal storage. A cronjob running hourly makes a copy of my notes into a local git repository and then tries to make a commit (which will silently fail if there are no changes). Here is the simple script:

cd $HOME
cp -r Sync/Notes Notes_git/
cd Notes_git/
git add "*"
git commit -m "Backup Notes $(date +'%Y-%m-%d-%H-%M')"

With this mechanism I have a backup of my notes on my Raspberry Pi which includes a history. I can edit my notes without fear of permanently deleting something. And all of this works without any third party service2.

  1. Other plain-text formats share most of the benefits. But I have personally found Markdown with minor extensions to be simple and still powerful enough while being most consistently supported by third parties. 

  2. Technically I use public syncthing discovery servers. But no actual data goes through third parties.