WTF is Markdown?

Markdown is a readability-focused way to author content for the web. You can think of it as a language, although it's technically not. That's because browsers can't read markdown. Content on the web must ultimately be HTML. Therefore, markdown is really two things:

1. A syntax, or a specification on the behavior of specific characters.
2. A tool that converts the markdown syntax into valid HTML that web browsers can parse.

Syntax Overview

While I encourage you to refer to the CommonMark spec, or the original spec, here's a taste of markdown to show you how it gets out of your way, unlike HTML.

If you want to add a heading in HTML, you need an opening and closing tag, like this:

<h1>Heading 1</h1>
<h2>Heading 2</h2>
<h3>Heading 3</h3>
<h4>Heading 4</h4>
<h5>Heading 5</h5>
<h6>Heading 6</h6>

With markdown, you use a series of hashes at the beginning of the line to indicate 1) that it is a heading, and 2) which level of heading it should be.

The above HTML, written as markdown, looks like this:

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6

More than anything, markdown is a minimalistic means of specifying structure to your content. It's easy to read and write the content while still understanding its structure.

Why Use Markdown?

There are many more reasons to use markdown. Shoot, I'm using it right now in an application called Bear. But of all the reasons, this is why I write with markdown virtually every day:

• Markdown is application-agnostic. It's just text and a specification on how that text should be structured and displayed.
• That also means markdown is future-proof and portable. I can take it out of one application and it's still just markdown.
• Markdown is widely used and supported. I use it almost anywhere I'm authoring content, except for email.
• Markdown is readable on its own. Even if using in a space that does not support markdown, it's still relative easy to understand what's going on without having to parse a bunch of HTML code.

History and Variations of Markdown

Markdown was created by John Gruber in 2004. The "official" syntax can be found here, though there are variations on it which extend its behavior. One of the most popular is GitHub Flavored Markdown, which adds a few features like tables, task list items, and strikethrough text.

Markdown Parsers

The original markdown parser was written in Perl. Today there are many parsing libraries available to you, depending on the language you're using.

For instance, if you're using JavaScript, there's remark, markdown-it, commonmark.js, and many others.

They tend to be fairly easy to discover, too. Here's a nice article from CSS-Tricks if you're having trouble finding or choosing the right parser for your project.

References and Next Steps

There are tons of references out there, so I won't go through an exhaustive list. But I'll start you with The Markdown Guide, which is an excellent resource when getting started. In fact, their Getting Started page is a great place to jump to next.