Markdown (.MD) is a text format that lazy people use to write HTML. Unfortunately once those same lazies are used to the format, their eyes glaze over and they start to believe .MD is the solution for all the world’s problems. They share a lot in common with githubbies who think github is the solution for book production, open source, bad democracies etc..
.MD files are common in the geek world. Programmers love them. The design of .MD is simple and efficient. If you know the syntax, you can write basic text documents with headers and bullet lists, blockquotes, bold & emphasis etc. pretty quick. That makes it a handy tool for the elite of text workers – programmers – to develop simple text documents, quickly. So it’s a popular format for writing, for example, human-readable README files that tell you a little bit about the software you are about to install. However, that is where the use case ends. .MD is not a useful format for many other cases unless you want to prove to the programmers that you too can do tricky stuff in plain text. For the rest of us, it has little value.
Markdown was originally developed by John Gruber in 2004 and you can read about some of the reasons why he developed it here. The original purpose of .MD is that it can be read without converting it to another format like HTML. Presumably, John Gruber wanted a format that could be read easily by the eye, allowing the user to be able to quickly understand which part of a text is a heading, which part is a list, which part is a paragraph etc .MD is designed not to be rendered for display, it is meant to be the display.
For example, a list written in .MD would look something like this:
* item 1
* item 2
* item 3
That actually looks like a list. In HTML we would do something similar and it would look like this:
- item 1
- item 2
- item 3
An asterisk looks like a bullet, so there is little cognisant drag here. Pretty readable.
However, things start to fall apart pretty fast. Can we really parse at speed, for example, nested bold and emphasis in .MD like this:
The quick *brown fox* **jumps** *over* the lazy **dog**
Is that or the following easier to read?
The quick brown fox jumps over the lazy dog
I’m going to say the second is easier to read. Way easier to read. So, that is just the start of the problems; from here on in it goes downhill pretty quick for use cases beyond simple READMEs.
MarkDown isn’t designed for creating HTML
So, let’s assume we can agree Markdown is readable in a very limited number of scenarios – and move on to rationalise (grasp at straws) other needs for the format. That is pretty much where we are today, with the big selling point being that Markdown is an easy way to create HTML. But let’s face it, even programmers don’t like reading raw Markdown and even in the most popular .MD repository of them all – github – the Markdown files are rendered in the browser as nicely formatted HTML. Great! A use case we can stand behind – use Markdown to create HTML.
However .MD is really a pretty bad way to create HTML. Firstly, you need something to convert the .MD into HTML. So if you use just a plain text editor to create .MD files and load it into the browser you will see just plain, boring Markdown. No nicely formatted documents for you. There are tools that programmers like, and so the rest of us are also expected to like them, for converting .MD to .html. After all, according to the technically gifted, converting a .MD file to HTML is “really really easy.”
One of the most common tools for doing this is Pandoc. Pandoc is a great software and extremely useful. However having to install and learn how to run Pandoc – a complex tool at best – to convert a text file to something readable – sounds a little like the long way home. And that’s not where the rot ends, far from it, the rot has only just set in and the worst is to come. If everyone was to use Pandoc to convert .MD to HTML we would have consistent conversion results. Unfortunately, that’s not what happens. Each to their own, and we have a lot of different tools with which to do these conversions, and hence we have different results created from the same source. Ugh. That is a file format nightmare right there.
And let’s say you want to add a little colour to your text. Perhaps a highlight? Forget about it. Markdown lacks the tools to enable you to do it. Pandoc might help, however – let’s add some colour highlights to a code block with this easy to remember command from the Pandoc manual:
pandoc code.text -s --highlight-style pygments -o example18a.html
So, first of all, do you know what a command is? Do you know what a terminal is? Happy using one? Oh..that’s actually not ok for you? No problems, there are plenty of online introductory courses on the command line. So before you write that funding document, “about” page on your website or scholarly research document – just whip through a quick course on the command line and you’ll be all set! (don’t forget to read the sections about installing software from the command line, you’ll need it to get Pandoc working).
Problems with conversion tools aside – Markdown struggles to find a nice way to represent HTML. It’s just a bad fit. Use Markdown for creating HTML and you will find all sorts of little formatting gotchas that will cause you frustration. It is why many markdown environments/conversion tools also support HTML tags.
All HTML is valid Markdown. If you’re stuck, not able to format your content as you would like (for example using tables), you can always use plain HTML instead of Markdown. http://support.ghost.org/markdown-guide/
So if you want to really write HTML with Markdown you have to, well, write HTML. Klaro.
Markdown was never intended for writing HTML. It wasn’t designed that way and for good reason – it doesn’t do it well.
Codified text
As mentioned above, by design, the original markdown has a very small subset of elements that can be converted to HTML. As John Gruber says in his philosophy:
Markdown is not a replacement for HTML, or even close to it…The idea for Markdown is to make it easy to read, write, and edit prose.
So, Markdown is not actually designed to be a good format for creating HTML. And it lives up to its design. It is for this reason that some Markdown formats ‘extend’ Markdown to include HTML code, and there are also other forks of Markdown that do some really weird stuff that I can hardly explain. For example, Ghost Markdown, the version of Markdown used for the (Open Source) Ghost blogging platform, tries to wrangle image formatting into Markdown. To place an image you have to write the following:
![]()
Intuitive, right? Nope.
The above is really a leap from ‘readable’ to ‘codified’. It is codified text and in order to be able to work with it, you need to know how to de-code the text… I’m sorry, but I just don’t get it. Markdown adds another level of codified complexity which I then need to de-code first (according to non-standardised, and not-standard rules written in some help file somewhere if I’m lucky), so that I can then sally forth and read the content? No thanks.
Say no to codified text.
Non-standardised formats suck
Efforts to take Markdown and extend it to meet a wider variety of formatting needs are actually where the big trouble starts. Markdown has gone off in a hundred-and-one different directions, each with its own syntax.
That means, if I want to write a Ghost blog (I love Ghost by the way, no disrespect to them) in Markdown (their required format) then it is not enough to learn Markdown. I must learn Ghost markdown …their particular reading of what a good markdown format is… So, that leads us to one of the really big problems. Markdown is not standardised.
Can any of us think of another non-standardised text format and where that leads us? Does MS Word and ‘world of pain’ ring any bells? Yes, Markdown is non-standardised and that is a very big no-no. It is, in fact, quite shocking that programmers, big on standards, do not quite see that by advocating Markdown they advocate dropping some central best practices. Can’t say anything more about that really.
But Markdown is structured!
I often hear the term “structured text” when referring to Markdown. For example, the opening lines from the CommonMark pre-amble.:
Markdown is a plain text format for writing structured documents
Sounds good doesn’t it? Sounds very techy and convincing. But what is structured text? Structured text means basically that we can see if something is a heading or something is a bulleted list, or something is a paragraph. Huh? But that describes just about any text document. Structured text is the basic requirement of any text you create – without it, you just have a flat plain-text document with no headings, no bullet lists etc. So… we might as well start every sentence about documents designed to be read as being ‘structured’. I think tomorrow I will go and buy a structured book. Or perhaps I will write a structured narrative on my text-structuring word processor. Excuse me word processor sales person, do you have structured text word processors? Ugh. Meaningless.
What is left?
Markdown is good for limited use cases. Use it for README files on github.
If you have a good dose of Markdown cool aid then don’t let me bring you down from your sugar high. Markdown away. However, if you have heard that there is this cool format available and it cures all your textual needs and it is just really really easy to use and really really quick… then think about the elixir you are being offered and re-read this document before slurping away…
Some comments on this article on Hacker News here:
https://news.ycombinator.com/item?id=8403783
Thank you for this. Designing a web page is more than “structured text.” I thought I was missing something when every flat file CMS trumpeted writing in Markdown. So what?
It’s like trying to tie shoelaces wearing boxing gloves and telling people it’s a FEATURE!
hey Chris,
Totally agree. Also the term ‘structured text’ is very loosey goosey and it is used by markdown advocates to suggest more than what .md is actually capable of.
Markdown does, in my view, have a very useful function not a million miles away from John Gruber’s original intention. However, if the css has not been used properly then the opportunities offered by markdown are pretty limited and uninspiring.
Where a nicely designed appearance has been pre-set, or where the user can control those settings, then Markdown is a great means of writing content where the writer can focus on the content and not think about the coding.
This is especially true when building responsive design web sites.
Stephen Hay describes his approach to designing responsive sites in his book “Responsive Design Workflow, building on Ethan Marcotte’s original ideas.
We have built on Stephen’s approach and created what we call Micro-responsive web design, the key characteristic of which is the use of in-line css and zero external style sheets. This has the advantage of being very fast.
So our approach is for the user to write their input in Markdown, to set the appearance of the page using any of about 100 css parameters, if that hasn’t previously been done, and then for the software to dynamically create the page of html inc the inline css. This takes only a few hundredths of a second and it only adds to the page the active css, so all the available css which is not being used, i.e. it doesn’t have a parameter, is not used in constructing the page. We then compress the page by removing all comments, white space and line ends. Pandocs, which I had used originally, does a vaguely similar thing only very much slower and without anything like the control.
So, having tried using Pandocs and Dexy we wrote our own system which aims to give the user a much easier method of working.
I am happy to explain more about our method to anyone who asks me, it is available as a free tool.
Cheers, Nick
I checked out Day One for business note taking and assumed it’s markdown would be fine. Turns out there are enough glitches in either markdown itself or their implementation that it’s not useful for me. Combining checkboxes with indentation and bullets is a real problem, for example. I gave up.
Thank you for posting this! I totally agree that Markdown should be used just for Read Me files and not much else beyond that.
Why even use markdown for readme files? I can create a structured readme using a basic .txt file. I just don’t get the point of markdown.
You’re missing the point:
Reading
The quick *brown fox* **jumps** *over* the lazy **dog**is harder than reading
The quick brown fox jumps over the lazy dog
but it’s the same as, if not easier than, reading
The quick <i>brown fox</i> <b>jumps</b> <i>over</i> the lazy <b>dog</b>which is what Markdown is trying to achieve.
Another interesting point that hasn’t been discussed is the speed and ease of writing; I’ve been mostly writing code documentation and articles on web development. Basically a lot of text, code, links and a few images here and there. And I think that Markdown is perfect for that purpose.
The biggest pros for me are:
List are nice
Every paragraph is automatically wrapped in <p>
I can keep my usual code indentation without worrying about extra whitespace at the start & end of <pre><code> blocks
Inline
`code blocks`read better than<code>code blocks</code>I do agree that if falls apart for more complex document structures, but I don’t think Markdown wants to nor should try to do complex documents; that’s what HTML is for. As for simple documents, I think Markdown is king albeit not perfect.
Thanks for making this point so I didn’t have to. The author is comparing apples to oranges here.
Another relevant comparison: reading history and diffs in your favourite git UI; vs. trying to understand a document’s history armed with only Word’s track changes.
I actually find the HTML version easier to read than the Markdown version for the simple fact that its tags exhibit more visual variation than successive asterisks.
This seems to me like a painting with a very broad brush to justify – what exactly? Using HTML for text entry? Would that be better? Or using a WYSIWYG editor?
Markdown solves a very basic problem, which is how to create simple text input that has a few minor markup features in an easy way using nothing more than plain text.
Are there problems with compatibility and adoption? Sure. Do you need proper styling and perhaps some sort of plug-in to syntax coloring, yes. But really that isn’t a Markdown shortcoming that’s HTML. Do it any other way to generate HTML and you have those same issues.
Markdown solves a very specific problem and it’s power comes from having been widely adopted!
Could it be better? No doubt it could be. Standardization would help, and a few additional feature extensions that allow for a little more control over styling would be nice. But the last thing you want is for this to become a complex standard that addresses too many needs and in the process gets too complex.
For now, it’s relatively easy and has wide adoption. I think it’s easy to underestimate what it takes to get this kind of reach if you had to start over with something else.
I have used Markdown to write technical documentation that is published in HTML. Not my choice — the site designers picked it without asking the technical writer. So I learned Markdown. My opinion is that it’s like writing with one hand tied behind your back–yes, it can be done, but it’s very limiting.
I agree with the author of this article that once you get past headings and lists, Markdown is not intuitive, and the markup gives no inherent clues to the meaning. There is no obvious association between the punctuation used and the formatting produced, so it all has to be learned by rote. In contrast (and I know I’m in the minority here), I think that <b> and <i> and <code> provide solid clues as to what formatting will likely be applied.
Beyond that, <b> and <i> haven’t been recommended for years because they are formatting tags instead of structural tags. It’s much preferred to use structured markup, which would be <strong> and <em>. I haven’t yet encountered any Markdown tools or discussions that advocate real structured documentation principles.
Lastly, I think any syntax or tool that considers white space to be significant is off to a bad start, because the output is affected by something that can’t be seen. What is the Markdown markup (yes, that sounds funny) for a new line (not a new paragraph)? It’s two spaces at the end of the line. If you’re using a basic text editor, you won’t see spaces at the end of lines, so you can’t see the markup. There are other examples, too, but that one is probably the dumbest bit of Markdown that comes to mind.
Markdown wasn’t created for writers; it was created for non-writers. Is Markdown useful for readme files? Yes, Can it be used for other, more elaborate writing? Yes, but there are probably better tools.
That’s pretty musch the same situation I’m in now. We had XML to write technical documentation and now we are forced to use Markdown wich doesn’t do the trick to us.
Let aside all the trouble it creates with tranlation memory.
I allways wondered why we don’t use html right away. The reason why we are forced to use Makrdown: Programmers find it more hard do read/write XML. Okay everyone could learn to use HTML. Especially programmers. I don’t get it.
The most important thing to note is that this is not for “coders.” It is for writers! With the creation of the web writers have had to completely change platforms and in turn, learn how to build content on the web. It is not for the “lazy,” but to make reading content easier so writers can get back to writing. I really enjoyed reading the comments from technical writers who use Markdown. Thanks!
coders, technical writers…it doesnt matter, call it ‘the technically inclined’ 😉
You can try WP Githuber MD – An all in one WordPress Markdown Plugin . It is free.
Not only support syntax highlighting but only support other poupular libraries such as Mermaid, Flow Chart, Katex.. and so on..
Source code: https://github.com/terrylinooo/githuber-md
Download from WordPress:https://wordpress.org/plugins/wp-githuber-md/
While I agree with everything you’ve said vis à vis Markdown, I would go farther than that: I don’t think that Markdown is useful even for README files on sites like GitHub.
One of the problems with the proliferation of Markdown for basic documentation is that software fetched from GitHub requires the use of 1: a program to convert the Markdown README file to HTML, and 2: a web browser to comfortably read the converted result. This is brain-damaged.
Are plain text files no longer good enough for READMEs? Is there too little going on within the document for the sugar-addled to grok?
My advice to anyone considering Markdown for any reason at all, including its originally intended use: please use a saner format.
Just stumbled across this and totally agree. I’d also add that the problem with markdown is that it’s extremely difficult to process programatically (with code). In fact, I’d take things a step further and insist that doc be written in XHTML which opens up a world of possibilities using XSLT or other XML processing code to provide extensibility, validation, transformation, etc..
The one killer feature of markdown IMO is the use of accent grave `foo` to demarcate keywords and/or code, an extremely common pattern that truly is annoying in HTML: foo or
foo. But even here markdown falls down because the convenience encourages everyone to ignore the difference between var and code (labels vs. examples), a significant semantic difference IMO and, when not styled differently, produces less than clear doc.Markdown enthusiasts would say “So what” people can figure it out,” which is true but exposes the ideology behind markdown which is to make life easier for the documenter rather than the person reading the documentation.
I spent a very long time composing a “beautiful” markdown document, always checking after a few changes that the document continued to render correctly.
**BAM!**
The same document that looked so good in my browser as file:///home/me/my-markdown-doc.md suddenly looked terrible when rendered as https://mydomain.com/myrepo/my-markdown-doc.md
I feel that I wasted my time.
What’s wrong with markdown?
What isn’t wrong with markdown?
I’ve used MANY forum text editors. Markdown is not for lazy users. Many forums have input controls that are designed for users who are simultaneously both lazy and ignorant, and while the quality of these varies it generally gets the job done.
Markdown does not ever get the job done. Even when you know exactly how to use the particular iteration of markdown used in your current text input field, it still locks you out of MANY possible and in fact very typical things you might want to say.
Markdown is for lazy WEB DESIGNERS to pretend they made a functional text input field, despite the fact that they could literally copy+paste a working one from any forum generator website. Apparently no matter how lazy a designer HTML is engineered for, the companies will always manage to hire a lazier designer.
I recently switched to a markdown note taking setup thinking it would be an improvement. And because icloud notes doesn’t work on Android ofcourse. Seeing the ease of use i also tried to switch copy/paste email templates i have and considered adding support for markdown to my website to i can write posts with it…
I searched and found some decent editors for Android, macOS and ipad, an online one in nextcloud and it all works together and have a neat setup… But every step of the way i am hindered by how limited markdown as a format really is.
Now 2 months of hassle later i switched the email template thing back to regular macOS notes and gave up on the wordpress posting idea too.
I still use basic markdown for some notes that need to sync to android from macos (via nextcloud) just to keep some text based stuff handy on all platforms but other than that i find markdown pretty much sucks and is insufficient for most of what i do… 🙄