We should use markdown more

These words are being written in markdown. Created in 2004 by John Gruber and Aaron Swartz, and subsequently expanded with no explicit standardisation into numerous “flavours”, markdown is a way of writing text using characters to “mark” the formatting of text without visibly formatting it.

While adoption of markdown seems to be on the rise, there has also been a widening rift between various schools of thought on markdown and its use. On the one hand are people who use markdown everywhere; then there are those who like to use it whenever they type up blocks of text (this is where I position myself); still others restrict its use to specific cases (such as “outlining”, on which more later) while preferring rich, or formatted, text everywhere else (surprisingly, Gruber sits among this crowd); and finally there are those who simply abhor it.

My interest in writing about this topic came after I read Russell Beattie’s piece on markdown recently (although the article itself is about a year-and-a-half-old) and it struck me that the differing positions on markdown come from fundamentally different philosophical tendencies amongst its users—or naysayers. What I want to do is address, categorically, all the objections to markdown that I have come across; but before I do that, and to make my responses more sensible, I need to do some quick ground work.

The ground work

Why markdown exists

Go back to where markdown began with Gruber and Swartz and you find these telling sentences: “Markdown is intended to be as easy-to-read and easy-to-write as is feasible. Readability, however, is emphasized above all else. 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.”

Their line of thinking is quite clear and, even today, clarifies what makes markdown such a powerful solution. Most flavours of markdown continue to keep it readable as was originally intended. Those that fail to do so involve some sort of yaml or stretch markdown to incorporate esoteric markup tags with no general use cases.

This also highlights another important aspect of markdown: what it is not. Markdown is not HTML. Markdown is not an image manipulator. Markdown is not a programming language with a debugger. Markdown is not an alien spaceship.

Portability is key

When technology was young, novelty ruled the market. A new piece of software could come up that heroically brought its own format and manner of doing things. Over time, as with any market, competitors came in and brought their own approach into the mix. As the leadership constantly changed hands, so too did the popularity of an approach, forcing users to swing between numerous, vendor-locked systems.

Then the consumer got wise. It started to dawn on us that whatever approach I choose to use to accomplish tomorrow, my content should fundamentally remain unchanged. This was especially true of text-based documents but also, to a reasonable extent, of presentations, spreadsheets and code.

So if I can no longer pay for Microsoft Word—or do not want to—what happens to my word documents? One obvious solution for people was to resort to plain text: the good old ASCII-powered assortment of letters. Nothing more than a digitised typewriter. But what if I wanted to include images or headings or format text with bold or emphasise it with italics or even type code or some such thing?

Markdown was the answer: with **bold** and *italic* formatting, and with # Heading 1 or ## Heading 2 or even [linking text](/to/a/url) and more, it allowed us to write in plaintext with some formatting markers that kept the original content readable and straightforward while also translating it to look bold or italic or whatever else.

As emacs creator Carsten Dominik pointed out 16 years ago, plain text is “the only truly portable format”. This is a critical aspect of markdown that we will do well to keep in mind for our upcoming discussions.

The objections

Note that I do not disagree outright with all aspects of all objections. For each objection I address I also specify how far I disagree with it and why—or why not—and what we can do about it.

Objection 1: It is not a specification

Russell points out in his article that markdown is not a specification and he is right. But the primary definitions of markdown (the bold, italic, link structure etc.) are in fact an unwritten standard today. I agree that actual standardisation is needed but to discard it despite an informal standardisation existing is unreasonable to me.

The takeaway for now: I agree that we do need standardisation (more on this later).

Objection 2: Semantic elements are missing, plus videos do not get embedded

This feels to me a bit like pointing out you cannot pinch to zoom on foolscap paper. Markdown was never intended to write an entire webpage with <main> or other semantic tags, or even embed videos for that matter. If anything, embedding images was already a step too far. Markdown is designed for writing text and it does that well. This should cover 75% of the average article. For the rest, split up markdown into blocks and drag-and-drop stuff in-between, or better still use HTML because all HTML is valid markdown anyway.

Objection 3: Metadata, YAML etc.

Again, bringing these up is a classic indication that markdown use has been stretched thin. Markdown was not designed to be used in scenarios where these things come into play.

I like to bring this up because it shows how muddled opinions are but as Gruber pointed out, “Reminders doesn’t have and doesn’t need styled text.” This is why the Reminders app does not support Markdown. So Reminders are out and YAML properties are out (although mainstream apps today, like Obsidian, do support it).

But just before this Gruber says “Notes supports actually WYSIWYG formatting, as it should” which is where things get unclear. Apple Notes is a propreitary format and a propreitary format supporting markdown makes little sense because you cannot take your data out anyway so the markdown is extra burden. But if you want to take plain text notes—as so many of us in academia prefer to do in the interest of platform-agnosticism and reliable data handling in the future—markdown is the way to go even for note-taking.

Objection 4: Writing only, not note-taking or outlining

This is a fair point in my opinion but only subject to certain condition. I object to this generally, though, because it takes the original intent of markdown and makes it needlessly dogmatic. Gruber argues that he uses “Markdown for writing, not for todos, not for notes. Just for writing.”

This seems unusually opinionated rather than objective. Also, what is “writing” that distinguishes itself from “notes”? Jason Snell’s clarification in agreement paints a slightly clearer picture. Snell says “I don’t need style in notes.”. But then why does Gruber support WYSIWYG format in Apple Notes?

In short, I fail to see any clear, reasonable distinction between writing, outlining and note-taking that could make any difference whatsoever in someone’s choice of markdown as a method of writing plain-text but formatted content.

Objection 5: Markdown needs a parser (and it can befuddle parsers)

Markdown needs a parser when you think it needs one. By itself, markdown is still perfectly readable without a parser. Afterall, that was one of the core purposes of markdown as we clarified while laying our ground work. But if you do want a parser because you want to show off formatted text—as I myself am doing in this essay—then how different is it really from other similarly parsed formats you are not complaining about? Rich text is parsed and formatted, Microsoft Word or Apple Keynote all parse a user’s intents to format their text. Parsers exist all around us and nearly all programs we use employ parsers; it is not a drawback of markdown that it needs a parser, rather a benefit of markdown that it works just fine without one.

Russell points out an interesting use case where markdown syntax can supposedly confuse a parser. He offers as example the following: ### **this is _test_** but I fail to see what is so complicated about it. This is an H3-level heading with bold text which contains a piece of italicised text within it. The real question to me is why anyone would want to make text both bold and italic.

Objection 6: We should not be using ASCII to write documents

Really? If anything that is exactly what we should be using for our most important work, not relying on propreitary software (even richtext is propreitary). As I said when laying my ground work, softwares, workflows and formats will come and go, but your content needs to remain valid, accessible and portable so you can plug-and-play with whatever new toy comes up in the future.

If you want platform agnosticism, you need ASCII. And with markdown, you celebrate the freedom ASCII keeping in mind that it is in fact ASCII at the end of the day and not rich text. The moment markdown syntax is hidden the point of markdown is lost and people start comparing it to rich text and more complex but vendor-locked apps and lose the forest for the trees. Far from wondering why we should use ASCII for things whose end products is text, the debate should be about why all apps do not run primarily as a layer atop ASCII.

As Gruber says in praise of the app Things, “It doesn’t hide the Markdown formatting characters, it just styles them … That’s the right way to do Markdown.” This is remarkably similar to another app he praised, and one that I use a lot myself, iA Writer, which also retains the markdown syntax in text rather than hiding it: “iA Writer is just beautiful. To me it’s the gold standard for Markdown syntax styling”. Gruber further clarifies the difference between markdown syntax and WYSIWYG format in a commentary on Jason Snell’s review of markdown apps: “the whole point of [markdown] is to provide a syntax where the most common HTML tags for prose can be replaced by simple punctuation characters that are meant to be visible to the writer. I want to see the characters so I know I’ll get exactly the HTML output I think I’m going to get … If you want WYSIWYG, do WYSIWYG. If you want Markdown, show the Markdown. Trust me, it’s meant to be shown.” The app Gruber himself supposedly uses, BBEdit, also shows all markdown syntax.

Objection 7: There is no standardisation

I have nothing to say about this objection except that I fully support it. I differentiate specification from standardisation in the following manner: specification, like something W3C would do, would give us written standardisation for markdown as a “language” universally. Standardisation simply means apps interpreting markdown to the same capacity based on unwritten rules.

Markdown has come long enough that we need some standardisation even if specifications are a long way off. I have come across multiple flavours of markdown—with whose names I am thoroughly unfamiliar—where the same syntax does something different. Of course this is not as bad as it sounds: the differences go only so far as to say one app might use *italics* and **bold** while another uses _italics_ and *bold* but never has an _italic_ turned into a code block or something worse. Still, standardisation would be great. Can all apps agree that single markers mean italics and double markers mean bold? Or that footnotes are a thing and that all apps should support it?

Without standardisation the portability of markdown comes into question. Are all my files with _italics_ compatible with that other app I have never used that wants *italics* in my files? Many apps do support multiple versions of italicising and emboldening, but I often find it hard to keep track of what I myself used. My go-to syntax is underscores for italics and asterisks for bold, but I am now considering switching to single (underscore or asterisk) for italics and double (underscore or asterisk) for bold. With standardisation I would not have had to do that. Luckily, markdown is designed not to look jarring and to remain readable even when not “interpreted” as rich text. Now imagine non-standard HTML “flavours” that browsers decide for themselves—what fresh hell that would be.

In this context, what I am against are rants like Joe Armstrong’s that declare that markdown is bad because they had problems when Github changed the “flavour” of markdown they want their users to employ. The real complaint should have been that markdown itself needs a standardisation so Github would just have to learn to live with it.

Example I decided to look at a recent post on Daring Fireball to see what “standard” Gruber follows and, interestingly enough, I found him using three different syntaxes to specify links. Look into the source markdown for that link and you will find—

1. the use of [foo] followed by [foo]: link
2. the use of [foo][bar] followed by [bar]: link and
3. the more common approach of [foo](bar)

All three forms in the same document with seemingly no discernable motivation for choosing each of these methods. Just for fun, I tried the same with links on this essay (I normally only ever use method 3) and… all of them worked just fine. Now I have a new dilemma to add to my original one: what italics syntax do I prefer, and what link syntax do I prefer? One clear advantage with method 2 is that I can reuse links multiple times. Look into Gruber’s markdown for more insights.

Objection 8: Two carriage returns for a paragraph

This is a good one. Way back in the days of typewriters (yes, I have used and own them) you could do a carriage return, then tab spaces to the right, and start a new paragraph with an indent to mark that. With the advent of computers, that changed to a space between paragraphs. Innocently enough that meant you could keep all your paragraph spaces to zero and leave a blank line every time. To me this is ideal. But there are two views against this, only one with which I sympathise.

To some—especially those used to the word processor ways—a carriage return should also add a paragraph space. Like so many other examples in word processing, this is an odd mixture of typesetting and typing that word processors have forced upon us as a nasty habit. Nowhere else—not in a plaintext editor, not in a notebook with pen and paper, nowhere really—does a carriage return add a paragraph space. This is a view I do not sympathise with. You want a space between paragraphs, add a line space. And in plaintext especially, this makes even more sense.

The other view has some merit: the normal way of doing plain text, before markdown, was that a cariage return would be maintained. This is even called \r for that reason in RegEx and C programming on a Mac (Unix uses \n and in typical fashion Windows decided to use \n\r instead). This guarantees you a new line. On markdown this promise is broken: not leaving a line space merges two “new” lines into one. But when you think about it, markdown is neither the only nor the first syntax to take this approach. Programming languages used a semi-colon to specify the line end which allowed you to type one programming line on multiple visual lines. Markdown does the same just with a line space serving the role of the popular semi-colon because a semi-colon means something in normal writing, which is what markdown is all about.

Tip If you really want a single-line paragraph break, end all your lines with a <br/> and it will work as you desire for little extra effort.

Objection 9: Markdown is for developers; or markdown does not belong in a “regular” note-taking app

I fundamentally disagree with the assumption that markdown is for developers. It is simple enough that anyone can pick it up over a cup of tea. I do somewhat agree that the average computer user has gotten comfortable with rich text formatting as the definition of a “regular” app with formatting. These people likely do not need markdown. And in 25 years when these people realise they have lost access to an app, been locked in by a vendor or something along those lines, I hope there will be an app that exports their content for them. And then there are other apps where this is not even a concern—like Apple Reminders as Gruber helpfully points out. My reminders are fine without formatting and if I lose them, I am still alright for the most part even manually copying them over to another app.

What I am interested in, though, and what I use markdown for, is permanent content. My academic notes, my research, my reading, all of these have to last at least for my lifetime if not longer. This means they cannot be vendor locked or reliant on specific apps. But also I might need formatting in these notes. This unique combination of needing plaintext as well as formatting means, short of typing full-blown HTML tags, my best bet is markdown. I can easily export it, I can quickly preview it and continue to use previews if I need to, or I can read the markdown itself same as sensible plaintext. And it will last. For this, you do not need to be a developer and a “regular” note-taking app is probably going to work against you unless it is a fully “rich” WYSIWYG app that nevertheless stores all its content in markdown so you can take your content out anytime and walk away. Now that would turly be the best of both worlds.

Objection 10: “I cannot do X with markdown” or “I need a compiler without which markdown is useless”

This is more a class of objections than a single objection and I came across several such objections. In every case, without exception, I found that the fundamental problem with claims that markdown cannot do something lay in a misunderstanding of what markdown was intended for. Like a lawnmower that does not paint your fence, markdown does not read text aloud, optimise your images, play embedded videw etc. And yet markdown persists simply because it is built atop the single truth of all digital media and analogue communication: plain text.

The other class of arguments, that markdown files are useless because for every device on which I have markdown files I need a compiler to turn it into rich text is silly because it works on the assumption that richtext is some sort of standardisation. This is how word processors have spoilt us and led us into a world of disarray, vendor lock in, and utter mess across different versions of a single app (I have just two words here: Microsoft Word). The truth is that behind the deceptively simple ⌘ B or ⌘ I lies a whole lot of propreitary code that keeps you beholden to an app. Sure, if you are writing for something that becomes redundant six months or a year from now and do not need your work to last beyond that, or if you are adding to your grocery list for next week, you will be fine with most of these apps; and for such apps, use rich text by all means.

But if you want simplicity, a light-weight file set, platform-agnosticism, your content itself rather than a typeset format, and you intend your writing to ultimately turn into some sort of human-readable format in another context, and you want to keep that for years and years, do not underestimate how quickly technology will change and turn your context uninterpretable. At least with markdown your text will still be readable and “convertable” the same way that plaintext is without any proprietary code.

There are some objections I did not feel worth addressing, like Alex Chen’s rant that “there are almost NO [sic] info on resizing that image after the link has been added” using markdown, which misses the point of markdown entirely. (Can you please add a gif halfway through your podcast? No? Is that not a sensible request?) The same is true of subjective opinion rather than objective criticism, like the good Mr Chen claiming markdown has “weird syntaxes … which just makes it look stupid and not user friendly”.

If you get the point of markdown you will find places to use it. If you have not found it then things are bound to look weird because they lack a necessity-driven context. Markdown is a good solution to a genuine problem and like all good solutions it has room to improve, but it is by far the best of its kind today and we will all do well to pick it up sooner or later. As an added benefit it also reminds us of the difference between what we write and what we typeset; between content and design—a dangerous line word processors brazenly cross all the time.