Shopping lists, class notes, technical documentation, time and place of important appointment - all of these things are difficult to keep in our heads, therefore we tend to write things down. It doesn’t matter who you are and which field are you working in, you probably have some kind of note taking system in place. It could be a physical notebook, a pile of post-it notes, the default ’notes’ app in your phone or perhaps more sophisticated piece of software with advanced note management features. Any of those are perfectly good ways to write things down in order to remember them later. However for some reason i was really struggling to find my preferred way of writing things down.

Holy grail

I have a few specific requirements for my note taking system:

  • I want markdown support - the format is easy to use and read even in it’s raw form, i just like it;
  • I want to own my data - i should be able to access, modify, backup, or delete the files containing my notes;
  • I want syncing across devices;
  • I want to be able to organize my notes into different categories;
  • I want to be able to search through the notes easily;
  • I want the system to be platform independent - i shouldn’t face any issues accessing and editing notes on any device or on any text editor;

Having these requirements in mind i went through my journey of searching for the perfect note taking app / system. As it turns out it was not so simple, i kept finding really nice ‘off the self’ solutions, however they would cover most but not all of my requirements. Let’s go over a few of them and see what was missing.


Giving credit where credit is due - Notion has built a great community around them and it seems to be the most praised tool, whenever you start looking into the currently available solutions for note taking systems. I was sold by those appraisals and decided to try it out. At first i was amazed, i thought that it’s the best tool on the market, database integration seemed really powerful and i started building my ‘perfect’ dashboard to manage everything note/knowledge base related. It took me a few days to realize that the platform is sucking me in and all i am doing is ‘perfecting’ my dashboard/work space rather than actually using it for taking notes. It feels like the tool is built for those toxic productivity gurus on YouTube who spend majority of their life building and talking about their productivity systems - the irony is that after interacting with all of those systems that’s supposed to make you more ‘productive’ you’re left with no time in the day to actually get stuff done.

At the time i used it Notion also didn’t have support for offline mode and it’s native text editor was terrible. For these reasons mainly I said pass.


Joplin was really close to what I’ve been looking for. It supports markdown, it has implemented syncing with various services, it has GUI and CLI client, which means i can edit notes in vim and it’s open source - what else is there to want? Well Joplin for some weird reason decided to not expose markdown files directly to the user, which prevents me from exporting plain markdown files and editing them in anything else than the Joplin client. It really is a shame but i had to say pass.


I have used obsidian for maybe 15 minutes in total. It seems really powerful and the notes are easily accessible as a plain markdown files. However the file syncing functionality is behind a pay wall which is a bummer. Another thing i didn’t like is it’s complexity, i understand that it’s really powerful however i do not see myself using the majority of the functionality and having so much bells and whistles to play with is a big distraction which pushed me away from adopting the platform. Although if i had to recommend one tool for someone else i would probably recommend Obsidian.

I was tiered of adopting a new system, migrating all my notes just to find that the platform doesn’t support some specific functionality that i need. It seemed that searching for a perfect note taking system is like searching for a holy grail. Therefore I decided i will just build my own system just for my own needs.

My own system

Well perhaps ‘building’ is a strong word here as I’m not creating an application here, i am merely designing a system with a set of tools around it which helps me cover all of the necessary functions i want from the note taking system.

I simply place all of my notes in a git repository and i have exported it’s directory as en environment variable by adding this to my .bashrc:

export NOTES_DIR=$HOME/Documents/notes

In order to access the directory quickly i have also created an alias:

alias notes='cd $NOTES_DIR'

I simply create and keep markdown files here without worrying too much about the directory structure.

Isn’t this an unorganized mess where nothing is possible to find easily?

Not really. I am organizing notes by creating tags for them. For example i have a vim cheat sheet file which has the following heading:

Title: "Vim cheatsheet"
Tags: [tutorial, vim, cheatsheet, documentation]

This let’s me use other tools that I’ve created in order to quickly find the by name or by tag.

In order to search for notes i have written a small shell script it lets me quickly search through notes by name, tag or even by text pattern of the note content: -h
The program searches for .md files through notes directory
Notes directory must be specified as $NOTES_DIR environment variable
-h    Prints this message

-t    Filters notes on tags. Tags must be specified in metadata block like this: 
      Tags: [tag1, tag2, tag3]

-g    Uses grep to search through notes, usage: -g searchpattern

The script opens a fzf interface, through which i can select, preview and open the note files in vim.

What if I need to write down something quickly?

I’m in a rush and i need to type something down as fast as possible, or i have a gist of idea in my head that i feel is slipping away, or maybe i just want to dump some thoughts and organize them later. No problem - I have written another shell script just for this purpose

This is a neat script that creates a new file in $NOTES_DIR, naming it, opens it in vim and adds a time stamp to the current line. What’s also cool is that if you have already launched the today it will not create a new file, but rather will open the already created note and add a new line with the new time stamp. That way you can write multiple ‘quick notes’ throughout the day and the script automatically organizes your thoughts with time stamps. Here’s how it looks:


How do I access the notes across different devices?

All of the syncing is done via git. It might not be as seamless as I’d like but it’s good enough for me, also i like that i have all of the change history, in case i need to access something from the past.

If I’m on a different computer it’s easy enough to access the notes as they’re stored in git repository, however if I’m on mobile using git might not be so pleasant. For this reason i also decided to self host a web app called flatnotes through which i can access the notes ‘on the go’. It’s also nice if only want to read the notes as it has a pleasant UI to read from compared to vim:

Flatnotes front page: flatnotes-frontpage

Reading individual note: flatnotes-note

One problem with flatnotes is that it doesn’t support nested directory structure, so if i have notes inside different folders they will not be visible to the application. Luckily the project is open source and i was able to fork the project and modify the code to overcome this limitation. I tried selling the idea to the developer in this PR, but he didn’t want to introduce the changes. In case anyone is interested in my forked version of flatnotes just amend the docker image from dullage/flatnotes:latest to gedulis12/flatnotes:latest

Markdown to PDF? No problem!

I also thought that it might be useful to have the notes accessible as pdf files, so i made another tool using Pandoc, it’s a small script that takes command line argument as an input and converts the markdown file to pdf. This way it’s easier to read through bigger files, especially technical documentation that i might write for myself.

What works for me may not work for you

Although i can say that the system i have created is perfect, most of you will probably not agree, and that’s fine. This post is meant to be read as an inspiration and not a definitive guide on how to create the perfect system. My goal is to show that the existing tools should not be taken as the only possible solutions to the problem, and with a little tinkering everyone can create something that fit’s their needs perfectly.

Hopefully I inspired someone to build their own perfect tool. I am happy to hear any feedback or suggestions, you can reach me on mastodon or github