my note system

Link post

I’ve been told that my number of blog posts is impressive, but my personal notes are much larger than my blog, over a million words and with higher information density. Since I’ve had a bit of practice taking notes, I thought I’d describe the system I developed. It’s more complex than some integrated solutions, but it’s powerful, modular, free, and doesn’t rely on any specific service.

is this necessary?

Most people don’t take extensive notes and don’t use git at all, so obviously a fancy note system isn’t strictly necessary for most people. To some extent, you have to ask yourself: are your notes on some topic going to be more useful to you than a Wikipedia page or internet search or book? Do you need more records than your emails already provide? In my case, I think my blog posts show that I have some info that’s hard to find, but I mostly just remember technical stuff instead of looking up notes, so many of them haven’t been necessary.

But most people do take some notes, this is modular so you don’t have to use every part, and the parts are useful for other things. I do think it’s at least worth being aware of the kinds of tools described below.

my note format

My notes mainly go in text files in a folder.

When a text file gets large, replace it with a folder with multiple text files.

When pictures are needed, put the text file in a folder with pictures.

When a flowchart is needed, you can use yEd or the desktop app.


That notes folder goes in a git repository. If you install git, you can create that with:

  • cd [directory]

  • git init

  • git add .

  • git commit -m “initial commit”

If you’re smart and don’t know how to use git, you should learn how to use git.

viewing history

To look at the edit history of your notes, you’ll probably want some GUI program, such as Github Desktop, GitKraken, or Gittyup.


If you want formatting or inline images, your text files can be Markdown. To view or edit the rendered Markdown, there are many options, such as:

  • VNote

  • Zettlr

  • MarkEdit (mac)

  • Typora (paid)

By the way, in Zettlr, if you want to remove the formatting bar when you highlight text, you can go to Appearance → Custom CSS and add:

body .main-editor-wrapper .cm-editor { display: none; }

Markdown files can contain relative links to other notes, including to folders, and Markdown editors can follow those links. This is useful.

bare repository setup

Instead of syncing the git directory directly with other computers, it should instead be pushed to a “local remote” which is a bare repository. That can be set up as follows:

  • cd [shared directory]

  • git clone—bare [existing repository]

  • cd [existing repository]

  • git remote add sync [created .git folder in shared directory]

On your first push, you can set the bare repository as default with:

  • git push—set-upstream sync


Next, download Syncthing and open it.

You can now add the bare repository folder to the synced folders, add another device you want to sync with, and it will handle the rest. You’ll also want to sync a folder for ordinary files.


Rather than describing complex things such as a manufacturing process or the 3d geometry of an aircraft, I’ve found it’s better to use conventions of programming languages, such as functions and assignment to variables, but with the things being assigned to variables described in an unstructured way.