Simple Markdown Zettelkasten

zettelkasten icon

I’m exploring this zettelkasten thing. I am attempting to “own” my own data by building out the linked web in markdown. I’m a vim fan, but I’m looking at other tools too.

As I’ve lurked productivity twitter I’ve noticed that a lot of the digital Zettelkasten1 systems that I’ve seen fall into two categories: ones using markdown plain text files, and ones using a dedicated tool like Roam/Notion/Evernote. Systems using markdown files can differ wildly given the needs of the particular user, and their favorite text editor.

As I’ve tried to build my own system my goals were simplicity and portability. I want files that are compatible with different apps and editors, so that I can easily take my knowledge-base anywhere.

After intense research I discovered my “new” idea is an old idea2. Here is what the experts at Zettelkasten.de say is be the most compatible markdown format for plain-text Zettelkasten files:

title: Pursuit of perfection causes anxiety
tags: #stress, #effort, #mindset, #cool

Many people believe that perfection should be effortless. This unreasonable expectation causes stress.

> A report from researchers at Duke University sounds an alarm about the anxiety and depression among female undergraduates who aspire to “effortless perfection.” They believe they should display perfect beauty, perfect womanhood, and perfect scholarship all without trying (or at least without appearing to try). [41][^mindset]

I wonder if this is related to the popular trope that "cool guys" don't care, or don't have to try. Over and over in 80s movies you have characters that do not seem to exert any effort to win, it just comes naturally.

[[cool-people-are-bored.md]]

[^mindset]: Dweck, Carol S. _Mindset: the New Psychology of Success_.  Ballantine Books, 2016.

There is more detail about the parts of a simple markdown zettelkasten over at zettelkasten.de.

Implementation Details

Connections

In the original paper implementation3, notes relate to other notes by proximity, and by a ID-powered link.

In a digital format you have a couple different ways to relate notes: Folders, Links, and Tags. I won’t concern myself too much with folders in this document… I will probably have a very flat file structure, only occasionally using folders for very specific domains (work vs. home, etc.)

Markdown has a syntax for making a link via [link text](url/or/path/to/file). While this is great, I have found that it’s nice to have a separate syntax specifically for the in-archive links between notes.4

Although it’s not part of the official markdown spec, it seems a fair number of major editors5 support “wikilink” or “freelink” style links (e.g., [[link]]). The ones that don’t6 are more prose-writing centric rather than notes databases, so I feel pretty comfortable continuing down this path.

Some of these editors prefer links without the file extension (just the filename/title), and some support the file extension. For maximum backwards compatibility, I recommend the full filename and extension.

Tags

There are many different ways to represent a tag7, but using #hashtags inside of MMD/YAML front matter is the most compatible implementation.

The incredibly organized @sirupsen is using #hashtag style in the body of the zettel, but that can conflict with the markdown syntax for a header, so I’m worried about the ramifications8. Putting the hashtags into the MMD frontmatter dodges this issue by keeping them outside the normal markdown, while still letting some apps search for and take advantage of the common hashtag format9.

Its just files

I am constantly distracted by lovely tools 😈. One lovely thing about implementing zettelkasten as flat text files is that you can technically work it by hand

Since I’ve been paralyzed too long by trying to build/discover the perfect tooling, I am going to just start building my “archive”. By hand. Then I will slowly develop tooling to enable what I do most often. On desktop, I am perfectly able to use vim to create, edit, and search files quickly. I’m just going to start, and build tools as I need them.

References

I’ve been scouring my own old wiki for references… here are links I used while researching and putting this together.

General Information about what is a Zettelkasten

Building Blocks of a Zettelkasten

There’s a thing called “Zettelkasten”, and then there’s you using it. The former is the toolkit, the latter is your application of a method.

Required Reading. If any of this intrigues you, this is where I think you should start.

How to Take Smart Notes: A Step-by-Step Guide

A review of a book about a particular implementation of a Zettelkasten system for taking notes. There’s some key points in here about how to run this system.

Baseline Zettelkasten Software Reviews

This article helped me understand what it is that I’m trying to build, and largely influenced the direction I’m headed in.

Zettelkasten — How One German Scholar Was So Freakishly Productive

A popular medium post about zettelkasten. Generally good infio.

You Only Find What You Have Identified

The importance of identifiers in the Zettelkasten archive.

How to Write a Note That You Will Actually Understand

Not only good advice for writing ZK, but generally technical writing.

When Should You Start a New Note?

A helpful flowchart of when to write a new note, when to split a long note, etc. Interesting context for how a zettelkasten works in practice.

Manage Citations for a Zettelkasten

Luhmann’s Zettelkasten with DEVONthink

There are other ways to build a inter-woven linked archive. Here’s one.

Markdown-Specific Implementations

Using nvALT as a Zettel Note Archive

If you don’t already have a preferred text editor, but this idea fascinates you, you should probably just use nvALT. Very helpful for anyone thinking about setting up a ZK.

vim-zettel

Very cool package built on top of fzf and vimwiki.

renerocksai/sublime_zk

A very robust package for sublime text. Popular on the zettelkasten.de forums.

How to Make Yourself Into a Learning Machine

A look into how one zettelkasten fan uses his system to expand his learning power. Some links to some very customized viml scripts to make his system flow.

https://docs.zettlr.com/en/guides/guide-zettelkasten/

How zettlr (an OSS note taking app) can be used for ZK. Obviously by the name, it’s designed a little bit for this.

Some Thoughts on How to Keep a Zettelkasten

A great post on how this writer uses iA Writer to build his ZK.

Supported Zettelkasten-Specific Editors

Being markdown plain text editors, all of these “support” all the features… but which ones have built-in tooling to search? This is by no means an exhaustive list, just the ones that I tested.

If there’s ones I’m missing, feel free to message me and I’ll add them to the table. I know there’s some org-mode/emacs afficiandos out there who have some amazing stuff.

Editor Link Styles Tag Styles Notes
Freelink Other Hashtag MMD Other
nvim + vimwiki :tag:, same as org-mode Vim being vim, you can adjust or grep for any string, so #tag or front matter will work, it’s just not built in.
nvim + vimwiki + vim-zettel Vim’s capability :tag:, same as org-mode Pretty robust… especially for the backlinks.
sublime text 3 + sublime_zk Vim’s capability Seems super well put together… very cool.
Drafts.app drafts:// URLscheme Built-in tags More for capturing information than storing it, but you could do it if you wanted. Drafts.app lists documents by the first line in the document, so while it supports MMD front matter, it makes the title look strange.
Bear.app n/a Honestly… as this app seems to check so many of the options, I’m surprised I haven’t given it a better go.
nvAlt Stores tags in database The search and interface is very good.
nvUltra urlScheme n/a Still in beta… seems very promising. Has a super powerful “related notes” feature that I think is nearly ideal for this.
The Archive.app The OG zettelkasten application.
Zettlr n/a This seems like a cool tool.
1Writer iOS urls
obsidian Supports a graph mode like roam research.

  1. For this document, I’m not going to try to define what the Zettelkasten system or practice is, there are entire blogs and YouTube videos dedicated to this topic. 

  2. I thought I was being very clever… I had originally written this long argument for structuring files this way, but it turns out that the answer has been there all along. 

  3. I’m not really an expert, I only know as much as can be known by reading blog posts on the subject. I haven’t taken a course or read the book. 

  4. It makes searching for in-archive links a lot simpler… imagine you want to write a regex for searching for all notes that link to the current note… it’s a lot easier if you can assume that all in-archive links follow freelink syntax. Some editors go a step further and the text within a freelink is actually more of a search than a file link. (I think The Archive does this.) 

  5. I tested: vimwiki, Bear, nvAlt, nvUltra, Drafts with a custom action and 1Writer 

  6. Editors that don’t support [[free links]] include: Drafts, Vim’s default markdown syntax, iA Writer, and Ulysses 

  7. In my current files, I have been lightly using vimwiki style tags (I think they get them from mediawiki?) They look like :this:. I don’t like writing the regex for these tags, and I can’t find anything but vimwiki that supports them. 

  8. This issue here shows some of the issues that can arise when you allow this in markdown. 

  9. NvUltra uses MMD style front matter for tags, and offers syncing them to OS X metadata so you can search in spotlight, which is very cool. 1Writer uses the #hashtag format for it’s built in tag search. I stole my solution from prolific ZK blogger Christian uses a combo of MMD and hashtag, which I may adopt since 1Writer is pretty nifty on the iPhone. 


Changelog
  • 2020-06-26 13:16:03 -0500

    Add obsidian to the list

  • 2020-06-18 14:26:02 -0500

    Move everything to CST

    Don't know why I didn't do that before. It caused _no_ end of
    problems.

  • 2020-06-14 15:51:50 -0500

    Update articles with series and series partials

    After the refactor, needed to move the series metadata to the actual
    name.

  • 2020-06-14 09:56:03 -0500

    Move zettelkasten files to their own series

  • 2020-06-08 12:34:07 -0500

    Hack together more series pages

  • 2020-03-17 14:37:01 -0500

    :tag: comes from org-mode

    Thanks @benjwrdill!

  • 2020-03-13 11:38:32 -0500

    Post: Simple Markdown Zettelkasten