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.
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 (emphasis) tag, which is rendered as italics in most browsers.
Suppose you want to use asterisks to mark footnotes.* As soon as you add a second footnote,** you're in trouble because your asterisks disappear and everything between them turns bold.
* I had to escape all of these asterisks.
** I see this happen fairly often to people's comments here.
> It should turn bold but keep the asterisk displayed so you can still edit as normal.
This is just terrible UI, why do you need garbage marks when you already have bold? And you can edit "as normal" if you like, but that only requires displaying asterisks during that tiny % of time you edit the word, not all the time when you read it or edit something else.
So you can still see the actual text that you're editing. And to reduce ambiguity. If you don't leave them, then you can't distinguish between adding more bold text to currently bold text or adding non-bold text immediately after
> So you can still see the actual text that you're editing
But you're not editing that text! You're editing some other text and see a bunch of asterisks all over the place. And this is especially bad in nested styles - try some colored bold word in a table cell - without hiding the markup you'll basically lose most of visibility into the text/table layout
> to reduce ambiguity
it does the opposite, you can't easily distinguish between an asterisk and an asterisk, which is... ambiguity
> can't distinguish between adding more bold text to currently bold text or adding non-bold text immediately
Sure you can. In a well-designed editor you'll see the style indicator right near your caret is so it's always obvious whether and how your typed text is styled or not.
In a not-so-well-designed editor you'll get that indicator far away from your caret or just get asterisks appearing when you need them.
In a not-designed editor you'll see them all the time even when they don't serve any purpose.
One problem with the /italics/ form is that it's not convenient when writing about filesystem paths (though I do like its visual indication of slanting).
Or italics can be //double slash// to avoid ambiguities with file paths. That still leaves the windows style //some/file/path as ambiguous
But I’ll never accept single * as natural for italics.
I agree that using *asterisks* just feels wrong for italics, and are much better suited for bold. However, surely the _underscore_ is just perfect to visually indicate underlining?
As for /slashes/, which would visually be perfect for italics, the only reason they conflict between italics and filepaths is the fact that in both cases they are expected to be used at the beginning and end of a word. Maybe using an unnatural placement of )parentheses( could have worked as a non-conflicting indicator of italics.
_underscore_ for italics conflicts with most identifiers in most languages.
Markdown was created in an era before the web had easily used components for structural syntax highlighting (tree-sitter) and where reliance on regex-based approaches was more common.
Thanks for posting this. I feel like for years we've been getting gaslit by the Markdown guys who inexplicably decided that stars should make text go italic instead of bold. I get it wrong every single time and then have to go back and look up a cheat sheet. It really isn't intuitive at all, and it also doesn't codify how we used to write before rich text entry boxes where available everywhere. Markdown reminds me more of all the custom wiki and forum markups that proliferated in the 2000s than any text-based conventions in use prior.
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
Writing mark down linter, i am i nterested in - if you think that you requirements for markdown formatting could be encoded in (relatively) simple rules?
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.
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)?
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.
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.
> 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:
This may be the first time my reaction to an objectively terrible programming language is a shrug and a "whatever". I like using markdown. I use it for journaling in Obsidian. It does everything I want it to. I like that it's just flat files. I don't want my journaling to be stuck in some online database.
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.
It is because the primary target for markdown is what would in any other formatting language be the source. Markdown has no source. It is guidelines for good looking plain text layout that when followed can be used to make a typeset document.
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.
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.
This is just like the debate over YAML. In both cases, the language is simple enough, and people use it sanely enough in practice that I just don't care about the warts. Contrast this with something like C++, where the warts are less avoidable and therefore more worthy of notice. Markdown as I use it is functional and simple and no one has suggested an alternative I like better, so I keep using it.
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.
309 comments
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 (emphasis) tag, which is rendered as italics in most browsers.
* I had to escape all of these asterisks.
** I see this happen fairly often to people's comments here.
The bullet point problem is fixed by only bolding when the asterisks are on either end of word characters.
> It should turn bold but keep the asterisk displayed so you can still edit as normal.
This is just terrible UI, why do you need garbage marks when you already have bold? And you can edit "as normal" if you like, but that only requires displaying asterisks during that tiny % of time you edit the word, not all the time when you read it or edit something else.
> So you can still see the actual text that you're editing
But you're not editing that text! You're editing some other text and see a bunch of asterisks all over the place. And this is especially bad in nested styles - try some colored bold word in a table cell - without hiding the markup you'll basically lose most of visibility into the text/table layout
> to reduce ambiguity
it does the opposite, you can't easily distinguish between an asterisk and an asterisk, which is... ambiguity
> can't distinguish between adding more bold text to currently bold text or adding non-bold text immediately
Sure you can. In a well-designed editor you'll see the style indicator right near your caret is so it's always obvious whether and how your typed text is styled or not.
In a not-so-well-designed editor you'll get that indicator far away from your caret or just get asterisks appearing when you need them.
In a not-designed editor you'll see them all the time even when they don't serve any purpose.
edit: HN automatically finds this example and puts in escapes to make it work. From elsewhere in the discussion I just want AsciiDoc.
https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-mar...
backticks.Or italics can be //double slash// to avoid ambiguities with file paths. That still leaves the windows style //some/file/path as ambiguous But I’ll never accept single * as natural for italics.
/root...*bold* and _italic_ would have been better.
As for /slashes/, which would visually be perfect for italics, the only reason they conflict between italics and filepaths is the fact that in both cases they are expected to be used at the beginning and end of a word. Maybe using an unnatural placement of )parentheses( could have worked as a non-conflicting indicator of italics.
Markdown was created in an era before the web had easily used components for structural syntax highlighting (tree-sitter) and where reliance on regex-based approaches was more common.
>
Maybe using an unnatural placement of )parentheses( could have worked as a non-conflicting indicator of italics.Using different delimiter for opening and closing is a good idea on its own, too. I think it makes parsing simpler and unambiguous wrt nesting.
I've imagined something like this:
Probably looks a bit more distracting, though.> Maybe using an unnatural placement of )parentheses( could have worked
O, c'mon! That is clearly a giant heading in a display font, squeezed in the middle and wider at the top and bottom. (-;
> worse is better
It's a very old idea
https://en.wikipedia.org/wiki/Monetae_cudendae_ratio>
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)?
* 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.
There's the stuff that wows people and the stuff that people actually USE.
• 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.
> We want to encourage people to produce written output with minimal friction.
What's wrong with .txt ?
> 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:
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:
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.