Obsidian and the Case for Using More Markdown – The New Stack

Something as simple as note taking has had a surprisingly tricky history. It seemed obvious in the heyday of desktop computers to have a notepad application, or even notepads. People wrote notes. Sometimes they sent them e-mails. That was it.

But as screens got bigger and clearer, text required font changes, different tabs, italics, bold, and even color. Storing this information exclusively has become increasingly foolish as personal computing has developed. Even after the rise of the great word processing empires, people still wanted to make short portable notes.

The concept of “marking up” text to suggest emphasis has always existed. Think casual:

…used to refer to throat clearing or to start a toast.

Or the recent meme:

…where we are literally asked to imagine the speaker ruffling through papers trying to find something written earlier. In either case, the casual reader understands that the asterisks are not part of the message, but part of how the message is expressed.

Reduction, invented in 2004 (but settled only a decade later) by John Gruber and Aaron Swartz, aimed to create an open, human-readable format that could be rendered into pretty HTML-like text. So yes, Markdown is a form of markup.

The two main reasons to learn Markdown are platform independence and speed. And it’s quick to learn, to boot.

Naturally, the point of adding markup is that it will be consumed by applications that will render it correctly, or at least imported and then converted to an application’s native format. Popular apps like Notion will spit out Markdown, helping portability.

At the time, we recorded notes in Rich text format (RTF), because that’s what Microsoft’s WordPad used. And RTF is perfectly readable today. But no one would seriously consider manually marking up text like this, using RTF:

Now Markdown has critics in the age of emojis, because those born with iPhones like to mark things themselves and have no interest in Gen X telling them how to do it. Either way, Markdown has achieved its goal of being a readable format that captures markup deftly. And with Obsidian, which claims to be “a powerful knowledge base on top of a local folder of plain text Markdown files”, I think it made perfect sense.

First, the basics

To get started, let’s take a look at some basic Markdown. Like all good standards, no two authorities fully agree on all the most advanced things, but the syntax below is still supported.

Here are some sections:

There are alternatives. Most Markdown have alternatives; that way it can play well with other formats that already use the same markup. For example:

Italic and Bold:

If we use the above as input for the online trainer dillinger.iowe have:

To create a blockquote, add a “>” as the first character on the line. This should already sound familiar to you over email.

And lists only need a dash (or a plus symbol or an asterisk) and a space. For an ordered list, just a number followed by a period and a space. Add four spaces or a tab and you’ll get an indent. The application generally handles the enumeration:

It should display as follows:

How do you indicate that you don’t want a section to be formatted? For example, because you are using a code snippet? Use a code blockwhich is indicated by typing four spaces or a tab.

Now, when it comes to continuous formatting – like lists and code blocks – you’re slightly at the mercy of the renderer’s implementation. Judicious use of blank lines before and after is recommended to indicate that you want to start or break this style of format. This is the area most likely to cause consternation to the unwary.

For example, this:

…is rendered correctly (in dillinger.io) once the two empty lines are present. Note that the asterisk in the code block is effectively ignored:

The simplest form of link can be expressed as follows:

as you might expect, it displays as follows:

There are many syntax rules dealing with more complex objects such as tables, all of which you can see here.

Obsidian and its Markdown knowledge base

This is all great, but we can also work between separate Markdown document files. The ability to create a set of linked documents supports the creation of a database. Along with Obsidian and similar tools, these are easy to create, easy to share, and likely to stay usable. If you’ve ever managed a wiki, you might remember how relatively cumbersome they were to work with – plus exporting the data probably wasn’t possible.

Obsidian is both an editor and a trainer for Markdown. It also provides many additional tools and plugins. Its main advantage, however, is its ability to support internal links:

The double brackets indicate a link to a document named “ducknote.md”. After the tube, you can add optional display text for the link. You can also link to a paragraph in the document.

If you have seen any wiki fan sites (e.g. wookieepedia), you already know what a knowledge base or knowledge network is. It simply means a growing set of documents that fit together in a structured but not formal way. This is by far the best way to write a relatively organized set of notes, in whatever order you want, connecting them whenever you want.

This should prepare you for how Obsidian describes itself: “Obsidian is a powerful knowledge base on top of a local folder of plain text Markdown files.”

Creation of a Winnie the Pooh knowledge base

So let’s quickly get Obsidian through its paces, as I begin my thoughtless Winnie The Pooh knowledge base.

We first create a new to jump; it’s just a directory of markdown files.

Obsidian has its own cloud option, but if you just want to share notes between your laptop and desktop, or a few team members, vault sharing in Google Drive or similar works perfectly fine.

We create our first document file (”Pooh Bear.md’). I turned off live preview so you can see the Markdown:

In read mode, this gives:

Of course, Poo’s best friend is Piglet – not Roo. After creating Piglet’s page, I can immediately link to Pooh simply by opening two hooks. Note the clue:

…and I have the opportunity to create a new note from my reference to “Hundred Acre Woods”, after putting it in double brackets:

Hovering over a link in read mode indicates whether the link is valid or not.

Finally, you can see that the contents of my vault is just a directory with two Markdown files and a meta directory.

I hope this encourages you to use Markdown, as well as form-related documents that aren’t forever trapped in a proprietary format.

The New Stack is a wholly owned subsidiary of Insight Partners, an investor in the following companies mentioned in this article: Duck Duck Go.

Photo by Troy Squillaci through Pexels.