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.

• frizlab

  today at 7:30 PM

  There are other solutions which are as easy to read/write (if not more) and which are defined much better… Asciidoc comes to mind.

  • Arainach

    today at 7:45 PM

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

• vbezhenar

  today at 6:44 PM

  HTML is valid markdown. So I'm not sure how you make oppose markdown and XML. XML is basically a subset of markdown.

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

  Markdown basically adds a whole layer of complexity upon HTML.

  • Arainach

    today at 6:54 PM

    If you're writing things like that in Markdown files (without being escaped in code blocks as HTML syntax examples), you're doing it wrong.

    • smahs

      today at 7:06 PM

      Not wrong, perhaps a little weird. HTML is a first class citizen in the commonmark (spec)[https://spec.commonmark.org/0.31.2/#html-blocks].

      • Arainach

        today at 7:20 PM

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

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.

• nostrademons

  today at 6:35 PM

  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.

  • singpolyma3

    today at 6:41 PM

    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

  • reaperducer

    today at 6:40 PM

    markdown tried very hard to encode conventions that were already used in Usenet, email, and other text media

    For those of you who weren't there:

      *bold*
    
      _underline_
    
      ~strikethrough~
    
      /italics/
    
      > Quotation
    
      - list
      - list
      - list
    

    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.

    • nostrademons

      today at 7:26 PM

      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.

    • dingaling

      today at 7:29 PM

      But Usenet style didn't have a trendy name, an 'inventor' or Github stars. So it didn't exist.

• wisemanwillhear

  today at 6:21 PM

  The solution is sufficiently perfected with markdown. Just like new revolutionary technologies doesn't replace wheel technology.

• xigoi

  today at 6:31 PM

  For me, Markdown produces a lot of unnecessary cognitive load compared to other markup languages.

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

  • mh-

    today at 6:40 PM

    > compared to other markup languages

    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.

    • xigoi

      today at 6:50 PM

      > I think it would be easier for me to appreciate your comment if you named some of these other languages.

      HTML? Also my markup language I created for myself, which is currently not published.

      • mkldd

        today at 7:23 PM

        my girlfriend goes to another school

  • nxpnsv

    today at 6:38 PM

    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

  • chrisweekly

    today at 6:34 PM

    I suggest trying Obsidian for WYSIWYG markdown editing. It beats heck out of typing it raw and eliminates that cognitive load.

    • xigoi

      today at 6:52 PM

      I don’t like WYSIWYG editing, as it makes the formatting invisible.

• recursivedoubts

  today at 6:32 PM

  I came here to say this.

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.

• singpolyma3

  today at 6:55 PM

  Those three are not the same thing though. They might render the same visually with the most popular visual user agents, but that's about it

• IshKebab

  today at 6:26 PM

  <b> is now hilariously called the "bring attention to" element. I shit you not.

  • ceejayoz

    today at 6:38 PM

    That's the sort of "we started at the acronym and worked backwards" approach the Pentagon loves to do.

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.

• zimpenfish

  today at 6:41 PM

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

  What a beautiful couple of years that was.

  • singpolyma3

    today at 6:54 PM

    IMHO still is. Just don't add any JS or CSS

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.

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.

• warkdarrior

  today at 6:28 PM

  Agreed, if you need programmable content you can add some Javascript: https://www.markdownlang.com/advanced/javascript.html

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.

• krapp

  today at 6:37 PM

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

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.

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.

All problems are solved once you embrace org-mode.

All you need is Emacs! Nothing more!

• sophacles

  today at 6:39 PM

  Objectively false. Please stop spreading misinformation.

  • BeetleB

    today at 6:43 PM

    I can think of a lot of potentially false things in the statement. The biggest falsehood likely is the perception that one needs Emacs. :-)

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.

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

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.

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)

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

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.

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

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.

• mewpmewp2

  today at 6:27 PM

  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.

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.

Aaron needs to hurry up and reincarnate already.

• jedberg

  today at 6:24 PM

  Aaron had very little to do with Markdown, other than reviewing the spec once at the end.

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.

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.

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

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

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.

Because there's only one reasonable implementation of AsciiDoc

Markdown lacks JavaScript and can be considered mostly harmless.

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)

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

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.

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.

These examples are contrived af.

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

• aerhardt

  today at 6:27 PM

  Yea I’ve been typing encyclopedias worth of markdown, most to throw away, some to publish, and I’ve never had any the problems shown here.

You can say hell on your own blog.

• sophacles

  today at 6:39 PM

  Interestingly, you can also choose not to say it on your own blog.

  • BoredPositron

    today at 7:40 PM

    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?

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.

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

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.