wolfgang ziegler

„make stuff and blog about it“

Managing your notes with Markdown, Visual Studio Code and GitHub

December 30, 2021


The OneNote logo

If I do the math correctly, I think I was using OneNote for managing my notes and cheat sheets for about 15 years (god, I'm old 😱). But honestly, OneNote is a great tool and there's nothing wrong with it - as long as you are using Windows, a Mac, or mobile devices. On Linux the browser version is what it comes to and I honestly never really liked that. It always felt slow and took me too long in order to jot down a few notes. I know this seems like complaining about first world problems but to me this was a deal breaker so I went looking for alternatives.


The EverNote logo

I had a quick look at EverNote as the obvious alternative but it has the same problem of the missing native Linux app (although I recently learned that there is something in the works). Also, their 2 devices restriction on the free plan is a deal-breaker to me. Sorry, I'm not gonna pay for a note-taking app.

Boost Note?

The BoostNote logo

After looking at a bunch of (honestly very similar) alternatives, I picked Boost Note as my main driver for note-taking.

Those were my evaluation criteria:

  • It must be cross-platform.
  • There must be a mobile (iOS) app.
  • It must support Markdown for note-taking.
  • It must be free.

Boost Note ticked off all these boxes and I want on it for about 2 years more or less frictionless.

There would have been no real (feature-related) reason to steer away from Boost Note again apart from the occasional mail asking to switch to their paid plan and what felt like subliminal threats that the free model could be taken away.

Also, since I was using Boost note mostly as a glorified Markdown editor for a bunch of files synced in the cloud, I felt that this should be done in a more straight-forward way.

VS Code + GitHub!

VS Code and GitHub logos

So what's a more straight-forward approach to editing Markdown files and syncing them in the cloud?


  • a Markdown editor
  • and a way to host and sync files in the cloud.

In my case, this is now done with Visual Studio Code and GitHub. But replace this combination with whatever floats your boat. If Atom and OneDrive make you more successful, use those.

The main idea is to have full control over your content with the least level of friction.

  • I can edit and organize my Markdown notes everywhere.
    • VS Code is available on all the operating systems I use (even on my Raspberry Pis).
    • I can read (even edit) my notes on my mobile using the GitHub app.
    • On a machine where I don't have my notes repository cloned, I can still use GitHub in the browser.
  • There's no vendor or data-format lock-in.
    • Should I happen to not like VS Code or GitHub anymore, I can take my notes and go somewhere else - it's just text files (plus a few images).
    • If Markdown should fall from grace someday and be replaced by something else, I'm pretty sure it will be really easy to convert to this "something else" (after all, it's just text).

Pro Tips

Here are a few Visual Studio Code extensions that greatly improved my Markdown and note-taking experience:

Markdown Preview Github Styling extension logo

This was a game-changer for me when it comes to working with Markdown in Visual Studio Code. It changes the built-in markdown preview to match Github's style which is ways easier on the eye. I can only recommend installing it right-away if you haven't already.

Code Spell Checker extension logo

This spell-checker works great for code but also for editing Markdown.

Luna Paint extension logo

This is a nice little extension if your notes include images that you need to resize, crop, annotate - all within VS Code. It supports png, jpg, webp, bmp and ico formats.

Markdown PDF extension logo

This is a great tool if you need to share your notes with someone. It extends your command pallete with a couple of new options to convert the current Markdown document into PDF, HTML, JPEG, or PNG.

markdownlint extension logo

After all, we want our Markdown notes to be, right?