Building a great personal knowledge graph with Obsidian

Obsidian is a very unique product amongst personal knowledge management software. Over a recent two-week break that I took from work, I spent some time really digging into Obsidian and the broader idea of "personal knowledge graphs".

One particularly excellent example of how to build a personal knowledge graph is done by Andy Matuschak.

Why Obsidian?

Some of my own notes on Obsidian:

  1. Obsidian is an IDE for linked thought
  2. Obsidian operates on open standards
  3. Publishing Obsidian vaults is cross-platform and portable

How to build an effective notes/knowledge graph

How should notes be written to make an effective knowledge graph?

Paraphrasing Andy Matuschak:

  1. Notes should be atomic
  2. Note titles should imperatively advance one idea
  3. Notes should be centered around concepts
  4. Notes should be linked densely

And my own thoughts tacked on:

  1. The knowledge garden should be tended to daily

How to build the notes site?

Now, what were the exact steps in building out the notes website?

Firstly, I used Obsidian to author the notes. The fact that it's a great IDE for linked thought helps a ton.

Secondly, I used an unpublished, install-from-source-only Python package, apparently developed by a Google engineer called Lettersmith to compile the markdown files into HTML files. I followed a baseline script by another GitHub user @kmcgillivray, who made obsidian-lettersmith, which provided a starter script I used as a base. I used a Jinja template to populate each page.

Thirdly, I re-visited Bootstrap docs to get styling done in a Bootstrap-idiomatic style. Previously, I was completely unaware of the styling utilities available. This meant I was maintaining very poorly-documented CSS hacks to get styling done right. By using the Bootstrap 4 utilities, I was able to compose together styling in a fashion that was much, much easier to maintain.

Fourthly, I wanted hover previews, which meant hacking the Jinja template with some custom JavaScript. Not pretty, and a bit verbose in the compiled pages, but it worked :).

By this point, I was happy enough with the sort-of-replicated Andy site.

I continue to use Obsidian to author the notes. As an IDE for linked thought, the graph view helps me see which notes are still isolated to one another; this gives me a great visual hint as to where I could add more links. I also continue to hack on the notes UI. The source code is in a private repository at this point, as I have plans to separate out the code for building the site from the notes source.

Pages that link here

Blog drafts
Some drafts of blog posts I'm writing:

Publishing Obsidian vaults is cross-platform and portable

Because Obsidian vaults are nothing more than collections of Markdown files, they can be easily converted into HTML files through static site generators. The only tricky part is finding a parser that will handle the "wikilinks", which are internal links to other pages.

One way is to use Obsidian Publish. This supports the devs, who continue to pour effort into frequent updates that really enhance the app. I personally chose to do so, because it would translate directly into support for the developers to continue developing Obsidian.

Another way I have been experimenting with is to build a static site based on the Markdown files inside my vault. I used two pieces of tooling, one slightly more infrastructural called Lettersmith, and the other which provided me with a template to get started called obsidian-lettersmith. My notes are published to GitHub pages.

Notes should be linked densely

I am lifting this idea directly from Andy.

Linking notes together forces us to comb through our mental model of the world. The knowledge garden that we build up is an externalized graph that maps our knowledge; it is a tool to help us remember things. We should leverage our externalized graph to help us find connections between ideas. In doing so, we reinforce the connections that live in our mind.

Note titles should imperatively advance one idea

Note titles are the currency of links between notes. We need them to be imperative such that they positively advance a message. Being imperative, they are more easily linked in the body of the text in which the link is being made, whether it is in a list form or in prose form.

Obsidian is an IDE for linked thought

By "IDE", I mean "Integrated Development Environment". It has a plugin-based system not unlike VSCode, and like any other IDE, it offers a toolset that makes accomplishing things faster.

A few examples:

  • Unified pop-up search that lets us fill in the titles of linked notes, or create new ones that aren't already present. This facilitates the note linking process by eliminating the need to search for another note in a different UI. This is one way Obsidian plays the role of an IDE.
  • Graph view that lets us visualize connections between notes, and browse through notes that are along the path from one idea to another
  • Automatic back-link detection for notes that have smaller titles with one-click linking. This also reduces the barrier to note linking.

Being able to actively cultivate linked thoughts via linked notes helps foster connections between ideas. In contrast to Evernote, which also supports note linking, Obsidian's ability to use the pop-up search to insert links helps a ton with linking notes. In other words, the UI reduces the friction involved in linking notes.

Notes should be centered around concepts

We center a note on concepts, rather than an author, or a book, or something else.

Concepts are translated into content espoused by authors/books/websites. They are like "instances" of the general idea; they provide support/evidence that we can refer to inside a note. Authors in their writings usually espouse multiple atomic concepts (see: Notes should be atomic), which makes referencing the exact idea in a note on a book difficult too.

Obsidian operates on open standards

Obsidian doesn't lock you into proprietary formats that can't be parsed elsewhere. Hackability is part of the ethos of the software.

A few examples:

  1. It uses plain Markdown with only one extension -- wiki links -- to build the graph of interlinked notes.
  2. Obsidian vaults are nothing more than folders of plain markdown files.
  3. Its UI is configured using an obsidian.css file, and this is done on a per-vault basis.

With Obsidian operating as an IDE on top of a filesystem of plain text files, it leaves users free from proprietary data formats or a database. For a collection of plain text notes, the filesystem is a wonderful database. Users can feel much safer about their data without this level of lock-in.

Notes should be atomic

In a personal knowledge graph that relies on notes, the notes should contain a single idea that makes one point. Having two points in the note makes the note confusing to link to.

The knowledge garden should be tended to daily

If not daily, then at least regularly.

This practice, once it becomes a habit, will foster the spaced repetition that is necessary for learning something. Written text externalizes my memory in a permanent and reliable media; revisiting it on a regular basis helps me strengthen the connections in my transient and unreliable memory.

The reason for daily tending, or at least regular tending, is that repetition helps with retention. After all, our goal is to internalize deeply (in our minds) the externalized representation (that lives in our hard disk).