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.
In the paper, Copernicus postulated the principle that "bad money drives out good", which later came to be referred to as Gresham's law after a later describer, Sir Thomas Gresham. This phenomenon had been noted earlier by Nicole Oresme, but Copernicus rediscovered it independently. Gresham's law is still known in Poland and Central and Eastern Europe as the Copernicus-Gresham Law.
Saying, that it is the best compromise we know of is going a little far, I think. There are more readable intuitive formats, but they simply don't have the spread, that markdown formats have.
> 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!
What about something like AsciiDoc (or reStructuredText)?
> barriers to producing documentation--should be minimized. Writing well is difficult enough!
Writing is a demanding kind of encoding. At the same time, we all expect but rarely get good, accessible, searchable documentation. Why? The one barrier that cannot be removed is the need to retain semantic structure.
In TFA, the author writes:
The Bad -- We don’t know what we want.
It's exactly this. We fail to recognise why we write and then we fail to express it. We don't write technical documentation for the equivalent of KLOCs. Writing something useful and meaningful -- not just performative filler for KPIs or SEO enshittification -- requires structure. Anything valuable that can't be retrieved effectively is lost. Imagine losing actual code or database rows at the same rate.
We consistently fail to manage meaning. It's strikingly paradoxical because the art of programming is all about meaning. We organise code semantically because it is essential to do so (not just for compiling, but also) for extending/refactoring/review/retrieval/understanding.
We need to write with the same considerations. This need not be complicated. Yet we persist in using the wrong utensils for the recipe.
> Markdown is the best compromise we know of
It reduces keystrokes and makes the handraulic act of writing easier. But... it addresses only part of the problem.
As an example of a small improvement, HTML5 offers a minimal set of semantic tags: <summary> <article> <main> <section> <details> <aside> <figure> <figcaption> <time>
It may be a simplistic set of tags, but it is an improvement over easy-to-type text blobs.
It's the inescapable truth that even after sitting down and engineering a magical solution ... sometimes just a basic CRUD function with just a couple bits added that doesn't have all the bells and whistles is what actually lasts when I write code and requires less maintenance.
There's the stuff that wows people and the stuff that people actually 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)
I just cannot fathom the thinking behind presenting URLs but not linking to them. The author clearly knows something about all this (unless it's AI-written, but I don't think it is), so how have they made such a glaringly obvious mistake?
I'm half wondering if they're using a very strange CMS to publish this blog. The fact that they seemingly cannot use the correct double-quote character in their code blocks lends a bit of support to this theory.
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.
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.
> 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.
> 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.
You know, like when you write <h2> in HTML or \section{} in LaTeX?
...and? What a weird article. Of course two different pieces source code can produce identical output. Every single mainstream languages are like that too.
One big thing I still miss with org-mode are explicit section endings. Just as with markdown you only have headings, the end of a section is implicit. This often leads to text getting swallowed up by the last chapter and makes any kind of restructuring fragile. HTML's <section> makes things much easier.
Having explicit header levels (similar to HTML's <h[0-6]>) is another annoyance, as that makes inclusion of one org document into another problematic and requires restructuring (somewhat workaroundable with "#+begin_src org").
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.
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.
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.
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 enjoyed how it complained about how unclear and ambiguous Markdown’s syntax for bold and italic text supposedly is, then showed an HTML translation with <strong> and <em>.
151 comments
[ 3.5 ms ] story [ 116 ms ] threadWe 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 very old idea
https://en.wikipedia.org/wiki/Monetae_cudendae_ratioWhat about something like AsciiDoc (or reStructuredText)?
* https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-mar...
* "Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code": https://news.ycombinator.com/item?id=33468213
Simply things are still simple, but there seem to be more advanced options for those that want/need them.
Writing is a demanding kind of encoding. At the same time, we all expect but rarely get good, accessible, searchable documentation. Why? The one barrier that cannot be removed is the need to retain semantic structure.
In TFA, the author writes:
It's exactly this. We fail to recognise why we write and then we fail to express it. We don't write technical documentation for the equivalent of KLOCs. Writing something useful and meaningful -- not just performative filler for KPIs or SEO enshittification -- requires structure. Anything valuable that can't be retrieved effectively is lost. Imagine losing actual code or database rows at the same rate.We consistently fail to manage meaning. It's strikingly paradoxical because the art of programming is all about meaning. We organise code semantically because it is essential to do so (not just for compiling, but also) for extending/refactoring/review/retrieval/understanding.
We need to write with the same considerations. This need not be complicated. Yet we persist in using the wrong utensils for the recipe.
> Markdown is the best compromise we know of
It reduces keystrokes and makes the handraulic act of writing easier. But... it addresses only part of the problem.
As an example of a small improvement, HTML5 offers a minimal set of semantic tags: <summary> <article> <main> <section> <details> <aside> <figure> <figcaption> <time>
It may be a simplistic set of tags, but it is an improvement over easy-to-type text blobs.
There's the stuff that wows people and the stuff that people actually USE.
What's wrong with .txt ?
... 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)
I'm half wondering if they're using a very strange CMS to publish this blog. The fact that they seemingly cannot use the correct double-quote character in their code blocks lends a bit of support to this theory.
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.
Nobody uses markdown like that bro. We like markdown because it's easy to read both rendered and raw.
Html has that same problem. Think <b>, <strong>, <p style=“font-weight: 900;”>, etc.
That’s life. Get used to it.
Check out my "Advent of Markdown" where I go through surprising markdown behavior: https://mastodon.social/@timokoesters/115643467322561173
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.
You know, like when you write <h2> in HTML or \section{} in LaTeX?
...and? What a weird article. Of course two different pieces source code can produce identical output. Every single mainstream languages are like that too.
All you need is Emacs! Nothing more!
Having explicit header levels (similar to HTML's <h[0-6]>) is another annoyance, as that makes inclusion of one org document into another problematic and requires restructuring (somewhat workaroundable with "#+begin_src org").
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.
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.
BTW TempleOS terminal comes into mind. I really love the hyperlinks.
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.
Then, in the solution section, doesn't identify a solution.
No thank you, I'll stick with Markdown.
If you’re used to CommonMark features, this is all you need.
[1]: https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-mar...