Something as simple as note taking has had a surprisingly tricky history. It seemed obvious in the heyday of desktops to have a notepad application, or even sticky pads. People wrote notes. Sometimes they emailed them. That was it.

But as screens got larger and clearer, text needed changes of fonts, different tabulations, italics, bold, and even color. Storing this information in a proprietary way got increasingly foolish, as personal computing expanded. Even after the great word processing empires came along, people still wanted to make short portable notes.

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

…used to reference the clearing of a throat, or to commence a toast.

Or the recent meme:

…where we are literally asked to imagine the speaker is ruffling some 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.

Markdown, invented in 2004 (but only settled a decade later) by John Gruber and Aaron Swartz, was aimed at making a human-readable open format that could be rendered into nice-looking 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 is quick to learn, to boot.

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

Back in the day, we saved notes in Rich Text Format (RTF), because that is 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 does have critics in the emoji era, because those born with iPhones like to mark-up things themselves and have no interest in Generation X telling them how to do it. Regardless, Markdown has achieved its aim of being a readable format that deftly captures markup. 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 has come into its own.

First, the Basics

To start with, let’s take a look at some basic Markdown. Like all good standards, no two authorities entirely agree on all the more advanced stuff, but the syntax below is always supported.

Here are some headings:

There are alternatives. Most Markdown has 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 to the online formatter dillinger.io, we get:

To create a blockquote, add a “>” as the first character in the line. This should already feel familiar from email.

And lists need no more than a dash (or plus symbol, or asterisk) and a space. For an ordered list, just a number followed by a dot and a space. Add four spaces or a tab, and you will get an indentation. The application will usually handle the enumeration:

This should render as:

How do you indicate that you do not want a section formatted? For example, because you are using a code snippet? Use a code block, which is indicated by typing four spaces or a tab.

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

As an example, this:

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

The simplest form of link can be expressed as:

as you might expect, this displays as:

There are a plenty of syntax rules handling more complex objects like 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 knowledge base. With Obsidian and similar tools, these are easy to create, easy to share and likely to remain usable. If you’ve ever managed a wiki, you may remember how relatively cumbersome they were to use — plus, exporting the data was likely not possible.

Obsidian is both an editor and formatter for Markdown. It also provides many additional tools and plugins. Its major benefit, however, is how well it supports internal links:

The double brackets indicates a link to a document named “ducknote.md”. After the pipe, you can add an optional display text for the link. You can also link to a paragraph within the document.

If you’ve seen any wiki fan sites (for example wookieepedia) you already know what a knowledge base or knowledge network is. It just means a growing set of documents that interlink in a structured but non-formal fashion. This is by far the best way to write a relatively organised set of notes, in any order you wish, linking when you want to.

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.”

Creating a Winnie The Pooh Knowledge Base

So let’s quickly run Obsidian through its paces, as I start my ill thought-out Winnie The Pooh knowledge base.

First we create a new vault; this is just a directory of markdown files.

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

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

In reading mode, this renders to:

Of course, Poo’s best friend is Piglet — not Roo. After making Piglet’s page, I can immediately create a link back to Pooh just by opening two square brackets. Note the hint:

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

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

Finally, you can see that the content 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-linked documents that aren’t trapped forever in a propriety 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 via Pexels.