DEV Community

Cover image for An amazing note-taking system with Markdown and Git, Part 2

Posted on

An amazing note-taking system with Markdown and Git, Part 2

In Part 1 of this series, I explained why I gave up paper notebooks, email, and note-taking software like OneNote over the years. I had taken up with plain text files when we last left off. But I'd like to also make a few honorable mentions.

Other things I tried

đŸ”¬ Consider why people take notes for a moment. "Notes" are actually not "notes" at all at the end of the day. They are actually records of conversations. Reminders. Encyclopedia entries. To do lists. Time tracking devices. And a dozen other things.

If you've followed the "productivity obsession" of the internet age, then you know there are little pieces of software for each of these specific needs. Necessity is the mother of invention. And so we have time tracking software like Toggl. And we have reminder software like Remember the milk! And we have wikis like Confluence or blogs like WordPress.

It may not surprise you to find out that over 15+ years, I tried all of these things and more. There are various small reasons why I abandoned each one in turn, but there is one huge reason that ultimately kept me from adopting them.

The Walled Garden Problem

A Walled Garden is both a real thing and a useful metaphor for any closed platform.

A terrarium viewed from above

The problem with a closed platform like any of the above is that once you start using them, you sink cost into them the longer you do. Any content you enter becomes more and more entrenched over time. That content becomes no longer portable.

It is imprisoned.

Sometimes it is only effectively captured, because it cannot be moved without expending such a large effort that it isn't worth moving it. But, often, it is actively captured by companies interested in profits, who use legal agreements, proprietary file formats, digital rights management platforms, and more to retain control over your content.

And sometimes you lose all that content entirely. I have experienced firstand what it is like for HP to buy out my online email provider and end my email address. I know the dangers of these systems firsthand. When my email address went away, so did my associated account on Facebook, because I couldn't reset the password or even change the address because it couldn't receive a confirmation email. And good luck trying to get any support from Facebook about that . . . because fraud.

So walled gardens are a huge problem and portability of any given solution has to take this problem into account. Besides that, what you end up paying over the years into certain platforms that are little more than repackaged open source can sting your conscience, especially when they don't give back to the community that made them possible.

So, I generally like to avoid walled gardens. That doesn't mean I think you should avoid them too. Nor does it mean that I always do, but it's worth pointing out that walled gardens have a cost, in both the small and the large.

So that brings us to the idea of standards.

The Markdown standard

While I was taking plain-text notes over the years, people were creating a wonderful thing: markdown. Markdown is, basically, a minimalist text-formatting scheme. It is one of those ideas that is so delicious that it found a wide audience fast. The adoption of markdown has been nothing more than spectacular. And its benefits are inarguable.

At the end of Part 1 I talked about two major drawbacks I had with paper notes:

  • Cannot link to anything in the outside world (no clickable URLs)
  • No images, audio, video, etc.

I had previously considered writing notes in HTML but—let's be honest—that is entirely impractical. So once I started using Markdown for other things, it didn't take long for me to want to put it to work in my notes. For the small price of adopting some kind of "compilation" stage in my notes, whereby they get compiled from Markdown to HTML, I could take notes that had all of the following features:

  • portability (thanks to standards!)
  • clickable links
  • code snippets with syntax highlighting in any language
  • images, including screen shots and photos of whiteboard drawings
  • audio or video embedding

I also really like the ability to

  • have
  • bulleted
  • lists,

The ability to

quote any text I want,

and so forth.

But how?

So that brought me to the question of how to achieve this "compilation stage." Stay tuned for part 3 of this series, as that's what I will cover next.

Top comments (25)

darrylnoakes profile image
Darryl Noakes • Edited

I seriously recommend taking a look at Obsidian.
It is, in essence, just a nice editor for Markdown files, with some useful amenities, like a calendar for journal entries, that sort of thing.

I have used OneNote, Evernote, Joplin, and plain files. I like just files, but even with VS Code and Markdown, it didn't really work, because I wanted to be able to easily use it on my phone.
I decided on Obsidian because:

  1. It's files where I choose the structure, instead of a database where the app has a hard-coded format.
  2. Because it's just files, I am in control of syncing, instead of having weird syncing systems like OneNote and Evernote. I use SyncThing (I was already before getting Obsidian) and am loving it.
  3. There is a desktop and mobile app.
  4. It has many handy plugins, like Calendar.
  5. It's simple by default, but can be pretty much as complex as you want.
  6. It's free.
jorahlavin profile image
Jorah Lavin

Sincerely, thank you, Darryl. You may have lead me to my starting point for finally building a working notekeeping/zettel. Also, thank you (sarcastically) for sending me down a rabbithole for two hours.

fahmifan profile image
fahmi irfan

I already use obsidian and it just great on desktop. Right now i use Telegram saved messages for my phone note taking, why? cuz it fast. Still need to figure out how to sync between phone and obsidian

snj profile image

I use Obsidian, and since it does not have a Andriod client, I build a web interface with it, and it works perfectly for me:

Thread Thread
darrylnoakes profile image
Darryl Noakes • Edited

I have the official Android app. What country are you in? Maybe it's blocked there.

Thread Thread
snj profile image

yes, it's blocked. BTW, if you use official app, where is the data stored?We need the official sync service?

Thread Thread
darrylnoakes profile image
Darryl Noakes • Edited

The data is stored in your filesystem, the same as with the desktop app.

The official sync service is not required, you can use anything you want for syncing. I use SyncThing, as stated in my original comment.

Maybe I can upload an APK...

Thread Thread
snj profile image

Thanks for your sharing!
I didn't notice it, but currently I'm happy with my own solution :). I prefer to use a web app which could embedded in Wechat.

That's the benefit of everything in plain text. we can build our own tools based on it.

Thread Thread
scottshipp profile image

You nailed it! We can build our own tools and have our own processes. I hope I have stated this better in the latest (third) post in the series that was published today. Thanks for the comment!

ivijl profile image

Man, you opened rabbithole for me, whole weekend I have been watching obsidian videos. And its amazing whole new world I didn't know about.

sams_here profile image

Thanks for sharing your note-taking journey. Looking forward to your 3rd installment.

Not sure if you (or anyone else here) are on Discord but I'd like to extend an invite to a closed Alpha note taking / whiteboard program called Project Meta. The community has grown to over 700 members since June (4 months).

You can read more about the project here:

Public Roadmap is here:

Discord server invite:

I'm a community Mod there and can say that everyone is extremely excited about the project and the small Dev team is super involved with user feedback, bug reports, use-case scenarios and 1-1 onboarding.

sams_here profile image

Oh, I just noticed that today (Oct 23) is your 4 year anniversary on! Congrats.

uchitesting profile image

I will read both parts later.
Until last year I tried to take notes on Microsoft OneNote.
In many cases this is useful, but as I was trained dev, I started to need code snippets. While I could do it in OneNote for there is a code styling, there are still problems :

  • No syntax coloration. It is always grayscale. Neither very attractive nor simple to read.
  • Not very practical.

I was already using Github for 6 months before the idea of markdown struck me.
Why didn't I think about it earlier?

Since then, any new course I'd follow, I write notes in there in markdown.

I'll read both parts later and may update this comment or write a new one after. Hopefully I may learn a thing or two I did not integrate yet.

inglesita profile image

Have any of you tried It sounds like what you are looking for. They've been around for about a decade and are still updating their changelogs with progress on improvements. I keep coming back to them for the simplicity.

tanami profile image

I wrote my own note-taking system which automatically links pages together because I didn't want to get in the way of the collocational features of the words. If you want to see the current prototype it is at

scottshipp profile image

That's pretty cool!

hudsonxp80 profile image

Notion.! Highly recommend

marflage profile image

As much I want myself enjoying using Notion, I just can't so somehow. The mobile app feels really sluggish, I am guessing it's because it's not a native app but a wrapped-up-web-tech app. The disability of using it on my phone bums me so much

justjenfelice profile image
Jennifer Hageman-Culp is where it's at

kjellskogsrud profile image
Kjell Skogsrud

I am excited to see the next part :)
I feel much of the same struggles and limitations in note taking and lists.

Looking forward to it :)

tinkerbits profile image

Enjoyed the read, thank you. Have you ever heard of org mode in Emacs? I find it amazing for note taking.

overminddl1 profile image

I signed up just to vote up this comment, org mode is the best for note taking, it's just a text format similar to markdown, but better (and older), give it a try!

nguyenit67 profile image

I recommend Notion as a handy service (to me).

morphzg profile image

When more? Thanks for sharing. Will follow.

scottshipp profile image

It looks like it will turn into a four-post series right now. I'm trying to make sure and publish them on Tuesdays and Thursdays. Glad you're getting something out of it