Notes organisation with Markdown, Visual Studio Code and Pandoc
28 Dec 2018
History
I have been using various note organiser tools, such as EverNote, MacOS Notes, Bear, Microsoft OneNotes over the years to keep track of my brainstorm ideas, study notes, project ideas, software commands, deployment instructions and some how-tos.
However, I still feel constrained by the limitation of the tools and unable to do exactly what I want to organise my notes. Here are some of my rants about these tools:
- EverNote has been my favourite notes taking and organisation due to its rich functionality and able to sync across multiple devices. It is great for me to keep track of different type of notes. For me, it keeps my cooking recipes collected from the internet pretty well, especially those with nice foodie shots. There are various browser plugins to make web clipping to EverNote easier and I love that. However, since EverNote decides to go for different business model (i.e. pay for features), I have stopped using it and looking for other alternatives.
- MacOS Notes is the default notes taking app in MacOS and iOS. It attracted my attention since it has the capability of syncing between different devices. Also, you can set a lock on individual notes so that you can keep the notes from prying eyes. However, the lack of Markdown support and richer editing experience of MacOS Notes lead me to search for other alternatives.
- Microsoft OneNotes comes pretty close to EverNote replacement since EverNote charging for the features. OneNotes has rich editing and notes taking capabilities, and allow syncing between different devices. One downside is you will be tied to Microsoft cloud infrastructure because the notes are stored in the cloud storage. While OneNotes software is free, there is a limitation on the storage. I am not sure if this is a personal bias, but everytime I tried to switch to OneNotes, I was unable to persist my will to continue using it as a note-taking software. In addition, OneNote also does not support Markdown.
- Bear is the closest clean notes-taking product that I have been searching for that supports Markdown. Although the product is quite recent, the interface is super clean and lightweight. It supports markdown out of the box and able to sync between different devices. Unfortunately it is not free and my worry is I am going to put all my notes into this product and if anything happen to the product, I will need to spend a lot of time thinking of a migration strategy.
So after spending some effort in searching for the holy grail for note-taking tool, I have created a list of functionalities that I am looking for:
Core
- Markdown support
- Able to sync between devices
- Allow copy and paste images easily
- Able to export the notes in different formats (e.g. PDF, HTML)
Nice to have
- Web-clipping plugin in the browser
- Support LaTeX formula
To me, Markdown is the de-facto standard now for notes taking. Markdown can be converted to different other formats and there are various support for rich editing, including LaTeX.
Also, writing notes in a “text” format will enable quick searching using any text searching tool. In addition, MacOS will be able to index it as it is in text format.
So I decided all my notes from now on will be written in Markdown.
Tools
My requirements on a note-taking tool led me to create a solution for myself with the combination of the following and it works quite well!
- Dropbox account - to sync between devices (or any other cloud service that supports syncing between different devices)
- Visual Studio Code (VSCode) - arguably, you can use any other editors but it is not covered in this post. VSCode is my favourite IDE at the moment and it is very versatile, from note-taking to coding.
- Pandoc - For various exporting format.
Methods
Steps to my custom solution for note-taking:
- Install Pandoc
- Install Visual Studio Code with the following plugins:
- Markdown Preview Enhanced (MPE): This emulates the Bear two split-pane editing mode, where the right pane reflects in real time what you write in the left pane. One minor limitation is it does not sync the location automatically - but this could be an advantage in itself because some editors did not do this well when it involves images (the calculation of the position to scroll to tend to mess up with different image heights). Ctrl+Shift+S is the shortcut key to scroll to the text - i.e. sync between left and right pane. Also, MPE supports exporting the markdown in different format, including PDF, PNG, JPEG, HTML. Pandoc is required to export PDF with LaTeX.
- Paste Image: This plugin allow you to paste the image in your clipboard directly to VSCode as markdown. It will create the image file in the designated folder (customisable) and include the markdown link in your document.
That is pretty much it for the setup!
Now you can create a folder, or many folders in your cloud drive and start creating Markdown documents using these tools and plugins.
Experience
I have been using this setup for a while now (approximately 6 months) and never look back to EverNote or other tools. Mind you, I still keep my recipes in EverNote because I am too lazy to convert them, and the recipes in EverNote works better on iPad when I am cooking.
However, all in all, this solution has make my notes-taking much easier and give me a peace of mind, knowing that all my notes are in text format and sync between devices. It can be exported to very nice format (defined in LaTeX + Pandoc template).
Limitations
It is not a holy grail but getting pretty close to my ideal note-taking tool.
At the moment, I still need to find out an iOS app to enable me to edit on iOS devices. There are many Markdown editors in iOS which support integration with cloud storage such as Dropbox, but at the moment, I have no need to edit or make notes on iOS yet.
Summary
I hope you find this post useful and happy to hear more about your experience in note-taking. Also, I am interested in integrating hand-written notes (using iPad + Apple Pencil) with this solution if you have any tips! Thanks.