Just Use Email
How to use Email for Everything



Markdown is overkill and is actually killing productivity

Published on

John Gruber's famed Markdown is everywhere. If you are a developer, software engineer, or just a technically-inclined person, you may under the belief that saving your files in Markdown (.md) is a great benefit. Incidentally, not only will your file system balk if you use a .md extension (unless you also download some software designed to parse Markdown, or a good text editor that recognizes that extension, but they are nothing other than plain-text files but usually denoted as written in Markdown by the author changing the .txt extension (often used in Windows and Mac) to .md. Some authors will save them with dual extensions, i.e. myfile.md.txt as a result.

The idea of Markdown was seemingly two-fold. First, that people could not easily write markup, usually HTML, directly, and that other people could not easily read other types of markup "as is". Nothing could be further from the truth.

Somehow, we bought into that myth, but before I blame Gruber too much, he was just buying into a previous myth: that all text needs to take advantage of nearly the entire spectrum of HTML markup.

That likely came from the plethora of modern word processing, such as Microsoft Word.

The idea is that we, mere internet writers, or computer writers before that, must also use all the typographical and nifty methods that formal publishers use. Italics, bold, and underline were not enough; we had to use indented block quotes, subscript and superscript, tables, and of course, lists made with bullet points and numbers, known as unordered and ordered lists respectively.

If you've ever attempted to create a table in a plain-text file, you know the futility. Tabs are your friend, but only if you account for a maximum character length per row, which can be difficult once you get beyond a half-dozen rows.

The simple truth is that 99.97% of you are not publishers and your work is mostly seen by a few people. In fact, there's a decent chance that your own children will not bother to read your writing, no matter how thought-provoking or convincing it may be.

Do you know what the cure to bullet mania is? Press Return. A blank line is almost always superior to a bulleted list.

Visually, a bulleted list is cramped. Without altering the default styling, a bulleted list keeps list items to single-line spacing, indents, and therefore shortens line-length. It's not wrong, per se, but in almost all cases, formatted HTML lists are not helpful. A bulleted list should have a very short list of items, else scanning through them becomes painful. How often do you see bulleted lists in books? Almost never. In magazines and newspapers, they are usually used only in callout boxes, not in the flow of the article.

The point I'm attempting to make is that when you attempt to backwards format plain-text to a theoretically superior markup system (HTML), you are just rowing upstream.

Worse, you now have to make use of a separate parser to rip apart your Markdown and recreate the HTML it (likely) should have been all along. That might not seem so bad, but after Gruber's Markdown was released into the wild, a half-dozen variants of Markdown appeared, the most notable being "Github-flavored Markdown". Typical of engineers, they added the 'flavored' element, instead of just calling it Github Markdown.

Outside of the basic tags, once you delve into more complex formatting, you'll need to know the end result of where your Markdown will be parsed. In other words, unlike HTML, you can't expect to memorize the entire Markdown specification. Tens of thousands of blog posts cluttered up the internet to explain why one 'flavor' of Markdown is superior to the other, or why everyone should just go back to the true Markdown of ReStructured Text.

Oddly, few seem to doubt that Markdown is needed at all. I guess I'll be one of those few.

Gruber thought rather logically that writers of plain-text often will use an * to denote a bullet point at the start of a line, or a 1. to start a numeric list of items. Since those are human-readable, why not create a parsing engine that could take those and output HTML (and eventually other markup formats)?

Then, it breaks down. Ever seen a table in Markdown? Not much cleaner than HTML.

One of my favorite examples of the overkill of Markdown is the horizontal rule. From Gruber's original:

HORIZONTAL RULES

You can produce a horizontal rule tag (<hr />) by placing three or more hyphens, asterisks, or underscores on a line by themselves. If you wish, you may use spaces between the hyphens or asterisks. Each of the following lines will produce a horizontal rule:

* * *

***

*****

- - -

---------------------------------------

This was to avoid the use of typing <hr />?

This brings us to the second argument to use Markdown: that readers can't understand <hr /> and are left in the lurch. But they get the general idea that a series of asterisks or dashes connote some kind of document division, just as a <hr /> does.

But here is the big lie. When, as an author, do you ever send your written material in Markdown to others? If the vast majority of Markdown tools is any testament, you don't. You convert it first to... wait for it... HTML, or possibly PDF or some other "readable" format.

Which means you need another piece of software, known as a Markdown processor, to (hopefully and correctly) parse your Markdown into HTML where another piece of software, known as an HTML parser found commonly in web browsers and email client software, will parse it into the truly human-readable format that you were looking for all along.

So, the question remains: why not just write in HTML to begin with?

After all, no one is actually typing the <p> tag at the start of each paragraph. I certainly don't. I type directly in my text editor just as I would a word document, except I'm typing in an .html file, the actual source and final output of what will be delivered to the reader. There is no CI/CD process. I'm not creating unit tests, running a sandbox on a Kubernetes instance, using a Markdown parser, or any tools at all except a text editor. As I type, I might add some emphasis tags and some hyperlinks, but when I'm mostly done, I highlight all my text and go to my markup toolbar and in one-click all my paragraphs are surrounded by proper HTML paragraph tags.

What pains am I trying to avoid by avoiding HTML?

Have you seen the all the in-depth articles describing people's writing processes these days? (1, 2, 3, 4) We aren't going forward; we are going backward.

The concept of Markdown was that 'average' people can't be bothered to remember a zillion html codes and that 'average' people can't read text in .html files should they stumble upon them. The kind of code in web apps is unreadable, full of zany javascript and not much plain text. But an article like this? The source file is very readable. View the source of this page. A 14-year old could read it if they had to, but here's the kicker: they don't have to... because web browsers exist and HTML parsers are real.

Some will say there are 110 tags in HTML and it would be impossible for 'average' people to memorize them. But that's just hyperbole to get you to install more tools on your system and complicate your writing workflow. The vast majority of those tags are not used in writing.

For instance, the video tag (and all its attributes) generally has no place in writing and Markdown has no solution for it either. In fact, wherever Markdown fails to replicate an HTML formatting option, it advises you to use... you guessed it... HTML.

There are many other HTML tags one would likely never use in normal writing such as the html, head, header, nav, body, section, footer, aside, meta, link, base, style, title, article, and similar tags. You'd likely use them once in your HTML template, just as users of SSGs (Static Site Generators) and other publishing workflows do, and not pay too much attention to them again. But they are not hard to learn and would take only a few minutes to master.

Many other HTML tags are related to tables, building forms, bi-directional text, making article text machine-readable (such as <data> and <date>), or require knowledge of many attributes usable within various HTML tags.

But to write an article (and effectively stop using Markdown) you likely only need to master these 11 tags that I've conveniently put into a comma-delimited list with hyperlinks to their documentation so you don't have to see a bunch of blinding white space and be forced to scroll further through a useless bulleted list: a, blockquote, br, em, h1-h6, hr, li, ol, p, strong, and ul.

Here are 9 optional HTML tags to learn for slightly fancier publishing: cite, code, img, mark, s, small, sub, sup, and u.

That is virtually all the HTML you need to know to write without the crutch of Markdown. Your HTML knowledge is universal and applicable to many things. It will stand the test of time since it is based on internet standards, not individual flavors.

Ditch Markdown and start writing in HTML directly when you need to create a publishable document.