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 draw.io 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 .cm-tooltip.cm-formatting-bar { 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.

New Comment
4 comments, sorted by Click to highlight new comments since:

Have you ever used Obsidian? Sounds similar to the method you're describing. If so, what do you think of it? Especially with respect to your preferred workflow?

Obsidian is similar in that it uses folders of Markdown files. However...

  • If you want version control, which I think you should, you'll need to set up the same git + syncthing system on your Obsidian vault, which negates any advantages regarding easier syncing.
  • I prefer the interface of some other Markdown editors.
  • I don't like how Obsidian discourages people from dealing with the filesystem directly.
  • It's not open source.

It's not a bad piece of software, relatively speaking. Some people like it; if you don't care about version control, then maybe you'd like it. It does have some fancy overview tools and it works on phones better.

I enjoy using Obsidian for its automatic syncing and intuitive mobile application. I'd happily use the git system outlined in your post if I didn't jot down as many notes (or reference links saved in files) on my phone as I do now.

Perhaps more important than these details: How do you curate input to take notes on, and what is the purpose you take the notes for? How do you use the notes once written? (This latter point seems to be one of the biggest reason many people have dropped PKM systems.)