October 22, 2020

The story behind Markdown.

How plain text got formatting, styled like classic emails.

by @maguay

Founding editor @capiche. Writer. Amateur photographer. Information architect. Older work: @zapier, @AppStorm. Personal blog: @techinch.
maguay's avatar
Categories
Writing

To hear an audio take on this story, subscribe to SaaS Radio Hour.

It all started when Charlie Brown let out a *sigh* at the state of things.

Good grief, he'd say when the going got tough. But words alone couldn't express the full human experience. So Charles Schulz reached for the asterisk, wrapping it around things that weren't quite words, things like whew, ahem, and sniff.

Decades later, we'd call that Markdown, use it to format text without clicking buttons, to write for the web without HTML. Schulz sketched the perfect antidote for our typing times.

On formatting.

Peanuts with Markdown formatting

Formatting lets you emphasize words and raise your voice on occasion, organize ideas with headings and lists. It's critical for the web, where linking references is half the point.

You could live without it; the alphabet, numerals, and punctuation are enough. But why not.

And so, humans innovate, as they do. Give them a clay tablet, and they'll press the stylus a bit harder to emphasize words. Give them a typewriter, and they'll type over text again to make it a bit stronger. Give them a handful of punctuation characters, and they'll turn them into formatting and emoticons.

The arts led the way, in comic strips of the 1900s. As linguist Ben Zimmer found, parenthesis then asterisks showed up to emphasize words like sniff and sigh mid-sentence for added effect. Charles Schulz' Peanuts used them more liberally, and they stuck.

Emails with markdown-style formatting

Decades later, Peanuts-style formatting would show up in email.

"Email was plain ASCII," recalled Low End Mac's Dan Knight in a 2000 article on email formatting. "No bold face. No italic. No fonts. No color. Just text."

So early email senders got creative. They borrowed from the world of typewriting, with two dashes for an em dash, lines of asterisks to indicate line breaks, and underlined text for headers. They added comic strip-style asterisks and underscores around words to add emphasis. Lists came with both dashes and asterisks; quotes and links came with new tech-influenced greater-than symbols and square brackets.

"I love writing email," wrote Markdown creator John Gruber shorter after launching the email-inspired standard. And thus the ad hoc symbols became a standard.

atx: Structured text

atx formatting

Computers, though, would complicate things before we'd rediscover the art of formatting with characters.

First came rich text editing, with button-filled toolbars and keyboard shortcuts that put a print shop's toolkit on your desk. Then came HTML, with its formatting syntax where you'd wrap everything in <something></something> or other.

Copy rich text from one app to another, and your formatting might stay the same, or it might look vastly different. HTML always looked the same—but it was never easy to read or write.

"I'm sick of bringing my writing down to the level of the computer," wrote Aaron Swartz, the programmer who influenced so much of the publishing web including the RSS format and Creative Commons' license. "Why should I have to cover everything in annoying pointy brackets just so it knows what I mean?"

So in 2002, he codified a simpler way in atx. "I'm not really interested in writing another <p> or </blockquote>. I'll have my computer do it for me," remarked Swartz in an email list.

So in atx, a new line meant a new paragraph, no <p> needed. You could add em and en dashes (with 2 or 3 hyphens, respectively), single and double quotes (with single or double backticks), underscore for italics, asterisks for bold, hash symbols for headings, pipes for code. Lists started with numbers or asterisks.

atx was similar enough to Markdown. But it wasn't quite enough. "I need to figure out some way of doing links," wrote Swartz, before describing wrapping text in square brackets then including the actual links at the end of the page.

But it was a start. "I want something good enough to replace HTML and XML for writers," said Swartz, and he was halfway there.

Textile: Bulletproof plaintext-to-HTML

Textile formatting

For all the trouble of writing HTML, it still didn't give the style of true typeset text.

"For years I’ve been trying to imagine a bulletproof web-based plaintext-to-HTML system," wrote designer and writer Dean Allen, someone Gruber would later eulogize as one who "strove for perfection and often achieved it."

Allen wanted an easier way to format text "without the writer having to think very much about it," along with ways to make HTML a better typographic citizen "that respects typographic standards and the correct presentation of non-standard characters."

Thus came Textile in 2002, as what seemed for years as the primary rival to Markdown.

Textile was interested in real typography: Single underscores for emphasis, double underscores for italics. Single asterisks gave strong; double gave bold.

You could add footnotes, superscripts, and subscripts, add classes to paragraphs and right, left, center, or justify. It was the typographic parts of HTML, simplified, “automatic conversions from plain text conventions left over from the manual typewriter to their typographic equivalents,” as Allen explained.

Allen was under no illusions Textile would change your life. He wanted to “offer shortcuts to style text (bold, italic) that may save minutes over the course of a lifetime,” his launch post said.

But minutes add up, and Textile soon would be the way you'd format text in Basecamp. Even today it influences Slack's plain-text formatting. "It was very well received, one of those ideas that people looked at and instantly liked," remarked Gruber.

Markdown: Email formatting, formalized.

Markdown formatting

Gruber wanted something simpler, something closer to the way he’d originally described Textile as a way to "write using email-ish plain text."

“Email is my favorite writing medium,” wrote Gruber. “The conventions of plain text email allow me to express myself clearly and precisely, without ever getting in my way.”

Gruber looked back at the earlier emails he'd loved and saw inspiration for a better way to write. "If you look at any transcripts of Internet email from the 90s, using *this* and _this_ were extremely common," Gruber told me in an email conversation. Where Allen saw typewritten text as the inspiration, email spoke to Gruber. A decade earlier, Setext had tried to standardize email markup, with headings underlined with equals signs, italics with tildes, bold with double asterisks. What could a simpler version of email-based formatting look like?

So two years after Textile launched with the smart quote algorithm he'd help code, Gruber followed up with his own thing—with Textile creator Dean Allen’s blessing.

"I was badgering Dean with a series of 'Why don’t you change the syntax of Textile to be more like this and this?' requests," remembered Gruber years later. "Dean’s response was, more or less, 'These are great ideas, but why don’t you just put them in your own thing?'"

So he dug in, along with Aaron Swartz. "Together we pored over the syntax details from top to bottom, trying to develop the perfect format," wrote Swartz. "It was like finding my way through a maze," recalled Gruber. "I went down many wrong paths, tried out numerous ideas that struck me as good until I actually tried using them."

Markdown didn't cover everything HTML did; if you needed more, you can add HTML inline. What it did cover were the things you’d use to write and blog, borrowing from plain text email formatting where possible. One underscore or asterisk for italics (matching the convention in emails in the ‘90's and comic strips from the ‘60’s and earlier), two asterisks or underscores for bold, greater-than symbols for quotes (as email apps show quoted sections of previous emails in replies), and hashes for headers (something ATX, email, and typewritten documents all used).

And it worked. "I think we’ve got something pretty darn great," wrote Swartz. "If you’re not interested," wrote Gruber, "I’ll try to change your mind in a bit.

The plain text formatting standard.

App Store featuring Markdown apps

That wasn't necessary. Markdown was everywhere soon enough.

That first year saw Movable Text and WordPress gain Markdown support. Basecamp co-creator David Hansson built a Markdown-powered wiki. Productivity blogger Merlin Mann caught himself "writing—in longhand, mind you—using Markdown," as the syntax had become second-nature.

An entire category of focused writing apps grew up around Markdown's popularity. The iPhone was years away when Markdown launched, but it too benefited from the character-driven formatting when early apps often lacked formatting tools.

Markdown even showed up in newsprint—though, perhaps more inspired by the comics of yore—when a 2013 New York Times article included *cough*, asterisks and all.

People loved it. "Not to pat myself on the back, but I think it's because everything was very thoughtfully considered," Gruber told me. "Markdown's conventions for the basics are a very nice combination of being easy to type, natural to read, and just plain look good."

And it became the basis for newer formats. MultiMarkdown added tables, footnotes, math, and some of the smart typography Textile sought to simplify. GitHub Flavored Markdown took the original Markdown ideas and the CommonMark spec, and tweaked them to fit the needs of their product (which, in GitHub’s case, needed better code escape tools in Markdown).

"Make up your own thing and see if it catches on," advised Gruber on The Talk Show, echoing earlier advice Allen gave him.

The markup that works the way you want

That spirit is what's made Markdown endure. It can be whatever you want it to be. There's no one way to use it; pick the way that's easiest for you.

Markdown gives two ways to write bold and italics, two ways to add code blocks, three ways to add bullet lists. There was no default file format; txt worked, Gruber used .markdown, and .md became common over the years as well.

"More or less: why not? Better to let people choose the character that feels most natural to them," explained Gruber in a post about Markdown unordered lists, where a Twitter poll showed 54% of people using hyphens and 42% using asterisks for unordered lists.

"I believe Markdown’s success is due to, not in spite of, its lack of standardization," Tweeted Gruber in 2014, as the web debated whether Markdown should be more standardized. "Different sites (and people) have different needs," he explained further down. "No one syntax would make all happy."

What did make all happy was writing, editing, and publishing without thinking much about formatting.

“When you write and read text that’s marked-up with HTML tags, it’s forcing you to concentrate on the think of it," wrote Gruber. "It’s the feel of it that I want Markdown-formatted text to convey.”

And then it became a legend

"New technology seldom eliminates old technology," wrote Mark Kurlansky in his history of Paper. "It only creates another alternative."

And so it was with rich text.

Textile still lingers in parts of the web, and Markdown, for all its popularity, will never replace rich text.

"When you make a product used by millions, you quickly see how confusing anything is that revolves around text editing," said Basecamp founder Jason Fried when asked why Basecamp switched to a rich text editor instead of the plain text Textile formatting it supported before.

But the spirit lives on. Even in today's rich text editors, toolbars are shrinking, or hiding away until you select text to format it. Markdown taught us we could write without distraction, putting ideas into words without reaching for the mouse all the time. Markdown even became a generic term for plain text formatting; Slack's markup is closer to Textile, with asterisks for bold and underscores for italics, but they referred to it as markdown formatting.

And like email, Markdown has become one of the most enduring parts of tech.

Explore plain text formatting.

Listen to the history of Markdown.

For an audio take on this story, subscribe to the Capiche team's new SaaS Radio Hour show and add it to your favorite podcast player—then listen to The Story behind Markdown episode for a narrated version of this post. To broadcast your own live audio discussions, check out Capiche.fm

Special thanks to neurocline on HN for the suggestion of including Setext.

FORMAT WITH MARKDOWN; DRAG AND DROP IMAGES
starfish_mod's avatar
@starfish_mod (replying to maguay )
30d

As an aside the new MIDI 2.0 Property Exchange spec now defines Commonmark as the way to send formatted text between devices.
It was chosen specifically to avoid the rapid evolution of HTML. MIDI devices have a 20+ year lifespan and some can only show text. This way devices that can show formatting can do so - while the rest can just display the text.
Full disclose I'm one of the authors.

4 points
1.0 more reply
bludrop's avatar
@bludrop (replying to maguay )
a month ago

RIP Textile

2 points
1.0 more reply
ybbond's avatar
@ybbond (replying to maguay )
a month ago

Great article as always!

I just knew that Gruber and Swartz knew each other and worked on markdown.

2 points
1.0 more reply
gabriel's avatar
@gabriel (replying to maguay )
a month ago

🔥🔥🔥🔥

2 points
1.0 more reply
misterpants1976's avatar
@misterpants1976 (replying to maguay )
a month ago

It's Charles Schulz, not Swartz.

2 points
1.0 more reply
What's the best tool for building a customized API documentation?

Let's say you have an API you want to document and you want to: - Let your users test their calls to the API thanks to a "playground" like the one on the Figma API - Be able to customize it to matc...

What's the best way to get feedback about a design or product?

Do you have a favorite survey or poll tool to get feedback, or a unique process to get actionable insights from your users about your design, product features, pricing, and more? There was an inte...

The community for power users.