The more things change, the more they stay the same. As technology and computing has evolved over the last 50 years something has remained constant. Like the guiding light of a lighthouse through the fog one format of data files has always remained a beacon of simplicity and stability no matter what the platform, no matter what the era: the plain text file. One evolution of the plain text file that’s gained a lot of traction with bloggers, developers and even non-technical users is Markdown.

Setting the stage

As the web evolved through the 90’s and into the new millennium the practice of being able to hand-code or hand-edit your website was getting more and more difficult. It was one thing to maintain a site when you didn’t have to worry about complex layouts, CSS or Javascript, but as the Internet was approaching the ‘Web 2.0’ era something was changing. More and more people had websites that separated content from design. What this meant was you could have a site where you did the design once, and then simply treated the content of the site like data.

One example would a a LAMP stack solution like WordPress which launched in mid-2003 — yes WordPress is 20 years old. You managed all of your blog posts as data in a database, and really didn’t need to know anything about website design at all to get something that looked pretty good. In other cases this meant you would hand edit relatively basic HTML just used to mark-up the text or images for your blog post and then could drop that into a template of some kind. It’s this latter case that Daring Fireball‘s John Gruber was able to leverage when he introduced Markdown in December of 2004.

Markdown was born out of the necessity for a lightweight markup language that simplifies text formatting for the web. Gruber’s vision was to design a syntax that produced clean, legible plain text while being effortlessly convertible into HTML—a vision that ultimately gave birth to Markdown. In his own words, "the overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions."

So what does it do?

Markdown has one purpose in life. Allow you to write in a plain text format with some visual cues for different types of markup while keeping the plain text version of the file comfortable and readable.

The syntax of Markdown is simple and user-friendly providing the ability to add formatting to text without taking away from the text itself. The formatting cues are simple and unobtrusive and allows for the document to remain very readable even without the markdown being rendered to visual styles.

When it comes to rendering there are tons of options. Many desktop and web editors have the ability to show both the markdown and rendered versions in the application. There are also lots of scripts and command line tools for rendering markdown to other formats. The majority of the applications and scripts are also platform independent and will work on Linux, Windows, MacOS or work as web-based tools. All you need is something that can edit text.

Common Uses of Markdown

OK, so all that said, let me highlight a few examples of everyday scenarios where Markdown is really shines. These are far from the only possible use cases but they should be enough to trigger the imagination a bit.

1. Blogging: This is kind of the no-brainer example for Markdown given its origins. Markdown is the preferred choice for many bloggers when writing and formatting blog posts. Many popular platforms like WordPress and Jekyll offer Markdown support either natively or with easy-to-add plugins. This allows you to focus on your writing rather than having to wrestle with HTML tags for headings, lists, links, and emphasis.
2. Documentation: In much the same vein as blogging, Markdown is well suited to different kinds of technical writing scenarios. When writing up documentation the requirements are often relatively light in terms of really complex formatting. The big thing is keeping it consistent and easy to read. The plain-text nature of Markdown also allows multiple people across different platforms to collaborate on the same documents without the need for expensive tooling. One caveat here is that Markdown isn’t always well suited to writing up complex scientific or mathematical formulas or equations. They can be included easy enough as images, but to put very complex formulas in as text can be challenging.
3. Note-taking: This is one of the spaces that Markdown has expanded the most in the past few years. Note-taking applications like Notion, Joplin, and Obsidian support Markdown natively enabling users to structure their notes efficiently while ensuring platform independence for their valuable content. Students, professionals, and researchers can use Markdown to organize their ideas, create to-do lists, and add context to their notes. Personally I’ve done the vast majority of my note-taking and writing drafts in Obsidian for the past year or so.

Possible Pitfalls of Markdown

While Markdown is versatile and user-friendly it does have its potential pitfalls. These aren’t necessarily deal-breakers but they are things to keep in mind.

As I mentioned earlier with regards to complex scientific formulas there are limitations in the complexity of layouts. Markdown was originally designed for text, blog posts specifically, and excels in that arena. If you need to format things in a more complex way, it may make more sense to write the draft in markdown, render it to HTML and do the last of your formatting there using something like CSS. Markdown will support tables, but it is a bit clunky and definitely takes away from the readability in many cases.

There is also a bit of a learning curve for Markdown. It’s not a long one, and I think that most people grasp the basics for their use case pretty quickly, but newcomers may encounter initial challenges with its syntax. However, compared to more complex markup languages, Markdown’s learning curve is notably gentle, making it accessible to most.

As the popularity of Markdown has grown, so has the number of variants or flavours of Markdown syntax. While they all more or less adhere to the original Daring Fireball vision, they add their own additional capabilities which are not always compatible. If you are writing for a particular platform with it’s own flavour of Markdown (eg GitHub or MultiMarkdown) it’s a good idea to check over their syntax guide to see if there are any pitfalls before you get too far into your writing project.

Go Forth, and Write

Markdown remains an invaluable asset for content creators, offering a simple, reliable and easily portable option for writing formatted text. The wide variety of common use cases underscore its universal appeal. The next time you have a writing project to do, or if you’re in the market for a new note-taking tool, keep Markdown in mind to help you get your ideas written up with a minimum of fuss.