• 30 min read

• Tools,

  Coding,

  Workflow,

  Opinion Column

Markdown is second nature for many of us. Looking back, I remember starting typing in Markdown not long after John Gruber released his first Perl-based parser back in 2004 after collaborating on the language with Aaron Swartz.

Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.

— John Gruber

That’s almost 20 years ago — yikes! What started as a more writer- and reader-friendly syntax for HTML has become a darling for how to write and store technical prose for programmers and tech-savvy people.

Markdown is a signifier for the developer and text-tinkerer culture. But since its introduction, the world of digital content has also changed. While Markdown is still fine for some things, I don’t believe it’s should be the go-to for content anymore.

There are two main reasons for this:

1. Markdown wasn’t designed to meet today’s needs of content.
2. Markdown holds editorial experience back.

Of course, this stance is influenced by working for a platform for structured content. At Sanity.io, we spend most of our days thinking about how content as data unlocks a lot of value, and we spend a lot of time thinking deeply about editor experiences, and how to save people time, and make working with digital content delightful. So, there’s skin in the game, but I hope I’m able to portray that even though I’ll argue against Markdown as the go-to format for content, I still have a deep appreciation for its significance, application, and legacy.

Before my current gig, I worked as a technology consultant at an agency where we had to literally fight CMSes that locked our client’s content down by embedding it in presentation and complex data models (yes, even the open-source ones). I have observed people struggle with Markdown syntax, and be demotivated in their jobs as editors and content creators. We have spent hours (and client’s money) on building custom tag-renderers that were never used because people don’t have time or motivation to use the syntax. Even I, when highly motivated, have given up contributing to open-source documentation because the component-based Markdown implementation introduced too much friction.

But I also see the other side of the coin. Markdown comes with an impressive ecosystem and from a developer’s standpoint, there is an elegant simplicity to plain-text files and easy-to-parse syntax for people who are used to reading code. I once spent days building an impressive MultiMarkdown->LaTeX->real-time-PDF-preview-pipeline in Sublime Text for my academic writing. And it makes sense that a README.md file can be opened and edited in a code editor and rendered nicely on GitHub. There’s little doubt that Markdown brings convenience for developers in some use cases.

That is also why I want to build my advice against Markdown by looking back on why it was introduced in the first place, and by going through some of the major developments of content on the web. For many of us, I suspect Markdown is something we just take for granted as a “thing that exists.” But all technology has a history and is a product of human interaction. This is important to remember when you, the reader, develop technology for others to use.

Flavors And Specifications

Markdown was designed to make it easier for web writers to work with articles in an age where web publishing required writing HTML. So, the intent was to make it simpler to interface with text formatting in HTML. It wasn’t the first simplified syntax on the planet, but it was the one that gained the most traction over the years. Today, the usage of Markdown has grown far beyond its design intent to be a simpler way to read and write HTML, to become an approach of marking up plain text in a lot of different contexts. Sure, technologies and ideas can evolve beyond their intent, but the tension in today’s use of Markdown can be traced to this origin and the constraints put into its design.

For those who aren’t familiar with the syntax, take the following HTML content:

The Markdown syntax is designed to be easy-to-read and easy-to.write.

With Markdown, you can express the same formatting as:

The [Markdown syntax](https://daringfireball.net/projects/markdown/syntax#philosophy) is designed to be _easy-to-read_ and _easy-to-write_.

It’s like a law of nature that technology adoption comes with the pressure to evolve and add features to it. Markdown’s increasing popularity meant that people wanted to adapt it for their use cases. They wanted more features like support for footnotes and tables. The original implementation came with an opinionated stance, which at the time were reasonable for what the design intent was:

For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.

— John Gruber

In other words, if you want a table, then use

. You’ll find that this is still the case for the original implementation. One of Markdown’s spiritual successors, MDX, has taken the same principle but extended it to JSX, a JS-based templating language.

From Markdown To Markdown?

It can look like Markdown’s appeal for many wasn’t so much its tie-in to HTML, but the ergonomics of plaintext and simple syntax for formatting. Some content creators wanted to use Markdown for other use cases than simple articles on the web. Implementations like MultiMarkdown introduced affordances for academic writers who wanted to use plain text files but needed more features. Soon you would have a range of writing apps that accepted Markdown syntax, without necessarily turning it into HTML or even using the markdown syntax as a storage format.

In a lot of apps, you’ll find editors that give you a limited set of formatting options, and some of them are more “inspired” by the original syntax. In fact, one of the feedbacks I got on a draft of this article was that by now, “Markdown” should be lower-cased, since it has become so common, and to make it distinct from the original implementation. Because what we recognize as markdown has also become very diverse.

CommonMark: An Attempt To Tame Markdown

Like ice cream, Markdown comes in a lot of flavors, some more popular than others. When people started to fork the original implementation and add features to it, two things happened:

1. It became more unpredictable what you as a writer could and couldn’t do with Markdown.
2. Software developers had to make decisions of what implementation to adopt for their software. The original implementation also contained some inconsistencies that added friction for people who wanted to use it programmatically.

This started conversations about formalizing Markdown into a specification proper. Something that Gruber resisted, and still does, interestingly, because he recognized that people wanted to use Markdown for different purposes and “No one syntax would make all happy.” It’s an interesting stance considering that Markdown translates to HTML, which is a specification that evolves to accommodate different needs.

Even though the original implementation of Markdown is covered by a “BSD-like” license, it also reads “Neither the name Markdown nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.” We can safely assume that most products that use “Markdown” as part of their marketing materials haven’t acquired this written permission.

The most successful attempt to bring Markdown into a shared specification is what is today known as CommonMark. It was headed by Jeff Atwood (known for co-founding Stack Overflow and Discourse) and John McFarlane (a professor of philosophy at Berkely who’s behind Babelmark and pandoc). They initially launched it as “Standard Markdown,” but changed it to “CommonMark” after receiving criticism from Gruber. Whose stance was consistent, the intent of Markdown is to be a simple authoring syntax that translates to HTML:

@davewiner And that’s what’s flawed with CommonMark. They want to make things easier for programmers as a primary goal. They miss the point.

— John Gruber (@gruber) September 8, 2014

I think this also marked the point where Markdown had entered the public domain. Even though CommonMark isn’t branded as “Markdown,” (as per licensing) this specification is recognized and referred to as “markdown”. Today, you’ll find CommonMark as the underlying implementation for software like Discourse, GitHub, GitLab, Reddit, Qt, Stack Overflow, and Swift. Projects like unified.js bridges syntaxes by translating them into Abstract Syntax Trees, also rely on CommonMark for their markdown support.

CommonMark has brought a lot of unification around how markdown is implemented, and in a lot of ways has made it simpler for programmers to integrate markdown support in software. But it hasn’t brought the same unification to how markdown is written and used. Take GitHub Flavored Markdown (GFM). It’s based on CommonMark but extends it with more features (like tables, task lists, and strikethrough). Reddit describes its “Reddit Flavored Markdown” as “a variation of GFM,” and introduces features like syntax for marking up spoilers. I think we can safely conclude that both the group behind CommonMark and Gruber were right: it certainly helps with shared specifications, but yes, people want to use Markdown for different specific things.

Markdown As A Formatting Shortcut

Gruber resisted formalizing Markdown into a shared specification because he assumed it would make it less a tool for writers and more a tool for programmers. We have already seen that even with the broad adoption of a specification, we don’t automatically get a syntax that predictably works the same across different contexts. And specifications like CommonMark, popular as it is, also have limited success. An obvious example is Slack’s markdown implementation (called mrkdown) that translates *this* to strong/bold, and not emphasis/italic, and doesn’t support the [link](https://slack.com) syntax, but uses instead.

You’ll also find that you can use Markdown-like syntax to initialize formatting in rich text editors in software like Notion, Dropbox Paper, Craft, and to a degree, Google Docs (e.g. asterisk + space on a new line will transform to a bulleted list). What’s supported and what’s translated to what varies. So, you can’t necessarily take your muscle memory with you across these applications. For some people, this is fine, and they can adapt. For others, this is a papercut and it keeps them from using these features. Which asks the question, who was Markdown designed for, and who are its users today?