WNW What is this Markdown Stuff?

Obsidian, like many new note taking systems uses markdown to structure your notes. But what is markdown and where did it come from? I'm glad you asked, this post gives some answers.

WNW What is this Markdown Stuff?

One thing you will notice about all of my Obsidian files is that they consist almost entirely of Markdown. But what is Markdown? I'm a big fan of innovation, and I love origin stories. To quote Hunter S. Thompson

Today's weirdness is tomorrow's reason why.

The Originals of Markup Languages

There's a story I read years ago that talks about some scientists who wanted to reexamine the data from the Voyager space probe. The Voyager Space Probes were a product of 70s NASA engineering, and as a result they embodied the early computer thinking of discrete components designed to do a single job.

More than a decade later NASA engineers sought to revisit the data from the space probe and were shocked to find a print out filled with 1s and 0s. Hundreds, and hundreds of pages of 1s and 0s. And nothing else. This was "The Voyager Probe Data." And it had become virtually worthless because the meaning of the data was encoded in the engineers heads who created the system. And they had all retired.

Only by finding a report from a retired engineer from the original project were they able to recover the information they sought.

This experience launched the drive for a self describing data formats, one that could persist across time and career change. This lead to the creation of SGML - or Standard General Markup Language which became a standard in 1986.

About a decade later, the Hyper Text Markup Language - a subset of SGML was created to focus on web page content. HTML was designed to be simpler, easier to use, and compatible with the internet.

Don't ask About XML
The Extensible Markup Language was adopted as an internet standard by the World Wide Web Consortium in 1998. HTML focuses on web pages, XML can handle just about everything else.

Despite how awesome HTML is at describing page contents, it is both cumbersome to write, and cumbersome to read. Even today, people talking about being able to "code" HTML. Mentally and emotionally, many people think about HTML as a kind of separate and special programming language.

It is this awkwardness that Markdown was born to fix.

The Birth of Markdown

In 2004, John Gruber with contributions from Aaron Schwartz wanted a form of mark up, specifically for text documents that met the following criteria:

  • Easy to write (fast and intuitive)
  • Easy to read (without converting to something else)
  • Resembled the written language and plain text as much as possible. (few special characters or odd syntaxes)
  • Could be converted to HTML easily.

Basically, they wanted a way to capture the author's intent. They wanted to separate what the anuthor meant to do, from how the authors work would be presented. How did the author want to structure their document? What words should be emphasized (using say, italics), and which words should be bold? (bold)? Should a list be unordered (bullets), with no priority? Or should a list be ordered, like a sequence of steps in a process (ordered list).

There is no underline in markdown
In 2004, Underline was the predominant way of displaying links, so there was no need to include underlining. If something was underlined in the early aughts, (or 00s if you prefer), then it must be a hyper link right?

And, above all the new markup format should be efficient. That means it is easy to type, using as few keystrokes as possible without interfering with the creative process. Ideally, the author would not have to move their fingers from the keyboard or make awkward stretches to apply formatting.

And one other thing

In 2004, if you wanted to write a document, meant for humans to read, you could use a plain text editor - like notepad, or some programming editor, like XCode, Visual Studio, or vi, or eMacs, or you could use a word processing application like MS Word, Apples Pages, or Google Docs. (Google docs launched in 2006). But if you used a word processor, you were locked into their format. Even though Microsoft moved to an open standard, you needed to be a programming genius to decode their .docx format. And copying and pasting between word processors and web applications is still a nightmare.

I often spent as much time reformatting what I wrote as I did writing it.

Markdown solved the problem for me.

Super Portable

One reason I love Obsidian is that I always own my data. It is just markdown files, images, and pdf's stored on my hard drive. And yes, it is back up in the cloud, but I never need to export any of it to get it.

Markdown is kind of the same way. If you write in markdown, you can take your text and paste it into a wide variety of web applications and your structural intent will be preserved.

You can change the way the structure is presented (say choose a different font, background color, etc), but the organization of your document - such as headings, and lists should remain intact.

As a matter of fact, by early 2024 Google recognized the growing dominance of markdown and Google Docs now allows you to write in markdown - it converts your markdown code to google formats. Getting the content out of google docs is still a chore, but it is possible.

So how do you use this?

First, there are lots of great tutorials and manuals. Obsidian offers one:
Obsidian Flavored Markdown , and Github Markdown is another great place to start.

But the reality is, I learned pretty much by looking at markdown documents.

I think it would be a bit much to replicate the markdown documentation here, but I will give you a list of the shortcodes I use the most:


I use the # to create headings. These will translate into HTML <H1></H1> headings when displayed. The more hash's you put, the higher the heading number...

# Level 1 Heading
## Level 2 Heading
### Level 3 heading
... you get the idea


Level 1 Heading

Level 2 Heading

Level 3 heading

... you get the idea

I am a big fan of lists.

1. A number followed by a period, followed by a space will start a numbered list.
2. Second item in the list. 
3. Third item


  1. A number followed by a period, followed by a space will start a numbered list.
  2. Second item in the list.
  3. Third item
The Numbers May Change As a heads up, the final piece of software (such as your website) might renumber your list.

And I love bullet lists.

- A hyphen followed by a space makes a bullet.
* The same is true with an asterisk


  • A hyphen followed by a space makes a bullet.
  • The same is true with an asterisk

I don't recommend using asterisks (*) to start bullet lists because asterisks do other things in markdown like...

Mark bold, and italics.

This one is a little tricky. There are multiple ways to do this, but I settled on using two asterisks to mark bold (the most common standard), and underscores mark italics, or emphasized text. And, if you need to mark something as a code, you can use back ticks to do it.

However, you can also use a single asterisk to mark something as emphasized.

**Bold Words**
_Italics text_
*Also Italics Text*
`fixed font code`

Bold Words

Italics text
Also Italics Text

fixed font code


And, this more than anything is what drove me away from Evernote... The need to store code snippets. One reason I suspect GitHub selected markdown is that markdown is excellent at representing structured code in a variety of formats. In 2015, 2016 Evernote just could not safely (or correctly) handle code. What's more, most markdown editors support what is called syntax highlighting. Meaning when you save code in a document, that code will be color coded in much the same way as your programming editor.

This was gaming changing for me. I could write a simple script, save it in Obsidian, and document its use case, and explain what I was trying to do, and where I was trying to do it. My largest Resource folder by file count is my Script folder.

All of the markdown examples I have used above are captured using code blocks. But you can save python, JavaScript, JSON, even markdown code inside of code blocks. code blocks start and end with three back ticks.

A sample bit of JavaScript code.

let x = 5;
Let b = 6 * x;


For a long time, markdown editors looked like programming applications, But I first noticed a change with ByWord, later followed by IA Write, and many others. They made a true WYSIWYG markdown editor (What you See Is What You Get). Obsidian follows that trend. When you type in markdown, the editor immediately converts your text into a beautiful representation of what you intended.

And, you can use different styles, to change the font, and style of how your text is represented (rendered) inside the editor.

As an example, I was able to modify my Obsidian style to match the Bear Note app on the Mac (Bear never made a note app for Windows Or I might not be here today using Obsidian).

ChatGPT Hack
If you use AI to help you write blog posts, you can ask ChatGPT or Claude AI to render your article in markdown format. IME most of the AI tools understand markdown.


So, in short, Obsidian, true to their core values, tries to maximize for portability. Your files are stored on your local machine, and they use an open standard for storing information in those files.

Even if you don't use obsidian, I would encourage you to take a look at markdown as a means for authoring your text content. The headaches it saves you when you port to other platforms is enormous and more and more systems are supporting it.