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.

Yet, I am the same person who refuses to code in anything but Rust due to how not-awful it feels to me. Strange how a person can hold a completely opposite view for two instances of the same problem. Being human in a nutshell.

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.

Everybody sort of knows it sucks as a formatting language. But we love it anyway. The benefit of being able to get a typeset document from a nice looking plaintext document is just too convenient. It is why specialized markdown editors make no sense to me. Why would you target something as shitty as markdown if you have a specialized editor? But really, if you at all care about the semantics of your document don't write it in markdown. But more importantly please don't kill the utility of markdown by adding semantics to it, all that noise just make the plain text look bad.

Also, as I use it, Markdown is effectively plain text. I very rarely look at "rendered" markdown. I guess in practice I actually use "plain text" that just happens to look a lot like markdown by this article's definitions.

This blog post makes no sense to me.

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.

1. Use a proper Markdown parser. The grammar is easy to define EBNF style most implementations I see now days use some recursive descent parser, etc… Regex implementation was used in original authors parser when it became popular.

2. You can resolve ambiguities and define more consistent symbols that make sense. Most markdown implementations are decent and follow common sense best practice syntax.

3. The beauty is its simplicity. You can pick it up in a few minutes and utilize it anywhere you damn near see a text box.

4. Parsing to HTML isn’t the only option! I mostly use TUI markdown viewers that render the document via ANSI escape codes beautifully. Check out glow project. But once you parse and have a AST, you can easily walk it and render it in other ways as well. Again though. Everyone can read a text document and a html document. You can render it to a PDF if need be.

5. Do we really need a whole new markup text2<format of some kind>? Markdown is simple fast and widely supported. So I have to say.. I prefer it over most things and that includes Rst.

If you need real beauty and power you can move to LaTeX or something… My two cents anyway.

Have used asciidoc, HTML, word, latex, and rst.

Markdown is the least painful of all. It's not perfect but the others are worse.

(My custom stack uses markdown (or Jupyter notebooks converted to markdown). Pandoc plus some custom filters creates typst (for PDF) or epub.)

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

That’s life. Get used to it.

What do you all think of Djot?

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

No thank you, I'll stick with Markdown.

Markdown though, especially if you're not using way too much of it and mostly using it sensibly, just to give your document some structure, can be read as plain text by pretty much everyone, and will be implicitly understood. Sure, they might not understand the exact different between a word with asterisks on either side and one with underscores on either side, but they'll get that you meant to emphasise that work. They'll also understand a list shown with asterisks, while <ul> and <li> tags will get too verbose for them and clutter the actual content (I don't really care, but I get why they do).

Programming languages (and the like) are for humans, not for computers or for creating formal systems.

Understanding this simple fact will save you (and by you I mean me and the type of people who frequent sites like this) a ton of headache.

A critique of MD carries no wind in my sails when it can't even appreciate why marrying multiple contemporary chat-grade formats into a document format might be a helpful thing.

Of course there are problems as you veer away from chat-like messaging, but it does a lot, and allows HTML when it can't go any further.

This is my single biggest complaint about reStructuredText. You create headings by putting underlines and (optional!) overlines around the section heading text. But all of the following are valid title adornment characters:

  ! " # $ % & ' ( ) \* + 
  , - . / : ; < = > ? @ 
  [ \ ] ^ _ ` { | } ~

  ==
  H1
  ==

  Normal text

  --
  H2
  --

  H1
  ~~

  Normal text

  !!
  H2
  !!

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.

This sentence is a great example of why such a pointless debate continues. Don't disparage HTML as "only" a markup language; it's a markup language. That's no 'better' or 'worse' than a programming language, just different.

A thread on markdown creator's stance https://x.com/nalband/status/1625541479295860752

All you need is Emacs! Nothing more!

The author of this article appears to be unaware of pandoc, and even better quarto. I started with pandoc and various plugins and my own scripts but moved to quarto, it is excellent.

https://quarto.org/

We all need headers and paragraphs, right. But I might want file listings. Or command-line snippets with my own color coding and marks. Or C declarations and precise references to them in text. Or todos. Or bibliographic information. Or I want to express the difference between emphasis and italics. Or I don't. And so on. With XML I grow my own notation that fits like a glove. There's no boilerplate, everything is there for a purpose.

Besides, it is not that incompatible with plain text. Here's plain text:

    abc def ghi

    <text>
    abc def ghi
    </text>

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.

Markdown in the same directory as the code it documents is very readable by humans and LLMs.

Given LLMs proficiency in markdown and that reading it in view and edit mode is comparable I bet many engineering teams ditch confluence/Google docs for documentation in favor of just markdown plaintext docs adjacent to code (my team has moved design/RFCs to this as well, get feedback via PR commits, turn an LLM loose to implement design)

Also if you really don’t like it I bet you could just ask the LLM to translate it. No point wasting the human input characters or tokens on a ton of <></> etc

Markdown apologist here - I think MD is the greatest thing since sliced bread and I use it a LOT. In fact, one project I work on has an entire git repo of just MD docs. It’s easy to maintain, and even non-tech people can author them with ease. In fat, I love that raw MD is entirely human-readable, and even if someone fat-fingers some of the syntax, it’s still very forgiving.

Don’t forget, many MD renderers support regular HTML embedding, including <style> tags, which makes it a very flexible choice.

I don’t think it’s going anywhere!

if you tell somebody they can use HTML, they get frustrated when you tell them that tags other than anchor, bold, italic, list, heading, and paragraph aren't supported. but if you tell somebody they can use markdown, then they implicitly understand that the content they're submitting won't be rendered as green text on a purple background, and don't try to accomplish that.

And this is what Markdown is for: its just enough above plain text such that you can get at least 95% of what you need for a blog post, whilst still have the source be easy to type and proof read.

I do love writing in Markdown, but my reasons are adjacent in some ways. It's a flat file, the syntax is easy to on-board new users with, adoption is widespread, and the HTML escape hatch is available. I only adhere to the syntax because I can usually expect a parser to exist for whatever environment I'm in.

I don't think this is the best we can do (or have done). I find myself conflicted about where to go next. Gemtext is nice! Except, what I often want is more expressiveness and consistency. This will probably be, for me, a spec that can still be run through a "reasonable" Markdown parser. When the output breaks, it still comes out as readable plain text (albeit with some weird ASCII scattered through my prose).

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.

    # Hi
    
    I am a <ins> simple </ins> _programmer_ doing
    <span class="fancy-text"> elegant </span> programming.
    
    <div class="animation">
    
    And here is my portfolio
    
    </div>

    I am a <span style="color:green">super *grinch* yall</span>

    <p>I am a <span style="color:green">super <b>grinch</b> yall</span></p

Similarly, the div in the first example produces div, p, close-p, close-div, because the rule isn't "find he closing tag". The rule is something like "if the line starts with html then stop parsing and just copy until the next blank line.

All that said, I know the rules and generally know how to follow them. Of course I still run into the issue that even though there's commonmark, every site and tool is running their own variation which are incompatible.

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.

[0]: https://typst.app

Pandoc can convert Markdown to .icml this is an Adobe InDesign format which allows you to go from markdown to a professional typesetting solution including figures, footnotes etc.

Of course if you write a physics or math paper there are better solutions, but for the majority of things you could write markdown is good enough and that is the reason so much of the content you encounter is in markdown.

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.

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.

The issue is that simple.

Personally, I always default to the simplest of tools. That's why I truly believe that anything meant for actual human use needs to have reasonable defaults. No "look at all the configs you can have", but a "let's get you what you need".

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 way to do it and no embedded html we would be better off.

And I say this while putting up with lousy Markdown rendering on a pet project (Django). Really needs a separate project which lets you massage the html to get the display looking it’s best.

##[color:red] Heading 2

or using code blocks with particular headers which render out as normal text with the styling applied, like this:

```styling: 'ruleset here...' Lorem Ipsum Dolor ```

this does require a lot of work to consider what might be ergonomic for a particular element (by element I mean ATX headings, blocks, etc.), though.

Most md editors don't support collapsing or folding sections, even though they could. VSCode had this feature where indentation is used as a simple hint to support collapsible sections, but md treats indentation as a code hint.

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.

- Reverse the link syntax braces, so the URL is in [], and the link text is in ()

- Allow table cell content to have line continuations

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

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’ve never attempted a markdown parser let alone any parser, so pardon me for asking a stupid question: doesn’t the markdown parser just let through HTML? Why does a markdown parser need to parse html?

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

If we are still using XML/YAML/JSON etc despite all their faults and shortcomings, Markdown can (and will) last decades.

https://www.zettlr.com/

† Obviously, for physical reasons given our current understanding of cosmology, no _implementation_ of a language can ever really be Turing-complete, but some language definitions are theoretically compatible with Turing-completeness, and others aren't.

Markdown is only going to get more popular as AI agents usage grows.

Use the best tool for the task. markdown is really good for talking to AI as a human for example.

Same goes for JSON, YAML, etc.. use what makes sense to you. I like markdown but I have issues with it as well. I like html, but i despise it sometimes. One-size-fits-all is the real enemy.

My view is that for all *langs (markdown, config, data, code, styling,etc..) we should leave the proverbial cave and come down from the trees, and talk about interoperability and best practices. Contracts, expectations, and exceptions.

There is this pattern where we invest in some software technology, and it becomes this ideology people fight over. Or invest a lot into it and fall into sunken-cost thinking.

Being able to rapidly figure out the best tool/solution, and readily tear out the old and patch in the new with minimal loss and friction, that should be the next era of tech. Not a repeat of the old, with a slight twist. I don't need another JSON, Markdown, HTML, CSS, C, Rust,etc.. especially with the advent of LLMs (hype aside), syntax is important but it isn't what it used to be. I want to be able to write in Markdown and know that if there is a better format, I can easily stop using it and reliably transpile all my existing Markdown, and tooling that works with Markdown to use that new format.

Adaptability and communication are the biggest dead-weights holding back technological progress.

It's not possible. HTML is worse. You need at least something, which on parsing does not segfault.

Markdown is great at small-to-medium documents; LLMs seem to like it too possibly out of a combination of fairly logical design and lots of training examples.

Custom extensions like |||warning\nDisconnect from the internet befor trying this!\n||| get you a bit further and don't tie you into HTML.

The moment you need multiparagraph items including code blocks inside a numbered list that also has an unnumbered list child of which some of the items are images ... the person who set you that task probably doesn't understand good design, but regardless, I find you need something with an explicit tree structure, that is there are markers for both the start and end of each node such as <td> ... </td>. That necessarily makes the document harder to write, though at that complexity it'll probably be hard to read too.

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

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.

If what is to communicate, plain text is good enough. If you want to control how information is consumed, fuck of, die already.

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

> It has so many poor decisions baked in that if you try to use it it will actively fight against you the moment you think you know what you’re doing.

That misses the point. The point of Markdown is simplicity, not perfection. And that is also the reason why Markdown will prevail.

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.

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.