Copying my thoughts from there which haven't changed:
>To which I say, are you really going to avoid using a good tool just because it makes you puke? Because looking at it makes your stomach churn? Because it offends every fiber of your being?"
Yes. A thousand times yes. Because the biggest advantage of Markdown is that it's easy to read, and its second-biggest advantage is that it's easy to write. How easy it is to parse doesn't matter. How easy it is to extend is largely irrelevant.
Markdown may or may not be the best tool for writing a book, but Markdown is the best tool for what it does - quickly writing formatted text in a way that is easy to read even for those who are not well versed in its syntax.
I don't want to write a book. If I did I'd use LaTeX before RST. I want something to take notes, make quick documentation and thread comments.
*****
My thoughts on strictly-defined XML-ish syntaxes are the same: they're harder for humans to read, write, and modify, which defeats the primary purpose and benefit of Markdown.
Very few people have to write a Markdown parser. Many orders of magnitude more have to read and write Markdown. Optimize for them even if it makes writing the parser painful.
"Better specified" doesn't mean better. A bunch of features doesn't mean better.
Markdown is popular because it is simple. I have never had to teach anyone Markdown. They look at the file and immediately see what's going on and can copy the style.
Occasionally someone may have to look up something like table syntax, but no one in my career or personal life has ever asked me to explain Markdown to them, which is rare for a technology that is so widely used.
This has not been my experience with other markup languages.
"Wrong" does not necessarily mean "against the standard". It means "against common usage and good team practice" in this context.
It's "allowed" to use raw pointers, malloc, and any number of things in C++ code. In general, if you do any of them in a modern codebase you're doing it wrong.
We want to encourage people to produce written output with minimal friction. Barriers to writing--and especially barriers to producing documentation--should be minimized. Writing well is difficult enough!
Markup is overhead. Complex markup is even more overhead. Markdown is the best compromise we know of today that provides just enough structure and typographic capability, while imposing very little cognitive load on the author.
Besides, if you need something more complicated these days, you can have your favorite AI agent do it.
It's also worth remembering that markdown tried very hard to encode conventions that were already used in Usenet, email, and other text media. A > to indicate a quote was widespread Usenet convention. Asterisks or underscores to indicate emphasis was also a common convention; both are legal because both were common. Double asterisk or double underscores to indicate really, really emphasizing something was also a common convention. So were asterisks to display a bulleted list, blank lines to separate paragraphs, and indenting 4+ spaces to write code.
It's a good example of "pave the path" design philosophy, where you do what users are already doing rather than trying to impose some platonic ideal of what the world should be like. And it works quite well at that.
Stepped right on the rake though because it uses sigils which were common, but requires they be used in uncommon ways (by doubling etc) which it why most chat UIs don't actually use markdown
Your quotation and list syntax should work out of the box in most Markdown flavors (HN has a very non-standard and crippled version - basically nothing other than italics, paragraphs, and code/preformatting works.)
Strikethrough and bold are doubled to avoid common ambiguities. Your underline should technically work, but it comes out as an <em> (emphasis) tag, which is rendered as italics in most browsers.
I think it would be easier for me to appreciate your comment if you named some of these other languages. Markdown is the only standardized one I regularly come across that I type by hand, these days.
What are you contrasting to?
As for Markdown specifically- the only thing I regularly mix up is the syntax for links. I frequently reverse the [] and (). But that's just because I don't use it enough to have the muscle memory.
1&2 just pick one, it doesn’t matter. 3 mostly you’re the parser… if you’re after accuracy there are better versions, but it sure is simple to read and write
Mark down is great because it doesn't define a bunch of things. Headline? Its a headline, no font, no sizing, no colors... Just a headline. It means that it can be displayed on any device, printed on any paper, work with any accessibility tool and optimized for what ever requirements the reader has, not what ever the writer thought looked good. The web is full of great content being made hard to access because of poor/inflexible layout choices. Just give me the text and let me choose how to make it readable. The added fact that you can read raw markdown without even parsing it makes it even better. Not having total control over what its going to look like for the reader is a feature not a bug.
> Its a headline, no font, no sizing, no colors... Just a headline. It means that it can be displayed on any device, printed on any paper, work with any accessibility tool and optimized for what ever requirements the reader has, not what ever the writer thought looked good.
God, remember when that was that goal of HTML and the web?
Not many keystrokes to get a readable text. Yes, it has issues. But at its core, it is a plaintext with extra stuff, and no temptation to turn it into a webapp. (See my footnotes on HTML vs MD for saving text in https://p.migdal.pl/blog/2025/02/markdown-saves/).
Yes, there is a problem with "many ways to do the same thing". The solution is ease - use a linter or autoformatter. No more bikeshedding.
> Simplicity through Consistency: If you know how to do one thing in Typst, you should be able to transfer that knowledge to other things. If there are multiple ways to do the same thing, one of them should be at a different level of abstraction than the other. E.g. it's okay that = Introduction and #heading[Introduction] do the same thing because the former is just syntax sugar for the latter.
The "right element for the right meaning" crowd is always going to fall when they charge against the sheer walls of "but I like using Caution for my bulleted list" crowd. Or the "of course we put tire patches in the wiring element, it's when we use the tire patches".
Or a million other examples I've wrassled with over the literal decades.
Whatever sophisticated semantic scheme you move into the markup layer, is gonna get messed up. And then your fancy schema is just noise, very expensive noise. Markup layer needs to glue as closely to natural language constructs as possible, and then glue a little more closely than that, and let the bulk of the information derived come from natlang. It's boring, but it works, and it's easier than ever to get quantitative information out of natlang.
Keep the domain stuff out of the markup layer.
All that said, Asciidoc forever baby. Write actual books in it. Not really more complex than Markdown[1]. Beats up DITA, takes its lunch money. Win win win.
[1] Unless you go legit insane with `include` and `ifdef/ifndef/ifeval`
I don't think Markdown should be (ab)used as a programming language. It should be treated as a plaintext container that has some formatting to organize the contents.
That is a lot of complaining for having no suggested better alternative.
And there is your answer to the clickbait title -- we're still using markdown because there's no alternative that is so much better that it is going to dethrone the one that has all the momentum from being the first good-enough take on this that got any traction.
Everyone seems to forget Markdown was invented for humans and incidentally for machines.
Almost everyone who complains has some parser or rendering related agenda. No one cares if you can't nest asterisks inside underscores. Most of these edge cases don't read well as Markdown, which defeats the purpose.
>Everyone seems to forget Markdown was invented for humans and incidentally for machines.
We already had plain text for that. Markdown was invented to be converted to HTML. It has no utility over plain text otherwise. The link and image syntax is doing what HTML tags do, but are less readable for people than just pasting the URL. The relationship to the machine isn't incidental, it's intrinsic.
What was the Bjarne Stroustrup quote about two types of languages again? I certainly have gotten more mileage out of Markdown at this point in my long career as a programmer and web developer than I have out of hand-written HTML, XML, or other markup languages. The latter are good for automation and unambiguous representation needed for system building, but for the type of informal writing that is my bread and butter outside of coding, Markdown kills, and Obsidian is the killer app.
I strongly dislike flexible input like
__Unambiguous___, *Unambiguous*
I’m reminded of the time Microsoft allowed mistakes in html writing. They attempted to parse a wide variety of common user errors. The effect of this was no standard and nobody else able to write a Microsoft compatible parser.
I dislike Nim lang because of this. At least Nim defined the specification. Still though I think it creates more cognitive load learning every legal variation and it makes searching more difficult.
I think to authors point if Markdown actually had a strict simple definition with one day to do it and no embedded html we would be better off.
On one hand, yes, all true, it’s definitely a bit of a mess. On the other hand, what’s the alternative and don’t all languages with limitations ultimately get extended by various parties in non-compliant ways? Can anyone point to any alternative that has done it all correctly? Show me one language where someone says “This is all good and correct” and I’ll show you a language with 100 feature requests to extend it way further than its original authors intended and would create a similar mess if acted on. This is all to say, I’m going to coin Roberts’ Rule which says “All markup languages eventually end up as piles of poo with half a Turing-complete language bolted onto the side. Resistance is futile.”
Markdown is widely used but I agree that it's a mess, there are so many dialects..
A similar but better markup is ASCIIDOC; it's formally defined and comes with a Technology Compatiblity Kit (TCK) that can be used to certify the compliance of an implementation with the spec.
When you look at wisdom principles, like those of the Solomonic kind, you observe that a proverb is profoundly true, wise, and useful when you first hear it, but it starts to feel less so when you subject it to intense scrutiny/deconstruction, or try to extrapolate it to places where it's not supposed to go.
Markdown is like that.
We use it because it's an incredibly human way of writing and reading data without having to wade too deeply into the various forms of overhead that allow machines to read, process, and display it.
I don't read HTML all the time, and I don't expect it to be easy to read when outside of a browser.
Markdown though, that's my slightly fancy readme. It has just enough structure that I can easily read and understand it on the command line.
I can easily grep it without need for an advanced parsing engine.
If you need something with font and style weight then go for HTML.
But if I see README.html with a project, it's going to put me off wanting to contribute. I do not want to learn that project's style guide for how to add some new parameters to a table or remember that they want to specify italics in one of a dozen different ways.
I think markdown has problems, but this doesn't really propose a sane solution.
The need markdown solves is document formatting without needing to know or use a tag-based markup language and remaining easily human readable and editable.
That said, this is actually not the most widespread requirement. And when people need to solve this requirement, there often not tons of options. So some flavor of markdown is often the least problematic option.
The article talks about how confusing Markdown can get. I understand, but HTML is *much* more confusing when it comes to creating technical articles. These days we are going to see more and more markdown with the advent of AI. Markdown works really we with AI because it reduces the number of tokens required for the same amount of information vs HTML.
Yes fully agreed, markdown is going to win by far just because of tokens and AI. The only thing I think right now that should be advanced, is plugins/custom components for markdown, like .mdx, etc token efficient ways of visualizing things in various ways, or custom interactive components, etc.
Start with Obsidian (with "Live Preview" and "Editing Mode" as defaults) for fantastic WYSIWYG note-taking. Then layer in plugins like Outliner, Templater, Canvas, Relay... and realize Obsidian is almost like an OS for .md files -- which are portable, and easily human- and machine-readable.
I just can't find myself summoning the energy to be mad about markdown. It's good enough for like 99% of the things I use it for. Sometimes I get annoyed at specific extension support or whatever when I realize I shouldn't be using markdown for that task.
I think the author is missing the point. Markdown is easy for humans to read, write, and modify. Yes, parsers can be complicated. Few people need to write parsers, so that's ok, if unfortunate for those parser authors. Orders of magnitude more people need to read, write, and modify the documents themselves, and the fact that it's easy to do so is a huge strength.
HTML is terrible when you consider these properties. It's not easy to read, and is annoying to write and modify. Ditto for any other XML-based markup language, or even something like RST. LaTeX is right out.
Ultimately the author seems to suggest plain text should be what people use? That misses the point. Plain text is great for a lot of things, but if you're going to generate HTML (or something else) from it, you need something that at least has some structure. Markdown hits a nice sweet spot where it has enough structure such that you can reasonably generate rich-text document formats from it, but not so much that non-technical users can't work their heads around the format.
This website, at least in dark mode, doesn't have any visible indication when text is selected.
... Which is additionally frustrating, since the links at the bottom aren't actually links (so you have to select them to copy and paste into your address bar)
...and? What a weird article. Of course two different pieces source code can produce identical output. Every single mainstream languages are like that too.
Why are we using Markdown? Why do I use it every day?
It's easy to write. It's easy to read. Despite the OP's complaints, quality parsers exist.
pandoc can turn it into almost any format. We will still be writing markdown in 50 years, because the design bridges a bunch of compromises very nicely.
I actually do agree that HTML is a better one, if it is a bit easier to read the source...I want text, image and links in one place and HTML is indeed the easiest one.
BTW TempleOS terminal comes into mind. I really love the hyperlinks.
Why the heck would you use the phrase "Why the heck" in any circumstance other than to avoid censorship/avoid algorithmic penality on a social media platform?
I'm not using Markdown; I'm using plain text, along with a handful of well-understood formatting conventions which go back decades. "Markdown" is just a prettier means of displaying such text.
HTML is not a markup language anymore; it has become a lunatic application platform, and the last thing I want when trying to read some text is the intrusion of some lunatic's application.
Copying my thoughts from there which haven't changed:
>To which I say, are you really going to avoid using a good tool just because it makes you puke? Because looking at it makes your stomach churn? Because it offends every fiber of your being?"
Yes. A thousand times yes. Because the biggest advantage of Markdown is that it's easy to read, and its second-biggest advantage is that it's easy to write. How easy it is to parse doesn't matter. How easy it is to extend is largely irrelevant.
Markdown may or may not be the best tool for writing a book, but Markdown is the best tool for what it does - quickly writing formatted text in a way that is easy to read even for those who are not well versed in its syntax.
I don't want to write a book. If I did I'd use LaTeX before RST. I want something to take notes, make quick documentation and thread comments.
*****
My thoughts on strictly-defined XML-ish syntaxes are the same: they're harder for humans to read, write, and modify, which defeats the primary purpose and benefit of Markdown.
Very few people have to write a Markdown parser. Many orders of magnitude more have to read and write Markdown. Optimize for them even if it makes writing the parser painful.
Markdown is popular because it is simple. I have never had to teach anyone Markdown. They look at the file and immediately see what's going on and can copy the style.
Occasionally someone may have to look up something like table syntax, but no one in my career or personal life has ever asked me to explain Markdown to them, which is rare for a technology that is so widely used.
This has not been my experience with other markup languages.
It's "allowed" to use raw pointers, malloc, and any number of things in C++ code. In general, if you do any of them in a modern codebase you're doing it wrong.
We want to encourage people to produce written output with minimal friction. Barriers to writing--and especially barriers to producing documentation--should be minimized. Writing well is difficult enough!
Markup is overhead. Complex markup is even more overhead. Markdown is the best compromise we know of today that provides just enough structure and typographic capability, while imposing very little cognitive load on the author.
Besides, if you need something more complicated these days, you can have your favorite AI agent do it.
It's a good example of "pave the path" design philosophy, where you do what users are already doing rather than trying to impose some platonic ideal of what the world should be like. And it works quite well at that.
For those of you who weren't there:
I've been using these for almost half a century. They're much easier and more intuitive than Markdown. I see no compelling reason to change.Strikethrough and bold are doubled to avoid common ambiguities. Your underline should technically work, but it comes out as an <em> (emphasis) tag, which is rendered as italics in most browsers.
• I have to decide whether to use asterisks or underscores for bold and italic.
• I have to decide whether to use asterisks, hyphen-minuses, or plus signs for unordered lists.
• I have to remember all the various rules and edge cases about parsing.
I think it would be easier for me to appreciate your comment if you named some of these other languages. Markdown is the only standardized one I regularly come across that I type by hand, these days.
What are you contrasting to?
As for Markdown specifically- the only thing I regularly mix up is the syntax for links. I frequently reverse the [] and (). But that's just because I don't use it enough to have the muscle memory.
HTML? Also my markup language I created for myself, which is currently not published.
Html has that same problem. Think <b>, <strong>, <p style=“font-weight: 900;”>, etc.
That’s life. Get used to it.
God, remember when that was that goal of HTML and the web?
What a beautiful couple of years that was.
Yes, there is a problem with "many ways to do the same thing". The solution is ease - use a linter or autoformatter. No more bikeshedding.
If you plan to use a clean yet expandable syntax, look at Typst. One of its core design principles (https://github.com/typst/typst?tab=readme-ov-file#design-pri...) is:
> Simplicity through Consistency: If you know how to do one thing in Typst, you should be able to transfer that knowledge to other things. If there are multiple ways to do the same thing, one of them should be at a different level of abstraction than the other. E.g. it's okay that = Introduction and #heading[Introduction] do the same thing because the former is just syntax sugar for the latter.
Or a million other examples I've wrassled with over the literal decades.
Whatever sophisticated semantic scheme you move into the markup layer, is gonna get messed up. And then your fancy schema is just noise, very expensive noise. Markup layer needs to glue as closely to natural language constructs as possible, and then glue a little more closely than that, and let the bulk of the information derived come from natlang. It's boring, but it works, and it's easier than ever to get quantitative information out of natlang.
Keep the domain stuff out of the markup layer.
All that said, Asciidoc forever baby. Write actual books in it. Not really more complex than Markdown[1]. Beats up DITA, takes its lunch money. Win win win.
[1] Unless you go legit insane with `include` and `ifdef/ifndef/ifeval`
And there is your answer to the clickbait title -- we're still using markdown because there's no alternative that is so much better that it is going to dethrone the one that has all the momentum from being the first good-enough take on this that got any traction.
Almost everyone who complains has some parser or rendering related agenda. No one cares if you can't nest asterisks inside underscores. Most of these edge cases don't read well as Markdown, which defeats the purpose.
We already had plain text for that. Markdown was invented to be converted to HTML. It has no utility over plain text otherwise. The link and image syntax is doing what HTML tags do, but are less readable for people than just pasting the URL. The relationship to the machine isn't incidental, it's intrinsic.
Then, in the solution section, doesn't identify a solution.
No thank you, I'll stick with Markdown.
I’m reminded of the time Microsoft allowed mistakes in html writing. They attempted to parse a wide variety of common user errors. The effect of this was no standard and nobody else able to write a Microsoft compatible parser.
I dislike Nim lang because of this. At least Nim defined the specification. Still though I think it creates more cognitive load learning every legal variation and it makes searching more difficult.
I think to authors point if Markdown actually had a strict simple definition with one day to do it and no embedded html we would be better off.
All you need is Emacs! Nothing more!
A similar but better markup is ASCIIDOC; it's formally defined and comes with a Technology Compatiblity Kit (TCK) that can be used to certify the compliance of an implementation with the spec.
Markdown is like that.
We use it because it's an incredibly human way of writing and reading data without having to wade too deeply into the various forms of overhead that allow machines to read, process, and display it.
Markdown though, that's my slightly fancy readme. It has just enough structure that I can easily read and understand it on the command line.
I can easily grep it without need for an advanced parsing engine.
If you need something with font and style weight then go for HTML.
But if I see README.html with a project, it's going to put me off wanting to contribute. I do not want to learn that project's style guide for how to add some new parameters to a table or remember that they want to specify italics in one of a dozen different ways.
The need markdown solves is document formatting without needing to know or use a tag-based markup language and remaining easily human readable and editable.
That said, this is actually not the most widespread requirement. And when people need to solve this requirement, there often not tons of options. So some flavor of markdown is often the least problematic option.
Per keyboard stroke, you write much more content with MD than HTML.
Even without a specific browser/reader Markdown is relatively non-intrusive to read. You cant read HTML without an extra tool/effort to discard tags.
And you can parse MD with regular expressions, or can you? ;). (tip hat to infamous Stackoverflow discussion)
People forget how important good UX can be, sometimes.
We're using Markdown, YAML, and JSON bc they're easy to use; they're "highly memetic" (easy to learn, easy to teach, easy to spread)
They don't require many months to learn like XML, back in the day
- It's pretty easy for humans to read & write
- It's very easy for AI to read & write
- It's quite token-efficient relative to its expressiveness
- It can be used in many different contexts, so it's actually surprisingly good for interchange.
There are many formats that are better-suited for a given purpose, but Markdown remains a very attractive compromise for many applications.
HTML is terrible when you consider these properties. It's not easy to read, and is annoying to write and modify. Ditto for any other XML-based markup language, or even something like RST. LaTeX is right out.
Ultimately the author seems to suggest plain text should be what people use? That misses the point. Plain text is great for a lot of things, but if you're going to generate HTML (or something else) from it, you need something that at least has some structure. Markdown hits a nice sweet spot where it has enough structure such that you can reasonably generate rich-text document formats from it, but not so much that non-technical users can't work their heads around the format.
... Which is additionally frustrating, since the links at the bottom aren't actually links (so you have to select them to copy and paste into your address bar)
...and? What a weird article. Of course two different pieces source code can produce identical output. Every single mainstream languages are like that too.
Why are we using Markdown? Why do I use it every day?
It's easy to write. It's easy to read. Despite the OP's complaints, quality parsers exist.
pandoc can turn it into almost any format. We will still be writing markdown in 50 years, because the design bridges a bunch of compromises very nicely.
BTW TempleOS terminal comes into mind. I really love the hyperlinks.
Nobody uses markdown like that bro. We like markdown because it's easy to read both rendered and raw.
If you have a better idea, make it happen.
The author merely described the parameters of a solution and didn’t even attempt to solve it.
In essence, we aren’t even left certain that a better solution that satisfies all stakeholders is possible.
Check out my "Advent of Markdown" where I go through surprising markdown behavior: https://mastodon.social/@timokoesters/115643467322561173
HTML is not a markup language anymore; it has become a lunatic application platform, and the last thing I want when trying to read some text is the intrusion of some lunatic's application.