I like Markdown, and generally agree that it strikes a nice balance between correctness and usability...
...but it's delicious that this blog post also demonstrates an ambiguity in Markdown: how to handle intra-word emphasis. In the rendered output, "mark_up_" and "mark_down_" were probably intended to be "mark<em>up</em>" and "mark<em>down</em>", but the underscores were instead rendered literally.
I do appreciate that Markdown's solution to ambiguities like this is dead simple - just inline some HTML.
This is good and detailed, but misses a broader trend: how "worse is better" started to win - first Java over C++, then python and javascript over Java, and here markdown over Word and docbook.
When markdown emerged, docbook was getting even more elaborate, and vendors everywhere had for decades been locking people into frameworks and languages with fantastic features that were hard to use -- and then the internet bubble had popped. Then people realized they'd thrown away years building complex system, and had little tolerance for promises.
Markdown is something you can use in its native form. It's both source and destination, with a touch of future-proofing: if the opportunity arrives, you can polish it into anything, and mostly parse it yourself.
(What's surprising to me is that pandoc barely registers when compared with markdown on google trends since 2004; pandoc is the reason I switched completely to markdown in ~2010)
> that year’s largely uninspiring slate of U.S. presidential candidates like Wesley Clark, Gary Hart and, yes, Howard Dean helped propel blogs into mainstream awareness
Markdown was cool for a while. I have switched to typst and boy is that an improvement. It’s the love child of latex and markdown. With markdown you’d still have to embed latex, while typst has its own thing that is nicer than latex.
I enjoyed "a curmudgeonly guy with a kind heart who right this minute is probably rewatching a Kubrick film while cheering for an absolutely indefensible sports team".
What's preventing browsers from rendering a common subset of markdown without the need for browser extensions, with fallback to the current default of plaintext if parsing fails? LLM output can be copy-pasted for rendering by chat messengers and notetaking apps (e.g. DevonThink). If LLM markdown output continues to proliferate, does it become the defacto common-by-volume subset of Markdown, which browsers could standardize and render?
There is no such thing as a common subset of Markdown. Even basic things are rendered inconsistently by different implementations. If browsers decided to add Markdown support, this would lead to another “works only in Internet Explorer” situation.
Here's a fun trick: if you add .text to any URL on Markdown creator John Gruber's blog you'll get to see the hand-authored (bar the metadata and tags bits) Markdown he wrote for that entry.
I'm a big fan of markdown, it's easy enough to remember the basic syntax and your files are portable across hundreds of different editors. If one day I decide to switch away from Obsidian, I can just plug the same files into another good editor.
Markdown filled an obvious void: the need for something with more formatting capability than plain text, but editable and version-controllable as plain text, without the obnoxious verbosity and complexity of typical markup languages: i.e. more or less readable as plain text also.
I just hate that (1) you can't nest anything into a table (2) it's different everywhere.
Restructured Text is much more capable, and yet here we are, still using Markdown.
My markdown pages often also have HTML in them, I mainly use Markdown so if I decide some overlong thing I wrote on Reddit actually doesn't suck, I can copy-paste it into a webpage, and my web-server's .smd handler does the convertion. Lowest common denominator. :(
I was texting with John the other night while working on this piece, and reminiscing about my initial quibbles about the format, and I think I had been frustrated by just about everything on your list. I just need you to travel back in time to tell me to fuss more!
I think it's a littly funny he characterizes "Had the right flavor for every different context" as an advantage. It drives me crazy that Markdown is not the same everywhere and I'm still regularly getting confused about *bold* or **bold** or *italics*. (Curse you, Slack's weirdo version.)
I respect Anil's argument that the extensibility has helped it be adapted to different contexts, and in practice the looseness of it doesn't cause a problem. I do wish CommonMark had more traction (and acceptance and use of the name Markdown). It'd be nice to have a standard, at least for the basic stuff.
In the contexts where Markdown is most often used, the distinction between bold and italics isn't really important. So long as *this* or **this** gets rendered in a way that conveys emphasis, the meaning is preserved.
It took me a long time to see the variations as a plus and not a minus; as a veteran of the RSS-vs-Atom wars, I was long an advocate of Technical Correctness(tm) like any good coder. But the years since then have made me a lot more amenable to what I think of as a sort of Practical Postelism, which I guess is like applied worse-is-better, where we realize the reality is that we'll _always_ have forks and multiplicities, so we should see it as a feature instead of a bug. It's like accepting that hardware will fail, and building it into the system.
I mean, HTML itself is well specified in the streets, and infinitely different flavors in the sheets. I don't _like_ that, the part of me that writes code _hates_ that. But the part of me that wants systems to succeed just had to sort of respect it.
Single-asterisk for bold is not Markdown. I believe Slack calls their thing "markup". I also find it annoying. So annoying that I just learned Slack's keyboard shortcuts instead.
Sound write-up. It is missing the #1 reason I like it though - it's fundamentally text.
No format/vendor lock-in and very amenable to living in a git repo. For my note taking that's already game over right there against everything else. I don't want to worry about whatever cursed format OneNote uses is still something I can extract in 2035.
I also like that it's become a defacto standard that LLMs speak. I can tell it to look at the code in this server repo and make me a API_documentation.md and it'll grasp that I want a text based summary of how to use this endpoint
Same. I’m reading The UNIX Programming Environment (1984), and it’s made me want to use text for a lot more things. Proprietary formats come and go, but text is forever.
Not only that but Markdown use the conventions people already used in text files (point 3 in the article). People wrote Markdown before Markdown existed, they just formalized it.
In fact, I like to write notes and documentation in text form, and then I notice I have been using Markdown all along, so I rename my text file into .md, fix a couple of markers, and now it looks nice on a viewer that supports markdown, and I have syntax highlighting in my text editor.
Except there's a massive lack of Markdown VIEWERS. You find MD files in every open-source project and lots of other places, but almost no viewers that render them as intended. So you wind up looking at them as plain text, with a bunch of formatting characters in them. What's the point, then?
Only just now has Windows Notepad been revised to render Markdown (I think it does now, anyway). And after searching for a Mac one I finally bought Marked. But that's all I could find. Otherwise you have to load MD files in some kind of editor and "preview" them. NO! I just want to double-click on the file and READ it, with the formatting applied. Why is that so hard?
Eh, the things Markdown was made to compete with were also text. Including, you know, plain text. Sure, there were people out there doing README.RTF or README.DOC that annoyed us all -- nevermind those README.PDF monsters -- but just as frequently it was README.TXT or READ.ME (or README.DOC was in plain text). And GameFAQs and newsgroups got pretty far with plain text and ASCII graphics.
The problem is that people want to use a web browser to display their documents, they want rich documents, and web browsers are awful at displaying text they don't understand the structure for. And <code> tags look consistently awful when read back, which is why we so strongly prefer syntax highlighting when we read XML or HTML.
Really, the big competition was BBCode, whose main problem is that it's too much like HTML, and Wikitext, whose main problem was that it's too bare-bones and domain-specific. The big advantages of Markdown are:
1. It's simply more readable. It pulls from how people were naturally formatting plain-text documents meant to be read as plain text rather than pulling from markup languages, so it more closely matches how people want to write documents in plain text. That makes the document easy to read while you're writing it. Asterisks for highlighting is an old convention, so were dashes and asterisks for bullets. Really, it made the asterisk an English punctuation mark for emphasis, which I think it genuinely is now.
2. It was easy to parse and short, which made it popular with Web 2.0 social media. It got picked up by Slashdot, Reddit, and Stack Overflow as "good enough" and "better than BBCode" for user generated content. Nobody liked using WYSIWYG editor boxes then, either. They were slow, buggy, and were often Flash-based before HTML5. They needed plain text formatting options, and BBCode was both annoyingly unnatural to type (just like HTML tags) and a little inflexible.
And nobody wanted to repeat MySpace and just let users use HTML. That was a horrible idea (Samy, XSS, etc.).
I think that is the biggest reason why Markdown doesn't support table. There are alternatives that do (e.g. wikitext) but they didn't get as popular as Markdown. Why? Perhaps it's because that tables will never really look fine in pure text no matter how clever your syntax is.
I mean markdown existed, but before that there's like... whatever format phpbb and friends let you use for forum posts right? There was stuff that was text-y.
But perhaps it was the first big format that was followed a Unix-y "here's a CLI tool to go to HTML from this" thing, instead of some php script
> It is missing the #1 reason I like it though - it's fundamentally text.
Sure, but that's table stakes.
There are much better formats: AsciiDoc, reStructuredText, etc. Yet I also primarily use Markdown. I could use a format that's perhaps 20% better, and well-specified. But I'd have to use Markdown somewhere anyway. So I just stick with Markdown. It's good enough for me.
Markdown is fundamentally WYSIWYG - you edit something and you get it rendered 1 to 1. Either in plain text (a.k.a. "source") or when it converted to HTML/CSS and then presented.
WYSIWYG requires 1:1 mapping between "source" and "presentation". Markdown is exactly that. While HTML/CSS is 1:N mapping - same presentation can be achieved with many combinations of HTML/CSS rules. That's why "true WYSIWYG" is barely achievable with HTML/CSS.
But Dash does acknowledge this, only slightly obliquely and I think more usefully broad:
reason #3 Markdown succeeded: Built on behaviors that already existed. It succeeded because it came from the culture it was born in. Email formatting conventions. HTML. Plain text.
I love Markdown. I'm a bit surprised, though, that you still can't open a .md file by default in most web browsers. It seems like it should be quite trivial to have the browser automatically convert it to html and display it.
Yeah, also missing a built-in JS API for turning Markdown into safe HTML. Sure, there are lots of different implementations, but maybe start with something small at least.
This is a good call. I know it's been suggested multiple times over the years; I wonder what the rationale was for rejecting the format, or at least having the option to render a file when it's loaded. (Maybe a "display as HTML" button or the like would be required before it would be rendered.)
As I was griping above, you usually can't just view a Markdown file with formatting applied at all. I think MAYBE Notepad has been updated just recently to render it, but otherwise... you're looking at plain text with a bunch of formatting characters in it. Why? It's baffling. Where are the simple Markdown READERS?
You write your markdown file, but add the code snippet at the bottom of yor document and save it with a .md.html extension. Then when you double-click it it opens and renders in your browser.
I save my notes in a Google Drive, and it's now replaced all the note taking apps I've tried over the years
The author of CommonMark and Pandoc has a new format called Djot: https://djot.net/ that I've been meaning to check out. Supposedly more sane to parse, and it comes from someone who would definitely know about that sort of thing.
I'm fairly new to all this, but my understanding is that Markdown is great for a few reasons:
It's just plain text, so no vendor lock-in and you can ripgrep/fzf/grep through it
Lives happily in git repos with proper diffs
LLMs speak it natively - they output Markdown, they understand Markdown input
Way easier for agents to parse than PDFs (which are binary, layout-focused, tables turn to mush)
Can do tables (at least in GFM), headers, code blocks, links - all structure preserved
What it can't do (as far as I understand): complex layouts, precise typography, embedded binary content, anything that needs pixel-perfect rendering.
Am I missing anything? What are the other limitations I should know about?
There's something really interesting about the constraints given by plain text that you would lose with What You See Is What You Get (or, the ever-unfortunate acronym WYSIWYG) controls. I almost think what you get in that case is an unfortunate mindset-shift towards What You See Is All There Is (or, an incredibly dope acronym, WYSIATI).
This is a good article, although I wish it had talked a little more about the standardization (or rather, the lack thereof) in Markdown. I get why it didn't, it's trying to be positive about something that is an overwhelming net positive for the world, but I think a "warts-and-all" treatment of the history would be more honest.
I appreciate that Gruber brought this very helpful thing into the world, but OTOH he was such a prick about the whole Standard Markdown debate, for no real reason other than ego. And it resulted in Markdown remaining an ill-defined standard to this day, with occasional compatibility issues still cropping up even though most platforms support most of "Github-flavored Markdown" (itself a stupid name and indicative how badly this has gone).
> ...that it was too difficult or inconvenient to write out full HTML by hand
It's not necessarily that writing HTML or other markup flavors is harder (obviously it is), but the beauty of Markdown for me is that it's perfectly readable in its raw form as well as with an applied styling.
And speaking of customizing the 'look' of markdown, a shameless plug for a markdown editor I've been working on with extensive customization options: https://kraa.io/about
95 comments
[ 2.5 ms ] story [ 136 ms ] threadIYKYK. Joyent. TextDrive. Textpattern CMS.
Imagining an alternate universe where it might have been Textile. https://textile-lang.com/
Really it comes down to historically the time and place when Markdown was needed and the power of momentum leading to its mass adoption.
...but it's delicious that this blog post also demonstrates an ambiguity in Markdown: how to handle intra-word emphasis. In the rendered output, "mark_up_" and "mark_down_" were probably intended to be "mark<em>up</em>" and "mark<em>down</em>", but the underscores were instead rendered literally.
I do appreciate that Markdown's solution to ambiguities like this is dead simple - just inline some HTML.
When markdown emerged, docbook was getting even more elaborate, and vendors everywhere had for decades been locking people into frameworks and languages with fantastic features that were hard to use -- and then the internet bubble had popped. Then people realized they'd thrown away years building complex system, and had little tolerance for promises.
Markdown is something you can use in its native form. It's both source and destination, with a touch of future-proofing: if the opportunity arrives, you can polish it into anything, and mostly parse it yourself.
(What's surprising to me is that pandoc barely registers when compared with markdown on google trends since 2004; pandoc is the reason I switched completely to markdown in ~2010)
Gary Hart?
My favorite Markdown creation was "GistDeck", a bookmarklet that turned a GitHub Gist of Markdown content into a slide show.
So much easier to make and share than a PowerPoint deck.
https://github.com/nzoschke/gistdeck
Example: https://daringfireball.net/linked/2026/01/09/moylan.text
... and if you look closely at some of the entries you might spot custom Markdown features that aren't part of the published spec.
Chatgpt is pushing markdown to the maximum expose, Google & Microsoft sooner or later should react.
Restructured Text is much more capable, and yet here we are, still using Markdown.
My markdown pages often also have HTML in them, I mainly use Markdown so if I decide some overlong thing I wrote on Reddit actually doesn't suck, I can copy-paste it into a webpage, and my web-server's .smd handler does the convertion. Lowest common denominator. :(
I respect Anil's argument that the extensibility has helped it be adapted to different contexts, and in practice the looseness of it doesn't cause a problem. I do wish CommonMark had more traction (and acceptance and use of the name Markdown). It'd be nice to have a standard, at least for the basic stuff.
I mean, HTML itself is well specified in the streets, and infinitely different flavors in the sheets. I don't _like_ that, the part of me that writes code _hates_ that. But the part of me that wants systems to succeed just had to sort of respect it.
*bold*
/italics/
_underline_
No format/vendor lock-in and very amenable to living in a git repo. For my note taking that's already game over right there against everything else. I don't want to worry about whatever cursed format OneNote uses is still something I can extract in 2035.
I also like that it's become a defacto standard that LLMs speak. I can tell it to look at the code in this server repo and make me a API_documentation.md and it'll grasp that I want a text based summary of how to use this endpoint
In fact, I like to write notes and documentation in text form, and then I notice I have been using Markdown all along, so I rename my text file into .md, fix a couple of markers, and now it looks nice on a viewer that supports markdown, and I have syntax highlighting in my text editor.
Only just now has Windows Notepad been revised to render Markdown (I think it does now, anyway). And after searching for a Mac one I finally bought Marked. But that's all I could find. Otherwise you have to load MD files in some kind of editor and "preview" them. NO! I just want to double-click on the file and READ it, with the formatting applied. Why is that so hard?
The problem is that people want to use a web browser to display their documents, they want rich documents, and web browsers are awful at displaying text they don't understand the structure for. And <code> tags look consistently awful when read back, which is why we so strongly prefer syntax highlighting when we read XML or HTML.
Really, the big competition was BBCode, whose main problem is that it's too much like HTML, and Wikitext, whose main problem was that it's too bare-bones and domain-specific. The big advantages of Markdown are:
1. It's simply more readable. It pulls from how people were naturally formatting plain-text documents meant to be read as plain text rather than pulling from markup languages, so it more closely matches how people want to write documents in plain text. That makes the document easy to read while you're writing it. Asterisks for highlighting is an old convention, so were dashes and asterisks for bullets. Really, it made the asterisk an English punctuation mark for emphasis, which I think it genuinely is now.
2. It was easy to parse and short, which made it popular with Web 2.0 social media. It got picked up by Slashdot, Reddit, and Stack Overflow as "good enough" and "better than BBCode" for user generated content. Nobody liked using WYSIWYG editor boxes then, either. They were slow, buggy, and were often Flash-based before HTML5. They needed plain text formatting options, and BBCode was both annoyingly unnatural to type (just like HTML tags) and a little inflexible.
And nobody wanted to repeat MySpace and just let users use HTML. That was a horrible idea (Samy, XSS, etc.).
I think that is the biggest reason why Markdown doesn't support table. There are alternatives that do (e.g. wikitext) but they didn't get as popular as Markdown. Why? Perhaps it's because that tables will never really look fine in pure text no matter how clever your syntax is.
But perhaps it was the first big format that was followed a Unix-y "here's a CLI tool to go to HTML from this" thing, instead of some php script
Sure, but that's table stakes.
There are much better formats: AsciiDoc, reStructuredText, etc. Yet I also primarily use Markdown. I could use a format that's perhaps 20% better, and well-specified. But I'd have to use Markdown somewhere anyway. So I just stick with Markdown. It's good enough for me.
The question is more why Markdown is slowly but surely outcompeting them.
Markdown is fundamentally WYSIWYG - you edit something and you get it rendered 1 to 1. Either in plain text (a.k.a. "source") or when it converted to HTML/CSS and then presented.
WYSIWYG requires 1:1 mapping between "source" and "presentation". Markdown is exactly that. While HTML/CSS is 1:N mapping - same presentation can be achieved with many combinations of HTML/CSS rules. That's why "true WYSIWYG" is barely achievable with HTML/CSS.
Simple and Universal: A History of Plain Text, and Why It Matters
https://amontalenti.com/2016/06/11/simple-and-universal-a-hi...
You might enjoy it!
If you only use headlines and bulletpoints, I have a very pleasing result for a simple text file.
reason #3 Markdown succeeded: Built on behaviors that already existed. It succeeded because it came from the culture it was born in. Email formatting conventions. HTML. Plain text.
You write your markdown file, but add the code snippet at the bottom of yor document and save it with a .md.html extension. Then when you double-click it it opens and renders in your browser.
I save my notes in a Google Drive, and it's now replaced all the note taking apps I've tried over the years
[1] https://casual-effects.com/markdeep/
It's just plain text, so no vendor lock-in and you can ripgrep/fzf/grep through it Lives happily in git repos with proper diffs LLMs speak it natively - they output Markdown, they understand Markdown input Way easier for agents to parse than PDFs (which are binary, layout-focused, tables turn to mush) Can do tables (at least in GFM), headers, code blocks, links - all structure preserved
What it can't do (as far as I understand): complex layouts, precise typography, embedded binary content, anything that needs pixel-perfect rendering. Am I missing anything? What are the other limitations I should know about?
I appreciate that Gruber brought this very helpful thing into the world, but OTOH he was such a prick about the whole Standard Markdown debate, for no real reason other than ego. And it resulted in Markdown remaining an ill-defined standard to this day, with occasional compatibility issues still cropping up even though most platforms support most of "Github-flavored Markdown" (itself a stupid name and indicative how badly this has gone).
It's not necessarily that writing HTML or other markup flavors is harder (obviously it is), but the beauty of Markdown for me is that it's perfectly readable in its raw form as well as with an applied styling.
And speaking of customizing the 'look' of markdown, a shameless plug for a markdown editor I've been working on with extensive customization options: https://kraa.io/about