Aaron needs to hurry up and reincarnate already.

Because, like UNIX/Linux itself, worse is better: https://en.wikipedia.org/wiki/Worse_is_better - and perfect is the enemy of "good enough."

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.

  *bold*

  _underline_

  ~strikethrough~

  /italics/

  > Quotation

  - list
  - list
  - list

i use it because it does what i want and is easy to use.

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)

When I read articles like this my reaction is always “put up or shut up.”

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.

These examples are contrived af.

Nobody uses markdown like that bro. We like markdown because it's easy to read both rendered and raw.

Because I think it’s fair to say it’s becoming a standard format for ai agent specs docs etc. It’s not going away anytime soon.

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.

Ambiguous means unclear meaning, not that there is more than one way to achieve the same thing.

Html has that same problem. Think <b>, <strong>, <p style=“font-weight: 900;”>, etc.

That’s life. Get used to it.

You can say hell on your own blog.

Markdown has a lot of weird choices and works best for longer documents.

Check out my "Advent of Markdown" where I go through surprising markdown behavior: https://mastodon.social/@timokoesters/115643467322561173

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.

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.

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.

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.

> These 2 produce IDENTICAL output.

...and? What a weird article. Of course two different pieces source code can produce identical output. Every single mainstream languages are like that too.

Because Markdown is awesome, easier to write, and easier to read at the source level.

All problems are solved once you embrace org-mode.

All you need is Emacs! Nothing more!

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.

Somewhat related past discussion: https://news.ycombinator.com/item?id=41120254

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.

    <b>This</b> <i>is</i> *valid*
    <ul>
    <li>*Mark*</li>
    <li>_down_</li>
    </ul>

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 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.

Easy and "good enough" very often trumps complex and comprehensive. Markdown is great precisely because it can't do a lot of things.

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.

Markdown is essentially plain text with a couple extra features. I think Markdown’s basic appeal is that it’s plain text.

The article correctly identifies the upsides of Markdown, then identifies a bunch of issues that I, as a casual user of it, don't care about.

Then, in the solution section, doesn't identify a solution.

No thank you, I'll stick with Markdown.

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.

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.

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.

Hard, hard no on this.

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.

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`

Funniest part of this article is claiming * will produce a b tag then demonstrating it will usually produce a strong tag and not even noticing this.

Because there's only one reasonable implementation of AsciiDoc

Markdown lacks JavaScript and can be considered mostly harmless.

Why would anyone dislike markdown when it is so simple to use? My only gripe with markdown is that sometimes i forget how to include links.

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.”

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.

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.

The answer to the question in the headline:

- 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.

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 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.

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.

This sounds like all the arguments against using JSON/YAML as well.

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

Markdown is for us humans. HTML is for machines.

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)

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.