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 <em> (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.
Ha, I remember this religious debate all the way back in the days of text-mode word processing in the 80s on CP/M and PC. I was indoctrinated in the WordStar camp where style controls were visible in the editor between actual text characters, so you could move the cursor between them and easily decide to insert text inside or outside the styled region. This will forever seem a more coherent editing UI to me.
This might be why I also liked LaTeX. The markup itself is semantic and meant to help me understand what I am editing. It isn't just some keyboard-shortcut to inject a styling command. It is part of the document structure.
Heh, I'm not even sure WordStart other styles at that level. Changing the color back then would mean having the print job pause and the screen prompt you to change ink ribbon and press a key to continue. I can't remember if it could also prompt to change the daisy wheel, or whether font was a global property of the document. The daisy wheels did have a slant/italic set, so it could select those alternate glyphs on the fly from the same wheel. Bold and underline were done by composition, using overstrike, rather than separate glyphs.
But yeah, this tension you are describing is also where other concepts like "paragraph styles" bothered me in later editors. I think I want/expect "span styles" so it is always a container of characters with a semantic label, which I could then adjust later in the definitions.
Decades later, it still repulses me how the paragraph styles devolve into a bunch of undisciplined characters with custom styling when I have to work on shared documents. At some point, the only sane recourse is to strip all custom styling and then go back and selectively apply things like emphasis again, hoping you didn't miss any.
And... I preferred WordPerfect's separate "reveal codes" pane, which reduced the opportunity for ambiguity. WP 5.1 has never been equalled as a general-purpose word processor.
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?
Commommark is the best, then looking at the most commonly implemented extensions:
- Superscript with hat symbol (^)
- Hidden content (also known as spoiler tags, content warnings, click-to-reveal, etc...) with two pipe symbols (||) at start and end of hidden content. Interact with the content to show the content inside.
- Table syntax to show tabular data and align content with pipe, hyphen, colon symbols
---
After that, I'd look at the extensions that are only useful for the use-case you're targeting:
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.
I see one, but then maybe I am just seeing things.
The wikipedia page about "worse is better" re: software linked above states:
It refers to the argument that software quality does not necessarily increase with functionality: that there is a point where less functionality ("worse") is a preferable option ("better") in terms of practicality and usability.
Copernicus' idea about money has a similar structure - "better" money such as precious metals, art, etc. is being hoarded due to its perceived desirability, leading to more "worse" money in circulation. As a result, the "worse" money is actually "better" at fulfilling its role as currency (bc it's not hoarded). So there is also a point where "worse" becomes "better".
Bad money drives out good money only if there is a legal tender law such that both have to be accepted for the same nominal value. In this case, good money is hoarded because it cannot be traded for its true value.
> 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)?
The problem is that proposed Markdown alternatives are targeting a vanishingly small niche of scenarios: for almost all simple writing Markdown is good enough, and for anything too complicated for Markdown, people will use HTML or LaTeX/Typst. The in-betweens just don't seem to have a reason to exist.
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.
Because I think, that there are other formats, whose formatting rules are more intuitive than Markdown's formatting rules. For example:
(1) I can never remember, whether I need to use [] or () first, when embedding an image. In Org mode syntax one simply uses [] for both parts.
(2) Or whether ** is bold or italic or * is bold or italic. Other formats use the well known / to mean italic, which optically already makes more sense and also doesn't interfere with something being bold or not, because it is a separate symbol. This makes Markdown also harder to parse btw..
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.
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.
> the only thing I regularly mix up is the syntax for links. I frequently reverse the [] and ()
I remember it as passing parameters to a function that requires an URL as an argument. Maybe it's not the most straightforward way, but it works for me
I remember it like this: If you squint the brackets around the link text make a rectangle and look almost like a button you can press. [Press here](to.go.there)
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
Then you might like Obsidian. When the cursor is in some bit of formatted text, it displays all of the characters. When the cursor is elsewhere, it just shows the formatted text.
In the worst case, the barrier to entry and exit are pretty low.
First you can switch from WYSIWYG to text editor instantly.
Then you have an outline where you can manipulate your “markdown blocks” [i.e title and its content] by drag n drop. Or extract a “markdown block” as a new note, and leave a reference where it originally was extracted from.
And then [the killing feature], it displays the content of a link, web link or internal link, as a [kind of] iframe, if you prepend a ! to the link.
> 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.
Ugh, troff. It's mind-boggling that the closest way to have an actual (hyper)link in a manpage is to use your pager's "search for text" function. No, "JuSt usE gNu iNfO it'S beTtER" is not an answer either.
groff can produce output with links in it, and does by default in HTML mode! The GNU version of the Unix man page macro set has .UR and .UE for “URI start” and “URI end”. (I don't know whether these were present earlier in the lineage or whether they were introduced by GNU.) Also, the lowdown Markdown converter when in man output mode will output those for links. For fun, try:
echo 'Hi there! Have a [hyperlink](https://www.gnu.org/software/groff/manual/groff.html).' | lowdown -st man | groff -man -Thtml
There's also support for OSC 8 terminal hyperlink sequences throughout most of the groff toolchain: grotty(1) supports outputting them, and less(1) supports passing them through, including ^O^P and ^O^N gestures for moving between them. But man(7) says they're not enabled for grotty output by default. “Options” describes the rationale in its item for “-rU1”: “grohtml enables them by default; grotty does not, pending more widespread pager support for OSC 8 escape sequences.”
So if I set MANROFFOPT=-rU1 in the environment, I can get clickable links in man… if the man page author included them that way in the first place. I'm not sure how common that is in the wild, but grepping the ones on my system, I find firejail(1) contains a link to a GitHub issue embedded in that way, and it does indeed work when I hit ^O^N to seek to it and then C-mouse1—though the mouse gesture I have Alacritty using for links doesn't seem to work through tmux (there might be a way involving twiddling the tmux terminal-features setting, but I ran out of steam before trying this), and I didn't see a great way to get either grotty or Alacritty to style them on display instead of having them blend into the surrounding text, so it's still kind of scuffed in practice. (Though I bet the cool kids have moved on from Alacritty by now?) less displays the link target in the status line when you use the navigation commands, so it's not inaccessible, but for opening selected links directly from less with the ^O^O gesture rather than leaning on terminal support, it looks like you need to explicitly set the LESS_OSC8_ANY and/or LESS_OSC8_‹scheme› environment variable to a shell command that outputs a shell command pattern to substitute the link into; if I set LESS_OSC8_ANY='echo xdg-open %o' then it passes it to my Firefox. I wonder if they'd take a patch (or if any existing distributions patch it) to use that as the default?
That was a fun little rabbit hole to go down, thank you.
I mostly care about links inside the man page (look at man bash — there are tons of internal references like "described below under CONDITIONAL EXPRESSIONS" or "section SHELL BUILTIN COMMANDS below", or operators being underlined and looking like hyperlinks, which you can't easily interact with to just go to where they refer to. You have to employ full-text search, but it also turns up the references themselves, and good luck searching for the place where e.g. command "." is described) and links to other man pages, not the normal Internet URLs being clickable (those things are trivially copy-pastable into a browser next window).
Ah! Yeah, that makes more sense—I misinterpreted you at first since I don't normally think of “internal link” as the default exemplar of “hyperlink”. And yeah, I don't see good target markup for that. Stuff like starting your search regexp with “^ +” helps but is still janky. I'd tend to categorize this mostly as “man pages aren't meant to be long treatments of more complex software”, of course? Some large packages do something which I kind-of like but which I'm not sure would work well if everyone did it (mainly due to ergonomy around disambiguation) where they split up a bunch of their documentation into shorter pages with the origin as part of the section when making it accessible through man: pcap_init(3pcap) from libpcap, Bigarray(3o) from OCaml. Shells, as you notice, get hit by this really hard; Zsh tries to do some splitting in the man version of its docs, but it's really not enough, like I'd want to see fc(1zsh) (and then fc(1bash), etc.) but instead it's all in zshbuiltins. (Eventually I facepalmed when I realized an Info version was available and switched to that. The way I found this out was actually by eyeing the Zsh source tree and noticing that the documentation files were written in Yodl, which I'd never heard of, and then noticing that the schema they were using looked a lot like Info…)
… wow, hang on, I just checked for Bash, and it has an Info file but it says it's just an intro and the manual page is the definitive version‽ That's… hah. There must be some timeline jank around that; ambiguous NIH vibes around Info aside, I wouldn't have expected it from an actual GNU program! Did Bash show up before Info existed?
A man page is simply a formatted text file. The display of it is performed by the program defined in the MANPAGER or PAGER environment variable, or by a default program, usually less(1). That is the program that would be responsible for navigating any hyperlinks, and the format of references to other pages is already pretty easy to pick out so developing a man page reader that could follow references to other man pages would not be particularly difficult. Many web-based and GUI man page viewers do this. Example: https://github.com/zigalenarcic/mangl
> The display of [a man page] is performed by the program defined in the MANPAGER or PAGER environment variable, or by a default program, usually less(1).
A man page source isn't a binary format, so your statement that they're "plain text" is technically correct. (The same is also true of TeX and LaTeX files, and even PostScript if you want to stretch the definition of "plain text" until it snaps.) But the renderer is groff or (legacy) troff with the `an` macro set. less(1) (or, originally, more(1)) is just the pager that consumed the former's output (if the output format is ASCII, which is one of many) and handled paging on the terminal for the convenience of the user.
In my old Sun workstation (and even early Linux desktop) days, I rarely used man(1) in the terminal because 1/terminals were usually too small and weren't usefully resizable like they are today, and 2/unadorned monospaced fonts don't look nearly as nice as properly typeset pages do. (Color terminals were just coming on the horizon, and text could only be emboldened, not italicized.) Instead, I typically used xman whenever I could. The best way I can describe xman is as if you were rendering man pages into PDFs and viewing them in Preview on the Mac. Man pages were much more comfortable to read that way.
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.
> Markdown in an of itself isn’t powerful enough to satisfy the simple monkey brained developer like me who is only satisfied when the site looks good enough™.
Well, indeed, Markdown is an inadequate tool for that. Let the author use more powerful tools, be it HTML, LaTeX, SVG, etc.
Markdown is fine for its intended purpose: very light formatting, very simple header structure. If I were not that lazy, i would come up with something opposite to CommonMark, some MarkDownDown, that does away with alternative ways to format things, most escaping, and most advanced syntax. The goal would be to have an easy-to-implement, unambiguous, safe and simple subset good for use anywhere. Intentionally limited.
(For daily use I prefer Org Mode, due to its vastly superior support in my preferred editor.)
> If I were not that lazy, i would come up with something opposite to CommonMark, some MarkDownDown, that does away with alternative ways to format things, most escaping, and most advanced syntax.
Being a strict subset of Markdown would make it itpossible to achieve simplicity. From the rationale:
> Rules for emphasis should be simpler. The fact that doubled characters are used for strong emphasis in commonmark leads to many potential ambiguities, which are resolved by a daunting list of 17 rules. It is hard to form a good mental model of these rules. Most of the time they interpret things the way a human would most naturally interpret them---but not always.
Any other combination does not parse as formatting, and is considered literal text. Yes, this prevents marginally useful cases like putting an italic fragment in the middle of the word. I'd be fine with that.
Word boundaries are a complex thing, especially in languages like Chinese or Japanese. Whitespace and punctuation are much less complicated, even if we take the full Unicode case. So the boundary where formatting is considered is between (whitespace | punctuation) and anything else.
So now you have to distribute a character class table in every implementation of your language, which is precisely what the author of Djot wanted to avoid.
• Markdown (most of my notes these days, supplanting my previous use of plaintext.)
• Single-file HTML (when my use case for fancy documents exceeds markdown's limits. While you can embed HTML into markdown, renderers vary in what they allow or sanitize, and vary in how you can (ab)use style tags. I've even taken to looking up CSS rules for printed documents, since my intended target is often pdfs or actual print at that point. Occasionally, JavaScript!)
• Google docs (Android phone nonsense!)
I'd mutter something about "using the right tool for the right job", but that's probably giving myself too much credit.
Exactly. I write my own notes in markdown, it works with or without a viewer app. I am not even sure if there is a better alternative. This format is good enough for most of the casual and semi serious use cases
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.
"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.
Have you tried Asciidoc though? It is, IMHO, much clearer than markdown (YMMV, obviously), and exactly the same pros you gave of markdown can be said of Asciidoc.
Bonus: It starts simple but can be used to do whole books if needed.
My experience is that Asciidoc very quickly gets into advanced syntax.
If you introduce something with advanced functionality onto a team, soon enough someone's going to use pieces that others don't fully understand later.
Now everyone touching the document has to understand includes and document metadata and whatever else someone added. Suddenly you have includes and cross-references and what used to be a document where you could read the raw non-rendered form linearly top to bottom is a confusing mess unless you render it. Markdown is almost always just as legible raw as rendered.
"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.
Yes, it's obviously "against common usage" given HTML support exists specifically for less common features that Markdown does not support. Like tables, which are supported by some implementations but not all, and iirc not even all Markdown variants that support tables use the same syntax for them. The only way to be 100% sure is to use HTML. Of course you wouldn't do that if you just have the file on Github, but in general HTML is supported in Markdown for a reason.
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.
Unfortunately, the plain text does not look good, and does not offer good control of the typesetting. At least, nearly all markdown I see is almost unreadable in its “raw” state. I’d much rather read manually formatted, monospaced, text. That way, you can use asterisks as bullets, as footnote markers and as emphasis markers all at the same time, and anyone who is familiar with normal typographic conventions will understand what is what.
Not too long ago, I used to think that Markdown was the Bee‘s knees. But having been forced to write some documentation in plaintext, I learned that plaintext is significantly more readable than raw markdown.
I think one of Markdown‘s biggest sins is how it handles line breaks. Single line breaks being discarded in the output guarantees that your nicely formatted text will look worse when rendered. I understand there are use cases for this. But this and the „add a trailing space“ workaround are particularly terrible for code documentation.
> I think one of Markdown‘s biggest sins is how it handles line breaks. Single line breaks being discarded in the output guarantees that your nicely formatted text will look worse when rendered.
My experience has been the complete opposite. Markdown parsers that don’t discard single linebreaks (e.g. GitHub-flavored markdown) turn my nicely formatted text into a ragged mess of partially-filled lines. Or for narrow display widths, an alternating series of long and short lines.
Markdown parsers that correctly discard single linebreaks make sure that the source text (reflowed to fit a max number of characters per line) and the rendered text (reflowed to fit the display width per line) both look reasonable.
> Why would you target something as shitty as markdown if you have a specialized editor?
Your at-rest format allows you to use any tool to edit it.
The specialized editor becomes a preferred tool, but not the only tool nor the most important one. Markdown and it's ecosystem came before the editor.
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.
> 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?
Problem with that is that the default browser styling is extremely ugly and the ability for custom style sheets was removed from the browser GUI many years ago. ReaderMode and Addons can help, but as long as the default is essentially broken and unsupported that whole approach remains a dead end.
On top of that come issues like the lack of pagination support in browsers, which make long document impossible to read and practically require to add custom UI inside the website itself.
ePub works much better, with readers giving control over line spacing, font size, pagination and proper markup for TOC and other metadata, but despite ePub being based on xHTML, browsers have ignored it (only old Edge supported it for a little while).
On this planet, humans have read HTML without parsing for years. People building their first websites without any significant technical knowledge stole HTML by reading the source of other sites and edited it by hand.
Oh, please. Don't insult everyone here by pretending you actually believe HTML is a human readable format like markdown. It was never designed for that and has never claimed that.
It is. Humans do read it, and have read it. Like any language it's just a matter of familiarity.
HTML was designed for humans to read and write long before Claude or compiling everything from typescript or whatever, when websites were all written by hand. In text editors. Even if you were using PHP and templates or CGI you wrote that shit by hand, which meant you had to be able to read it and understand it. Even if you were using Dreamweaver, you had to know how to read and write HTML at some point. WYSIWYG only gets you so far.
Is HTML more difficult to read than Markdown? Sure. It is impossible? Not even remotely. Teenagers did it putting together their Geocities websites.
You can be as snarky as you like, but facts are facts.
I don't think they were appreciating that HTML could be read unrendered. I think they meant that it was up to the browser to render HTML with sensible but unspecified or otherwise user-specified styling (the browser is supposed to be a "user agent", remember?) before web designers started aiming for pixel-perfect control through CSS.
> 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?
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.
I don't know YAML well enough, I never liked it. But if you want to write an halfway common marks compliant parser, then markdown is just nuts. It is just way too complicated for the simplicity it conveys. Look at lists, they can be freely nested, and contain all(?) other block elements. That is extreme overkill. If you need that much flexibility, then any wannabe "simple" markup is just the wrong choice.
Exactly this. At this point I read markdown as if it were rendered, with the exception of tables which are a mess visually in plain text.
But everything else, headings and bold and italics and lists, I’m honestly not sure I can tell the difference. It’s like watching movies with subtitles when you’re sufficiently experienced: your brain just fills in the gaps and you don’t even notice
YAML is actually very complex, to the point that basically nobody implements the full YAML 1.2 spec from 2009 (https://matrix.yaml.info/), while 1.1 contains footguns like `country: fr` and `country: no` parsing issues.
Though I agree simple usage is good enough in practice, there are a lot of edge cases that can cause subtle bugs.
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.
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.
I recently tried to create markdown like parser, I had to refer a lot to common marks. What I saw was madness. I never knew from casual use, that markdown is so complex. There is literally zero thought about parsing, it forces natural looking text into a format that can be structured into actual markup, but it has so many pitfalls and edge cases that it just feels wrong.
Each time I've looked up another markdown parser I was stunned how overegineered they are. If you need an AST to parse something seemingly simple like markdown, then something went wrong. Probably every coreutil is smaller then the average markdown parser. Why?
I did a book in rst and liked that it had cool admonition, import, glossary, and index features that made it better than markdown for me. Still hate the heading conventions.
I have a custom pandoc filter for callouts and index entries. None of the simple lightweight markup languages has complete support for writing a real book. Writing custom rst code is a pain (and no one else in the world uses it). (I say this as a 25-year Python veteran and as a docutils committer!)
Looks like a duck, quacks like a duck… but is semantically different, except for when most people interact with them.
My point wasn’t that they are identically - my point is that 99% of the time they achieve the same effect. Or they would be if I had swapped the <p> tag for a <span> tag.
https://djot.net/ seems to be very sane and still very similar to markdown. And after reading the CommonMark spec, I appreciate the saneness very much. CommonMark did a great job at describing all the rules and edge cases, but it clearly shows how messy markdown is.
I like most of Djot’s simplifications, but its requirement to write nested lists with blank lines between every change in indentation is a dealbreaker for me:
- Djot requires
- writing nested lists
- with blank lines in between
- successive list items at the same level
- can skip the blank line
- but not this list item
Yes, supporting indented list items without blank lines in between would make Djot’s parser more complicated. But I write nested lists all the time in my notes, and extra blank lines would distract from the content. For me, it’s not worth it to make my raw text ugly just to make the file easier to parse.
Djot could have avoided the blank line requirement by not trying to join hard-wrapped lines back into one paragraph / list item. That would work for me because I only soft wrap my text. Djot’s choice to support hard wrapping caused all of its users (including those who hard wrap) to have worse nested list syntax.
Djot is great so far, and I'm eager to switch to it from Pandoc Markdown since editor support for Pandoc Markdown is lacking.
Looking at the repo's issues, I'm a bit concerned that it's already fragmented since some enthusiasts have implemented features far beyond, or against, Djot's spec. People seem impatient for v1.0...
too little (preserves weird whitespace semantics requiring extra newlines, non-obvious _under_ for /italics/ markers, confusing multitude of link syntax, too many and too few list markers (why isn't • allowed?) too late? But would've been a great start instead of the aborted markdown attempt back then...
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>.
I like HTML and will use it for my own projects, but I cannot send pure HTML to someone who's not a into tech, so to speak, and expect them to actually read it. It doesn't take much CSS to make a readable web page, and I actually kind of like the barebones no-CSS HTML style, but for many others, that style reads as 'this page is broken'. I guess I can write all my styles inline or in the header, but that's a big ask when I never do that normally.
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).
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.
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.
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.
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.
>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.
Markdown largely serves the same role as things like vocal emphasis and intonation in speech. Here are some example sentences that have slightly different semantics communicated by markdown differences.
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:
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.”
> how HTML is only a markup language and not a programming language.
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.
"No, I was and remain against establishing extensions. Markdown has thrived because it’s a small idea, not a spec, and thus embraces many variants to suit particularly needs and contexts." https://x.com/gruber/status/1495119598148009991
This post reminded me of Bjarne Stroustrup's famous quote "There are only two kinds of programming languages: those people complain about and those nobody uses".
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").
You kind of do need Emacs though, as far as I know it is the only existing fully compatible implementation. As soon as the file is outside that environment, all bets are off. I tried using org-mode instead of Markdown once, not for long.
I'm in no way saying that markdown is perfect but it is much better than anything else I've used. It's got me through both a bachelors and masters.
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.
I always advocate for XML. While Markdown is like "a car in any color as long as it's black", XML is a) exactly what you need and b) as precise as you need it, and also c) not more precise than necessary.
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
Here's well-formed XML:
<text>
abc def ghi
</text>
That's all, save for two extra newlines. Plain text is the best thing when you write to think. But once you're done with thinking you might want to add a date mark, a tag, or another more structured content. With XML you can have both.
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`
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.
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
Exactly, I am very bearish about the prospects of any new languages post-LLM era gaining traction. Unless they are highly specialized or somehow better for LLMs.
i use markdown because it's inherently limited to styling that is easy to represent. it's a good way to communicate the limitations of text-based content submission form.
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.
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 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.
Markdown is _fine_? I certainly have my own issues with it; most of which can be mitigated by adhering to a style guide (e.g. only use one syntax for <em> and <strong> as well as <ul> and headers). I'm not sure why we need both asterisks and underscores to represent the __same semantics__ – to me this feels wasteful of precious ASCII. Perhaps it was to allow the writer to express their preference while providing a shared and consistent meaning (same with the other duplicate forms). In that sense it seems to have done an <del>excellent</del> okay job at affirming common ground. I'm not sure. From what I can tell, the original author has been reluctant to do the work here and has left this for others (i.e. CommonMark).
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).
I used to write raw HTML for my blog because I needed more formatting and structural power than what Markdown could provide for Jekyll. Then I built my own little blog generator that uses Markdown and which pre-substitutes my own hacky syntax elements for the extras I need.
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'm mostly fine with markdown, but I just wanted to comment, this example in the post
# 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>
Might not do you think it does. markdown does not include html parser per-se. It allowes HTML but has rules like
I am a <span style="color:green">super *grinch* yall</span>
will generate
<p>I am a <span style="color:green">super <b>grinch</b> yall</span></p
It doesn't see the span element and turn off parsing.
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.
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.
People use Markdown because it's expected, it's probably already a part of whatever library or framework they're already using, and there is no well supported or popular alternative.
I mean I started using it because I don't like using Word or Google Docs and wanted a more portable data format since I was going between Mac and Linux.
There are bunch of reasons why it came to dominate.
As somebody who is currently trying to use structured markdown in obsidian for knowledge management and finding it a bit challenging, I agree with the author that markdown is not the ideal language for what he and I are trying to do with it, and that we'd probably be better served by something else. But I'm not necessarily convinced such a language would find a lot of adoption, because I suspect that most people using markdown aren't doing what we're doing, and are quite well served by what's there. Actually, I'm one of those people about 90% of the time -- I have never thought about any of this stuff while writing a readme or a forum post, and that's what MD is actually for. How many users are out there clamoring for a completely unambiguous markup language optimized for parsing and extensibility?
As always, honorable mention to Typst [0] as a good balance between the readability & simplicity of Markdown with the flexibility & composability of LaTeX. I think and hoping that Typst will be the future, but for now I'm happy with Markdown.
Because we need to get information down quickly, but still have the option of parsing to a presentable format. Markdown is not perfect, but it's far better for the efficient capture of information or document authoring. I recently built AS Notes for VS Code (https://www.asnotes.io). It's markdown based, with wikilinks, mermaid diagrams, with the ability to publish to github pages etc. There is no way I'm writing my day to day notes with HTML and anchor tags without it being a huge distraction. And HTML is so much harder to read in longform if you need to come back end edit your writing. Markdown is for humans where HTML was designed to be simple, but is ultimately for parsers.
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.
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.
As someone who has written his PhD thesis in LaTeX, I wish Markdown, or more specifically Quarto, would have existed at that time. Spent too mich time setting up basic stuff that is now just 2 pre-defines styles away.
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 wrote my MA thesis in Markdown. The good thing about Markdown is that it forced you to just write and it had enough markup to be useful, but not so much thst you depend time procrastinating getting the output perfect (like LaTeX).
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.
HTML tags contain letters. Naturel Language words also contain letters. But markdown tags don't contain letters, and when reading, tags and words don't get mixed up.
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 way to do it and no embedded html we would be better off.
Why does flexible input bother you? There’s more than one way to do it is more than motto, it’s how all human languages work. Or does speaking English really bother you?
Because to me it's good enough, the syntax is simple and it's totally readable in plaintext, which makes it the ultimate format against vendor lock-in.
Markdown is the Python of documents. As technology, and consequently technical writing increase in complexity, any reduction in barrier to access becomes increasingly necessary. The opposite of using markdown and python leads to bike shedding.
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've actually tried some other markup languages like asciidoc, but went back to markdown since I found it's hard to cooperate with others with another markup language like asciidoc and it's harder to find something else than asciidoctor to render it. I could write blog posts in asciidoc but in order to make it parse-able for my SSG I'd still have to compile it to markdown.
I've thought about this a bit too, and instead of a straight escape hatch to html when any special formatting is necessary, it might make sense to bind css to particular elements like so:
##[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.
Not sure I caught the author’s use case, but Markdown shines in the document space when you’re the author and user. It’s efficient and sufficient—lowest common denominator of ease of writing and formatting basic text.
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.
This article is legit, but markdown is good enough to me.
Actually, I was using reStructuredText which has a better specification for writing. I switched back to Markdown because its syntax is easier to remember and fulfill most of my needs.
The thing I needed was comments for adding folding marks in vim. I use inline <!-- --> to do so and that's OK.
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.
For me, one major issue with md is that it does not support indentation that could be used for collapsing sections.
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.
If HTML were for machines it would be a binary format. It's text so it's meant for humans to read and write, and humans did both for years without it being a problem.
for me as a user, I like it it's simple to use, I know for the developers it's probably very hard to parse and what not, but for most people the experience matters most.
Also markdown you can use it without any parser just a text editor.
> The real issue is that to ship a Markdown parser you also need a to ship a friendly HTML parser.
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?
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 was lamenting the other day that we used to have SGML SHORTREF, then XML came along because supposedly SGML is just too hard to parse. But XML is for computers, not for humans. So then we got Markdown, which is worse than where we started from.
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.
Markdown is much easier to write quickly than HTML. Situations where I write Markdown quickly include writing messages on Slack and for AI chatbots. I wouldn't want to use HTML in either of those cases.
If we're going to define a programming language as one that is Turing complete, it's important (in a kind of pedantic sense) to note that that includes HTML (with CSS), which can be used to encode a Rule 110 automaton, and excludes C, whose standard imposes an (implementation-defined) upper bound on accessible memory, meaning it can never, even in principle†, similarly a Turing machine, which has infinite storage. This is probably not what was intended :)
† 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.
Bonus points for MD being readable even when it's not parsed. More bonus points for Sublime Text displaying it in plain text and still looking great. Good enough++
i like html fine, but org-mode, now you're talkin'. it's like the nasa voyager equivalent of text markup. just needs to be rescued from being held hostage in emacs.
The format itself can be easily implemented. There's not much to it and it actually has features that's undefined in markdown like frontmatter and references. The things that are missing can be replicated outside of emacs (babel, agenda, task management, timetracking, export,...), it's just that no one is doing it.
Is that an issue? There’s only one reasonable implementation of Typst too, and both AsciiDoc and Typst are fully supported by Pandoc, which supports a wide selection of writers (output formats).
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.
I'll give them credit for not just being another "markdown sucks, let's switch to RST" slop article. Even more so as they say they don't have a solution - because a solution would be like asking for 3/3 on "cheap, reliable, fast" or whatever your favorite version of "engineers are paid to make compromises" is.
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.
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.
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.
...and? What a weird article. Of course two different pieces source code can produce identical output. Every single mainstream languages are like that too.
This also misses the point: multiple syntax markers for the same thing is the opposite of simplicity (though that's not the reason why Markdown will fail)
You have the wrong end of the stick. The point is simplicity for the user, not the developer of the parser. And for users, having two ways to get the same thing adds no complexity- they just pick one and use it.
I don't, it's not simple for the user - you can't just pick one and forget the other or you'll end you wondering why your use of the other for regular text.l suddenly broke your whole paragraph because you didn't close a mark you never use.
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.
Why the heck would you use the phrase "Why the heck" in any circumstance other than to avoid censorship/algorithmic penality on a social media platform?
Well, one good reason is that a person who generally doesn't "swear" can then choose to use them very effectively when the situation warrants. If you always go to strongest words when mild ones will do, you're out of things to say when you need to make a stronger/more forceful point.
Perhaps instead of worrying about someone else's free choice to use certain words iver others, it would be wise of you to ask: why would you complain about forced speech patterns in the context of censorship but then be angry when someone uses their free speech differently then you would use it?
Because being consistent helps prevent mistakes in circumstances where use of regular curse words is contraindicated. And why the fork should you care?
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.
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.
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.
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:
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.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.
What ambiguities are there with bold?
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.
Disappearing asterisks is just terrible UX. It should turn bold but keep the asterisk displayed so you can still edit as normal.
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.
This is just a personal preference. I strongly prefer to see the markup as I write it. I can't stand disappearing characters.
Do you enable visibility of tab and space?
I do!
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.
Ha, I remember this religious debate all the way back in the days of text-mode word processing in the 80s on CP/M and PC. I was indoctrinated in the WordStar camp where style controls were visible in the editor between actual text characters, so you could move the cursor between them and easily decide to insert text inside or outside the styled region. This will forever seem a more coherent editing UI to me.
This might be why I also liked LaTeX. The markup itself is semantic and meant to help me understand what I am editing. It isn't just some keyboard-shortcut to inject a styling command. It is part of the document structure.
> easily decide to insert text inside or outside the styled region.
Only for the 3 primitive styles that were supported? 3 table cells of RedBold GreenLowerCaps BlueUnderlineItalic isn't easy anymore
But also - there wasn't a single app in the 80s with a different easy approach, right? So removing noise had a downside.
> styling command. It is part of the document structure.
Not for the most used markdown markers, where styling = semantic.
Heh, I'm not even sure WordStart other styles at that level. Changing the color back then would mean having the print job pause and the screen prompt you to change ink ribbon and press a key to continue. I can't remember if it could also prompt to change the daisy wheel, or whether font was a global property of the document. The daisy wheels did have a slant/italic set, so it could select those alternate glyphs on the fly from the same wheel. Bold and underline were done by composition, using overstrike, rather than separate glyphs.
But yeah, this tension you are describing is also where other concepts like "paragraph styles" bothered me in later editors. I think I want/expect "span styles" so it is always a container of characters with a semantic label, which I could then adjust later in the definitions.
Decades later, it still repulses me how the paragraph styles devolve into a bunch of undisciplined characters with custom styling when I have to work on shared documents. At some point, the only sane recourse is to strip all custom styling and then go back and selectively apply things like emphasis again, hoping you didn't miss any.
Same, same.
And... I preferred WordPerfect's separate "reveal codes" pane, which reduced the opportunity for ambiguity. WP 5.1 has never been equalled as a general-purpose word processor.
For the love of god, yes. Slack is the worst for this with backticks. Editing the start/end points is a giant pain.
What ought, amn't
Asterisk * has other uses too. Even more common than footnotes would be x*y=42 X=42/y
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...
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).
I agree that file paths should be in `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.
Try finding the backtick on a mobile phone keyboard in less than a minute, tho. So very annoying. (SwiftKey I'm look at you, bud.)
A path should be written `/root`...
Yeah, *asterisks* for italic has always felt wrong to me. I can understand underscores if slashes cause confusion with file paths.
*bold* and _italic_ would have been better.
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.
> 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. (-;
Like Typst does ;-)
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.
I have long used underscores for _emphasis_, but I never made the connection that it was meant to resemble an underline until now.
I have historically used asterisks for emphasis and slashes for the use/mention distinction.
Org-mode FTW
But Usenet style didn't have a trendy name, an 'inventor' or Github stars. So it didn't exist.
GitHub stars weren't a thing when Markdown was roughly codified. Was GitHub even around then?
Git wasn't even around.
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
Somehow basically only Discord gets it almost perfectly right though.
Which is very recent. Discord only added full markdown support a couple years ago.
Even when they only had a subset, that subset was correct
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?
Commommark is the best, then looking at the most commonly implemented extensions:
- Superscript with hat symbol (^)
- Hidden content (also known as spoiler tags, content warnings, click-to-reveal, etc...) with two pipe symbols (||) at start and end of hidden content. Interact with the content to show the content inside.
- Table syntax to show tabular data and align content with pipe, hyphen, colon symbols
---
After that, I'd look at the extensions that are only useful for the use-case you're targeting:
- Subscripting with tilde symbol (~)
- IDs, Classes and Attributes
- Task lists
- Sections / Containers
- Language labels for code blocks
- Math Support (mathml, latex, katex, etc...)
- Table of Contents / Footnotes
- Definition lists
- etc...
Just search "Markdown grammar"
Check out commonmark
> worse is better
It's a very old idea
https://en.wikipedia.org/wiki/Monetae_cudendae_ratioI'm not quite sure I understand the connection.
I see one, but then maybe I am just seeing things.
The wikipedia page about "worse is better" re: software linked above states:
Copernicus' idea about money has a similar structure - "better" money such as precious metals, art, etc. is being hoarded due to its perceived desirability, leading to more "worse" money in circulation. As a result, the "worse" money is actually "better" at fulfilling its role as currency (bc it's not hoarded). So there is also a point where "worse" becomes "better".Bad money drives out good money only if there is a legal tender law such that both have to be accepted for the same nominal value. In this case, good money is hoarded because it cannot be traded for its true value.
The solution is sufficiently perfected with markdown. Just like new revolutionary technologies doesn't replace wheel technology.
To actually manage notes and information in plain text I like org-mode markup. For just writing, markdown is good enough.
This is exactly why ReStructured Text is better/worse.
> 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.
The problem is that proposed Markdown alternatives are targeting a vanishingly small niche of scenarios: for almost all simple writing Markdown is good enough, and for anything too complicated for Markdown, people will use HTML or LaTeX/Typst. The in-betweens just don't seem to have a reason to exist.
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.
Why do you think that is?
Because I think, that there are other formats, whose formatting rules are more intuitive than Markdown's formatting rules. For example:
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.
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.
> 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.
> the only thing I regularly mix up is the syntax for links. I frequently reverse the [] and ()
I remember it as passing parameters to a function that requires an URL as an argument. Maybe it's not the most straightforward way, but it works for me
I used to flip the link syntax all the time too. What finally helped me to remember it was noticing how I write links in plaintext emails.
In email, I naturally write things like "...on the example website (www.example.com)..."
Markdown keeps those () in the same place, and just adds the [] so you can delimit the visible text: "...on the [example website](www.example.com)..."
I remember it like this: If you squint the brackets around the link text make a rectangle and look almost like a button you can press. [Press here](to.go.there)
> 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.
[flagged]
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
I suggest trying Obsidian for WYSIWYG markdown editing. It beats heck out of typing it raw and eliminates that cognitive load.
I don’t like WYSIWYG editing, as it makes the formatting invisible.
Then you might like Obsidian. When the cursor is in some bit of formatted text, it displays all of the characters. When the cursor is elsewhere, it just shows the formatted text.
In the worst case, the barrier to entry and exit are pretty low.
Obsidian has 2 main advantages to me.
First you can switch from WYSIWYG to text editor instantly.
Then you have an outline where you can manipulate your “markdown blocks” [i.e title and its content] by drag n drop. Or extract a “markdown block” as a new note, and leave a reference where it originally was extracted from.
And then [the killing feature], it displays the content of a link, web link or internal link, as a [kind of] iframe, if you prepend a ! to the link.
[flagged]
[dead]
[flagged]
> We want to encourage people to produce written output with minimal friction.
What's wrong with .txt ?
We also want standard structure so the more than the content is understood.
> 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: <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.
Worse is better doesn’t mean worst is best either.
Markdown is pretty far from the worst. It's decent and unobtrusive. Worst would be something like Troff or jira formatting. Midtier would be RST.
Ugh, troff. It's mind-boggling that the closest way to have an actual (hyper)link in a manpage is to use your pager's "search for text" function. No, "JuSt usE gNu iNfO it'S beTtER" is not an answer either.
groff can produce output with links in it, and does by default in HTML mode! The GNU version of the Unix man page macro set has .UR and .UE for “URI start” and “URI end”. (I don't know whether these were present earlier in the lineage or whether they were introduced by GNU.) Also, the lowdown Markdown converter when in man output mode will output those for links. For fun, try:
There's also support for OSC 8 terminal hyperlink sequences throughout most of the groff toolchain: grotty(1) supports outputting them, and less(1) supports passing them through, including ^O^P and ^O^N gestures for moving between them. But man(7) says they're not enabled for grotty output by default. “Options” describes the rationale in its item for “-rU1”: “grohtml enables them by default; grotty does not, pending more widespread pager support for OSC 8 escape sequences.”So if I set MANROFFOPT=-rU1 in the environment, I can get clickable links in man… if the man page author included them that way in the first place. I'm not sure how common that is in the wild, but grepping the ones on my system, I find firejail(1) contains a link to a GitHub issue embedded in that way, and it does indeed work when I hit ^O^N to seek to it and then C-mouse1—though the mouse gesture I have Alacritty using for links doesn't seem to work through tmux (there might be a way involving twiddling the tmux terminal-features setting, but I ran out of steam before trying this), and I didn't see a great way to get either grotty or Alacritty to style them on display instead of having them blend into the surrounding text, so it's still kind of scuffed in practice. (Though I bet the cool kids have moved on from Alacritty by now?) less displays the link target in the status line when you use the navigation commands, so it's not inaccessible, but for opening selected links directly from less with the ^O^O gesture rather than leaning on terminal support, it looks like you need to explicitly set the LESS_OSC8_ANY and/or LESS_OSC8_‹scheme› environment variable to a shell command that outputs a shell command pattern to substitute the link into; if I set LESS_OSC8_ANY='echo xdg-open %o' then it passes it to my Firefox. I wonder if they'd take a patch (or if any existing distributions patch it) to use that as the default?
That was a fun little rabbit hole to go down, thank you.
I mostly care about links inside the man page (look at man bash — there are tons of internal references like "described below under CONDITIONAL EXPRESSIONS" or "section SHELL BUILTIN COMMANDS below", or operators being underlined and looking like hyperlinks, which you can't easily interact with to just go to where they refer to. You have to employ full-text search, but it also turns up the references themselves, and good luck searching for the place where e.g. command "." is described) and links to other man pages, not the normal Internet URLs being clickable (those things are trivially copy-pastable into a browser next window).
Ah! Yeah, that makes more sense—I misinterpreted you at first since I don't normally think of “internal link” as the default exemplar of “hyperlink”. And yeah, I don't see good target markup for that. Stuff like starting your search regexp with “^ +” helps but is still janky. I'd tend to categorize this mostly as “man pages aren't meant to be long treatments of more complex software”, of course? Some large packages do something which I kind-of like but which I'm not sure would work well if everyone did it (mainly due to ergonomy around disambiguation) where they split up a bunch of their documentation into shorter pages with the origin as part of the section when making it accessible through man: pcap_init(3pcap) from libpcap, Bigarray(3o) from OCaml. Shells, as you notice, get hit by this really hard; Zsh tries to do some splitting in the man version of its docs, but it's really not enough, like I'd want to see fc(1zsh) (and then fc(1bash), etc.) but instead it's all in zshbuiltins. (Eventually I facepalmed when I realized an Info version was available and switched to that. The way I found this out was actually by eyeing the Zsh source tree and noticing that the documentation files were written in Yodl, which I'd never heard of, and then noticing that the schema they were using looked a lot like Info…)
… wow, hang on, I just checked for Bash, and it has an Info file but it says it's just an intro and the manual page is the definitive version‽ That's… hah. There must be some timeline jank around that; ambiguous NIH vibes around Info aside, I wouldn't have expected it from an actual GNU program! Did Bash show up before Info existed?
If the manpage is written with the 4.4BSD -mdoc semantic markup macros then it can contain hyperlinks like
And the mandoc tools will include them in their really nice HTML output. It will also hyperlink .Xr cross-references to other man pages.https://mandoc.bsd.lv/
troff was originally used to format printed output, where hyperlinks would not make any sense.
But you still have to use it for man pages, even though nobody prints man pages anymore.
A man page is simply a formatted text file. The display of it is performed by the program defined in the MANPAGER or PAGER environment variable, or by a default program, usually less(1). That is the program that would be responsible for navigating any hyperlinks, and the format of references to other pages is already pretty easy to pick out so developing a man page reader that could follow references to other man pages would not be particularly difficult. Many web-based and GUI man page viewers do this. Example: https://github.com/zigalenarcic/mangl
> The display of [a man page] is performed by the program defined in the MANPAGER or PAGER environment variable, or by a default program, usually less(1).
A man page source isn't a binary format, so your statement that they're "plain text" is technically correct. (The same is also true of TeX and LaTeX files, and even PostScript if you want to stretch the definition of "plain text" until it snaps.) But the renderer is groff or (legacy) troff with the `an` macro set. less(1) (or, originally, more(1)) is just the pager that consumed the former's output (if the output format is ASCII, which is one of many) and handled paging on the terminal for the convenience of the user.
In my old Sun workstation (and even early Linux desktop) days, I rarely used man(1) in the terminal because 1/terminals were usually too small and weren't usefully resizable like they are today, and 2/unadorned monospaced fonts don't look nearly as nice as properly typeset pages do. (Color terminals were just coming on the horizon, and text could only be emboldened, not italicized.) Instead, I typically used xman whenever I could. The best way I can describe xman is as if you were rendering man pages into PDFs and viewing them in Preview on the Mac. Man pages were much more comfortable to read that way.
I came here to say this.
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.
> Markdown in an of itself isn’t powerful enough to satisfy the simple monkey brained developer like me who is only satisfied when the site looks good enough™.
Well, indeed, Markdown is an inadequate tool for that. Let the author use more powerful tools, be it HTML, LaTeX, SVG, etc.
Markdown is fine for its intended purpose: very light formatting, very simple header structure. If I were not that lazy, i would come up with something opposite to CommonMark, some MarkDownDown, that does away with alternative ways to format things, most escaping, and most advanced syntax. The goal would be to have an easy-to-implement, unambiguous, safe and simple subset good for use anywhere. Intentionally limited.
(For daily use I prefer Org Mode, due to its vastly superior support in my preferred editor.)
> If I were not that lazy, i would come up with something opposite to CommonMark, some MarkDownDown, that does away with alternative ways to format things, most escaping, and most advanced syntax.
https://djot.net/
It makes quite a few right calls, but still tries to not be a strict subset of Markdown, requiring e.g. a different editing mode.
Being a strict subset of Markdown would make it itpossible to achieve simplicity. From the rationale:
> Rules for emphasis should be simpler. The fact that doubled characters are used for strong emphasis in commonmark leads to many potential ambiguities, which are resolved by a daunting list of 17 rules. It is hard to form a good mental model of these rules. Most of the time they interpret things the way a human would most naturally interpret them---but not always.
Indeed. I'd go with dead simple rules. The below assumes whitespace or punctuation on either side:
Any other combination does not parse as formatting, and is considered literal text. Yes, this prevents marginally useful cases like putting an italic fragment in the middle of the word. I'd be fine with that.If I’m understanding correctly, your rules are based on word boundaries? How do you define a word boundary?
Word boundaries are a complex thing, especially in languages like Chinese or Japanese. Whitespace and punctuation are much less complicated, even if we take the full Unicode case. So the boundary where formatting is considered is between (whitespace | punctuation) and anything else.
So now you have to distribute a character class table in every implementation of your language, which is precisely what the author of Djot wanted to avoid.
So y = x * 7 + b * c will be bolded in the middle?
No
If only you could just put html tags in the markdown whenever you need a bit of extra expressivity!
html comes with baggage.
---
If you're writing a parser, you might have text nodes, and bold/italics nodes which can contain each-other and text nodes. Example:
- bold node
-- italics node
--- text node
But if you add html support, you're going to run into strings like this:
<b><i>text content</b></i>
How easy is it for you to represent that?
What about:
not bold or italic <b>bold but not italic <i> bold and italic </b> italic but not bold </i> not bold or italic
What about:
</b> not bold <b> bold <b> bold again? </b> is this still bold? </b> what about now? <b>
I use a horrific mix of:
• Markdown (most of my notes these days, supplanting my previous use of plaintext.)
• Single-file HTML (when my use case for fancy documents exceeds markdown's limits. While you can embed HTML into markdown, renderers vary in what they allow or sanitize, and vary in how you can (ab)use style tags. I've even taken to looking up CSS rules for printed documents, since my intended target is often pdfs or actual print at that point. Occasionally, JavaScript!)
• Google docs (Android phone nonsense!)
I'd mutter something about "using the right tool for the right job", but that's probably giving myself too much credit.
Exactly. I write my own notes in markdown, it works with or without a viewer app. I am not even sure if there is a better alternative. This format is good enough for most of the casual and semi serious use cases
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.
There are other solutions which are as easy to read/write (if not more) and which are defined much better… Asciidoc comes to mind.
"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.
Have you tried Asciidoc though? It is, IMHO, much clearer than markdown (YMMV, obviously), and exactly the same pros you gave of markdown can be said of Asciidoc.
Bonus: It starts simple but can be used to do whole books if needed.
My experience is that Asciidoc very quickly gets into advanced syntax.
If you introduce something with advanced functionality onto a team, soon enough someone's going to use pieces that others don't fully understand later.
Now everyone touching the document has to understand includes and document metadata and whatever else someone added. Suddenly you have includes and cross-references and what used to be a document where you could read the raw non-rendered form linearly top to bottom is a confusing mess unless you render it. Markdown is almost always just as legible raw as rendered.
It's great apart from the nested list syntax. It's quite noisy. I'd prefer if it supported indentation.
HTML is valid markdown. So I'm not sure how you make oppose markdown and XML. XML is basically a subset of markdown.
Markdown basically adds a whole layer of complexity upon HTML.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.
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].
"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.
Yes, it's obviously "against common usage" given HTML support exists specifically for less common features that Markdown does not support. Like tables, which are supported by some implementations but not all, and iirc not even all Markdown variants that support tables use the same syntax for them. The only way to be 100% sure is to use HTML. Of course you wouldn't do that if you just have the file on Github, but in general HTML is supported in Markdown for a reason.
But it is a bad reason that goes against the reasons for the creation of Markdown.
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.
Unfortunately, the plain text does not look good, and does not offer good control of the typesetting. At least, nearly all markdown I see is almost unreadable in its “raw” state. I’d much rather read manually formatted, monospaced, text. That way, you can use asterisks as bullets, as footnote markers and as emphasis markers all at the same time, and anyone who is familiar with normal typographic conventions will understand what is what.
+1
Not too long ago, I used to think that Markdown was the Bee‘s knees. But having been forced to write some documentation in plaintext, I learned that plaintext is significantly more readable than raw markdown.
I think one of Markdown‘s biggest sins is how it handles line breaks. Single line breaks being discarded in the output guarantees that your nicely formatted text will look worse when rendered. I understand there are use cases for this. But this and the „add a trailing space“ workaround are particularly terrible for code documentation.
> I think one of Markdown‘s biggest sins is how it handles line breaks. Single line breaks being discarded in the output guarantees that your nicely formatted text will look worse when rendered.
My experience has been the complete opposite. Markdown parsers that don’t discard single linebreaks (e.g. GitHub-flavored markdown) turn my nicely formatted text into a ragged mess of partially-filled lines. Or for narrow display widths, an alternating series of long and short lines.
Markdown parsers that correctly discard single linebreaks make sure that the source text (reflowed to fit a max number of characters per line) and the rendered text (reflowed to fit the display width per line) both look reasonable.
Your text isn’t nicely formatted, which is the point. Discarding line breaks is a terrible idea inherited in general.
> Why would you target something as shitty as markdown if you have a specialized editor?
Your at-rest format allows you to use any tool to edit it. The specialized editor becomes a preferred tool, but not the only tool nor the most important one. Markdown and it's ecosystem came before the editor.
> Why would you target something as shitty as markdown if you have a specialized editor?
Because Markdown is the standard text formatting language. It’s the format everybody works in.
> But really, if you at all care about the semantics of your document don't write it in markdown
But it’s the standard text formatting language everybody uses.
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.
> 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.
IMHO still is. Just don't add any JS or CSS
Problem with that is that the default browser styling is extremely ugly and the ability for custom style sheets was removed from the browser GUI many years ago. ReaderMode and Addons can help, but as long as the default is essentially broken and unsupported that whole approach remains a dead end.
On top of that come issues like the lack of pagination support in browsers, which make long document impossible to read and practically require to add custom UI inside the website itself.
ePub works much better, with readers giving control over line spacing, font size, pagination and proper markup for TOC and other metadata, but despite ePub being based on xHTML, browsers have ignored it (only old Edge supported it for a little while).
No? That has always been a uniquely unreadable language with weird, arbitrary choices.
And on no planet is it human readable without parsing.
That is an unjustified over-generalisation.
HTML markup is pretty readable (except when it becomes soup) and I read and write raw HTML documents all the time. I like it better than markdown.
It's even more readable in a code editor that distiguishes tags from content.
Ask your grandmother to do the same.
On this planet, humans have read HTML without parsing for years. People building their first websites without any significant technical knowledge stole HTML by reading the source of other sites and edited it by hand.
Oh, please. Don't insult everyone here by pretending you actually believe HTML is a human readable format like markdown. It was never designed for that and has never claimed that.
What a rediculous thing to even say.
It is. Humans do read it, and have read it. Like any language it's just a matter of familiarity.
HTML was designed for humans to read and write long before Claude or compiling everything from typescript or whatever, when websites were all written by hand. In text editors. Even if you were using PHP and templates or CGI you wrote that shit by hand, which meant you had to be able to read it and understand it. Even if you were using Dreamweaver, you had to know how to read and write HTML at some point. WYSIWYG only gets you so far.
Is HTML more difficult to read than Markdown? Sure. It is impossible? Not even remotely. Teenagers did it putting together their Geocities websites.
You can be as snarky as you like, but facts are facts.
I'm confused. Are you saying you cannot read an HTML file?
You must be kidding. If you can read BBCode you can read HTML.
I don't think they were appreciating that HTML could be read unrendered. I think they meant that it was up to the browser to render HTML with sensible but unspecified or otherwise user-specified styling (the browser is supposed to be a "user agent", remember?) before web designers started aiming for pixel-perfect control through CSS.
> 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?
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.
I don't know YAML well enough, I never liked it. But if you want to write an halfway common marks compliant parser, then markdown is just nuts. It is just way too complicated for the simplicity it conveys. Look at lists, they can be freely nested, and contain all(?) other block elements. That is extreme overkill. If you need that much flexibility, then any wannabe "simple" markup is just the wrong choice.
Exactly this. At this point I read markdown as if it were rendered, with the exception of tables which are a mess visually in plain text.
But everything else, headings and bold and italics and lists, I’m honestly not sure I can tell the difference. It’s like watching movies with subtitles when you’re sufficiently experienced: your brain just fills in the gaps and you don’t even notice
YAML is actually very complex, to the point that basically nobody implements the full YAML 1.2 spec from 2009 (https://matrix.yaml.info/), while 1.1 contains footguns like `country: fr` and `country: no` parsing issues.
Though I agree simple usage is good enough in practice, there are a lot of edge cases that can cause subtle bugs.
One of markdown's greatest assets is that it's basically plaintext. Can't render it to HTML, it's still very readable.
This blog post makes no sense to me.
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.
A few things here.
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.
I recently tried to create markdown like parser, I had to refer a lot to common marks. What I saw was madness. I never knew from casual use, that markdown is so complex. There is literally zero thought about parsing, it forces natural looking text into a format that can be structured into actual markup, but it has so many pitfalls and edge cases that it just feels wrong. Each time I've looked up another markdown parser I was stunned how overegineered they are. If you need an AST to parse something seemingly simple like markdown, then something went wrong. Probably every coreutil is smaller then the average markdown parser. Why?
> If you need an AST to parse something seemingly simple like markdown, then something went wrong.
This may surprise you, but that is very common in programming languages.
Doesn't surprise me at all.
Because the size of the optional parser for Markdown is irrelevant to the purpose of Markdown.
Because Markdown is made for humans, not for machines.
I've written over a dozen books.
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.)
I did a book in rst and liked that it had cool admonition, import, glossary, and index features that made it better than markdown for me. Still hate the heading conventions.
I have a custom pandoc filter for callouts and index entries. None of the simple lightweight markup languages has complete support for writing a real book. Writing custom rst code is a pain (and no one else in the world uses it). (I say this as a 25-year Python veteran and as a docutils committer!)
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.
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
Looks like a duck, quacks like a duck… but is semantically different, except for when most people interact with them.
My point wasn’t that they are identically - my point is that 99% of the time they achieve the same effect. Or they would be if I had swapped the <p> tag for a <span> tag.
<b> is now hilariously called the "bring attention to" element. I shit you not.
Apparently <i> is the "idiomatic text element".
Maybe we can bring back all the fun tags by making them acronyms? <marquee> can be "make a really quite entertaining effect".
That's the sort of "we started at the acronym and worked backwards" approach the Pentagon loves to do.
I've heard them called "backronyms", which I quite like.
https://djot.net/ seems to be very sane and still very similar to markdown. And after reading the CommonMark spec, I appreciate the saneness very much. CommonMark did a great job at describing all the rules and edge cases, but it clearly shows how messy markdown is.
What do you all think of Djot?
I like most of Djot’s simplifications, but its requirement to write nested lists with blank lines between every change in indentation is a dealbreaker for me:
Yes, supporting indented list items without blank lines in between would make Djot’s parser more complicated. But I write nested lists all the time in my notes, and extra blank lines would distract from the content. For me, it’s not worth it to make my raw text ugly just to make the file easier to parse.Djot could have avoided the blank line requirement by not trying to join hard-wrapped lines back into one paragraph / list item. That would work for me because I only soft wrap my text. Djot’s choice to support hard wrapping caused all of its users (including those who hard wrap) to have worse nested list syntax.
Djot is great so far, and I'm eager to switch to it from Pandoc Markdown since editor support for Pandoc Markdown is lacking.
Looking at the repo's issues, I'm a bit concerned that it's already fragmented since some enthusiasts have implemented features far beyond, or against, Djot's spec. People seem impatient for v1.0...
Do you see a way to help and improve the situation?
too little (preserves weird whitespace semantics requiring extra newlines, non-obvious _under_ for /italics/ markers, confusing multitude of link syntax, too many and too few list markers (why isn't • allowed?) too late? But would've been a great start instead of the aborted markdown attempt back then...
it's amazing
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 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>.
The solution is to use any other better-defined languages with a cheat sheet like [1].
If you’re used to CommonMark features, this is all you need.
[1]: https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-mar...
I like HTML and will use it for my own projects, but I cannot send pure HTML to someone who's not a into tech, so to speak, and expect them to actually read it. It doesn't take much CSS to make a readable web page, and I actually kind of like the barebones no-CSS HTML style, but for many others, that style reads as 'this page is broken'. I guess I can write all my styles inline or in the header, but that's a big ask when I never do that normally.
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).
Because, and I cannot stress this enough:
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.
Because it's Good Enough™ in many use-cases.
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.
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.
Agreed, if you need programmable content you can add some Javascript: https://www.markdownlang.com/advanced/javascript.html
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.
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.
>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.
Markdown largely serves the same role as things like vocal emphasis and intonation in speech. Here are some example sentences that have slightly different semantics communicated by markdown differences.
My cat is an idiot.
My cat is an idiot.
My cat is an idiot.
> These 2 produce IDENTICAL output.
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:
So in each doc you have to figure out the H1, H2, H3 formatting separately. E.g. in one doc it's: Whereas in another it might be: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.”
> how HTML is only a markup language and not a programming language.
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.
"No, I was and remain against establishing extensions. Markdown has thrived because it’s a small idea, not a spec, and thus embraces many variants to suit particularly needs and contexts." https://x.com/gruber/status/1495119598148009991
A thread on markdown creator's stance https://x.com/nalband/status/1625541479295860752
This post reminded me of Bjarne Stroustrup's famous quote "There are only two kinds of programming languages: those people complain about and those nobody uses".
All problems are solved once you embrace org-mode.
All you need is Emacs! Nothing more!
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").
> as that makes inclusion of one org document into another problematic and requires restructuring (somewhat workaroundable with "#+begin_src org").
Outside of Emacs, yes. Within Emacs, there's a keybinding to paste a tree and have it fit.
Objectively false. Please stop spreading misinformation.
I can think of a lot of potentially false things in the statement. The biggest falsehood likely is the perception that one needs Emacs. :-)
You kind of do need Emacs though, as far as I know it is the only existing fully compatible implementation. As soon as the file is outside that environment, all bets are off. I tried using org-mode instead of Markdown once, not for long.
In that case you can't write markdown without Obsidian.
I'm in no way saying that markdown is perfect but it is much better than anything else I've used. It's got me through both a bachelors and masters.
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/
I always advocate for XML. While Markdown is like "a car in any color as long as it's black", XML is a) exactly what you need and b) as precise as you need it, and also c) not more precise than necessary.
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:
Here's well-formed XML: That's all, save for two extra newlines. Plain text is the best thing when you write to think. But once you're done with thinking you might want to add a date mark, a tag, or another more structured content. With XML you can have both.> That's all, save for two extra newlines
And save for two extra words and 5 extra symbols, which in many cases (like config files) draw out the actual content
> XML is a) exactly what you need and b) as precise as you need it,
So how can I precisely get rid of that noise?
So format your post in Markdown and in XML and ask your grandmother to read them. (I assume she isn’t Grace Hopper.)
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`
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.
We use markdown because LLMs are great at it.
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
LLMs are great at it because it was already a widely adopted standard and fed to LLMs in training sets
Exactly, I am very bearish about the prospects of any new languages post-LLM era gaining traction. Unless they are highly specialized or somehow better for LLMs.
i use markdown because it's inherently limited to styling that is easy to represent. it's a good way to communicate the limitations of text-based content submission form.
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.
MD is not perfect, but it’s perfectly adequate.
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!
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.
Markdown is _fine_? I certainly have my own issues with it; most of which can be mitigated by adhering to a style guide (e.g. only use one syntax for <em> and <strong> as well as <ul> and headers). I'm not sure why we need both asterisks and underscores to represent the __same semantics__ – to me this feels wasteful of precious ASCII. Perhaps it was to allow the writer to express their preference while providing a shared and consistent meaning (same with the other duplicate forms). In that sense it seems to have done an <del>excellent</del> okay job at affirming common ground. I'm not sure. From what I can tell, the original author has been reluctant to do the work here and has left this for others (i.e. CommonMark).
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).
I used to write raw HTML for my blog because I needed more formatting and structural power than what Markdown could provide for Jekyll. Then I built my own little blog generator that uses Markdown and which pre-substitutes my own hacky syntax elements for the extras I need.
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'm mostly fine with markdown, but I just wanted to comment, this example in the post
Might not do you think it does. markdown does not include html parser per-se. It allowes HTML but has rules like will generate It doesn't see the span element and turn off parsing.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.
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.
People use Markdown because it's expected, it's probably already a part of whatever library or framework they're already using, and there is no well supported or popular alternative.
I mean I started using it because I don't like using Word or Google Docs and wanted a more portable data format since I was going between Mac and Linux.
There are bunch of reasons why it came to dominate.
fair enough, but what alternatives did you have?
Depending on the context: plaintext, HTML, BBCode, WYSIWYG editors
As somebody who is currently trying to use structured markdown in obsidian for knowledge management and finding it a bit challenging, I agree with the author that markdown is not the ideal language for what he and I are trying to do with it, and that we'd probably be better served by something else. But I'm not necessarily convinced such a language would find a lot of adoption, because I suspect that most people using markdown aren't doing what we're doing, and are quite well served by what's there. Actually, I'm one of those people about 90% of the time -- I have never thought about any of this stuff while writing a readme or a forum post, and that's what MD is actually for. How many users are out there clamoring for a completely unambiguous markup language optimized for parsing and extensibility?
I'd like to see a less flexible markdown standard. There's no reason to have 2 different ways of italics/bold etc. Pick one, reject other text.
Yes, there is. Different people have different preferences.
As always, honorable mention to Typst [0] as a good balance between the readability & simplicity of Markdown with the flexibility & composability of LaTeX. I think and hoping that Typst will be the future, but for now I'm happy with Markdown.
[0]: https://typst.app
From typst one cannot really create HTML, which makes typst unsuitable for online publishing.
https://typst.app/docs/web-app/export-and-preview/#html-prev...
Because we need to get information down quickly, but still have the option of parsing to a presentable format. Markdown is not perfect, but it's far better for the efficient capture of information or document authoring. I recently built AS Notes for VS Code (https://www.asnotes.io). It's markdown based, with wikilinks, mermaid diagrams, with the ability to publish to github pages etc. There is no way I'm writing my day to day notes with HTML and anchor tags without it being a huge distraction. And HTML is so much harder to read in longform if you need to come back end edit your writing. Markdown is for humans where HTML was designed to be simple, but is ultimately for parsers.
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.
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.
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.
i use it because it does what i want and is easy to use.
As someone who has written his PhD thesis in LaTeX, I wish Markdown, or more specifically Quarto, would have existed at that time. Spent too mich time setting up basic stuff that is now just 2 pre-defines styles away.
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 wrote my MA thesis in Markdown. The good thing about Markdown is that it forced you to just write and it had enough markup to be useful, but not so much thst you depend time procrastinating getting the output perfect (like LaTeX).
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.
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.
There are other options. AsciiDoc come to mind.
HTML tags contain letters. Naturel Language words also contain letters. But markdown tags don't contain letters, and when reading, tags and words don't get mixed up.
The issue is that simple.
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 way to do it and no embedded html we would be better off.
Why does flexible input bother you? There’s more than one way to do it is more than motto, it’s how all human languages work. Or does speaking English really bother you?
More complexity, no benefit. Human languages have lots of problems. I would simplify English if I knew how and had the power to make it so.
Because to me it's good enough, the syntax is simple and it's totally readable in plaintext, which makes it the ultimate format against vendor lock-in.
Markdown is the Python of documents. As technology, and consequently technical writing increase in complexity, any reduction in barrier to access becomes increasingly necessary. The opposite of using markdown and python leads to bike shedding.
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've actually tried some other markup languages like asciidoc, but went back to markdown since I found it's hard to cooperate with others with another markup language like asciidoc and it's harder to find something else than asciidoctor to render it. I could write blog posts in asciidoc but in order to make it parse-able for my SSG I'd still have to compile it to markdown.
I've thought about this a bit too, and instead of a straight escape hatch to html when any special formatting is necessary, it might make sense to bind css to particular elements like so:
##[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.
cf `# Heading 2 { attributes}` in pandoc:
https://pandoc.org/demo/example33/8.3-headings.html#extensio...
There are also attributes for image position/size, etc.
This is sweet!
As the comment count in this thread increases, the ratio responding to the headline alone, and nothing in the article, is approaching 1.0.
Not sure I caught the author’s use case, but Markdown shines in the document space when you’re the author and user. It’s efficient and sufficient—lowest common denominator of ease of writing and formatting basic text.
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.
This article is legit, but markdown is good enough to me. Actually, I was using reStructuredText which has a better specification for writing. I switched back to Markdown because its syntax is easier to remember and fulfill most of my needs. The thing I needed was comments for adding folding marks in vim. I use inline <!-- --> to do so and that's OK.
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.
For me, one major issue with md is that it does not support indentation that could be used for collapsing sections.
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 only changes I'd want to Markdown:
- Reverse the link syntax braces, so the URL is in [], and the link text is in ()
- Allow table cell content to have line continuations
Easy and "good enough" very often trumps complex and comprehensive. Markdown is great precisely because it can't do a lot of things.
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.
Aaron needs to hurry up and reincarnate already.
Aaron had very little to do with Markdown, other than reviewing the spec once at the end.
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.
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)
If HTML were for machines it would be a binary format. It's text so it's meant for humans to read and write, and humans did both for years without it being a problem.
Trained humans can read and write HTML. Untrained humans can read and then write Markdown.
for me as a user, I like it it's simple to use, I know for the developers it's probably very hard to parse and what not, but for most people the experience matters most. Also markdown you can use it without any parser just a text editor.
Markdown is essentially plain text with a couple extra features. I think Markdown’s basic appeal is that it’s plain text.
That applies to XML, AsciiDoc, LaTex, ReStructuredText, and all the others as well. Apparent simplicity seems to be the most appealing factor, IMHO.
Readability as well.
> The real issue is that to ship a Markdown parser you also need a to ship a friendly HTML parser.
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?
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 was lamenting the other day that we used to have SGML SHORTREF, then XML came along because supposedly SGML is just too hard to parse. But XML is for computers, not for humans. So then we got Markdown, which is worse than where we started from.
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
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.
In a few years we'll all laugh at how ridiculous this blog post is.
If we are still using XML/YAML/JSON etc despite all their faults and shortcomings, Markdown can (and will) last decades.
Markdown is much easier to write quickly than HTML. Situations where I write Markdown quickly include writing messages on Slack and for AI chatbots. I wouldn't want to use HTML in either of those cases.
The Pandoc Markdown dialect solves many of the mentioned issues. If you want a good editor for that have a look at
https://www.zettlr.com/
If we're going to define a programming language as one that is Turing complete, it's important (in a kind of pedantic sense) to note that that includes HTML (with CSS), which can be used to encode a Rule 110 automaton, and excludes C, whose standard imposes an (implementation-defined) upper bound on accessible memory, meaning it can never, even in principle†, similarly a Turing machine, which has infinite storage. This is probably not what was intended :)
† 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.
Because Markdown is awesome, easier to write, and easier to read at the source level.
Bonus points for MD being readable even when it's not parsed. More bonus points for Sublime Text displaying it in plain text and still looking great. Good enough++
Strong disagree. Markdown is great. And the perfect format simply doesn't exist. You cannot be all things to all people. shrug
Because Markdown is quite readable in plaintext form with no Markdown-specific rendering at all. HTML isn't.
i like html fine, but org-mode, now you're talkin'. it's like the nasa voyager equivalent of text markup. just needs to be rescued from being held hostage in emacs.
The format itself can be easily implemented. There's not much to it and it actually has features that's undefined in markdown like frontmatter and references. The things that are missing can be replicated outside of emacs (babel, agenda, task management, timetracking, export,...), it's just that no one is doing it.
Because there's only one reasonable implementation of AsciiDoc
Is that an issue? There’s only one reasonable implementation of Typst too, and both AsciiDoc and Typst are fully supported by Pandoc, which supports a wide selection of writers (output formats).
Use LaTeX nice and simple
This is why John MacFarlane designed djot https://djot.net/
I rarely render it and only use it with syntax highlighting in my text editor, and that’s it. It helps structure my notes, and I love it, KISS.
Markdown lacks JavaScript and can be considered mostly harmless.
We're not "still" using Markdown, we're only getting started.
Markdown is only going to get more popular as AI agents usage grows.
HTML is not something to hold up as the standard for documentation.
"we" aren't using anything, "you" are.
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.
Anyone that thinks Markdown is bad is crazy. People need to be able to quickly and easily markup their text.
I love markdown for technical reporting when the alternative was a hacked together Word document.
Just write in whatever language makes you happy. Nobody is forcing you to use markdown
i would not use html(5). XHTML? perhaps. but try to find 3 parsers, which parse html in the same way and not segfaulting.
It's not possible. HTML is worse. You need at least something, which on parsing does not segfault.
I'll give them credit for not just being another "markdown sucks, let's switch to RST" slop article. Even more so as they say they don't have a solution - because a solution would be like asking for 3/3 on "cheap, reliable, fast" or whatever your favorite version of "engineers are paid to make compromises" is.
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.
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
He at least admitted to be a simple monkey brained developer.
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.
Why aren't you quietly stop using Markdown?
Textile was better, but less popular IIRC
Because it supports HTML as an escape hatch.
You communicate on hacker news through plain text. You don't need to control the user don't, color, and what ads they see.
If what is to communicate, plain text is good enough. If you want to control how information is consumed, fuck of, die already.
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.
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.
> 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.
> These 2 produce IDENTICAL output. And this is just the tip of the iceberg?
> 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.
This also misses the point: multiple syntax markers for the same thing is the opposite of simplicity (though that's not the reason why Markdown will fail)
You have the wrong end of the stick. The point is simplicity for the user, not the developer of the parser. And for users, having two ways to get the same thing adds no complexity- they just pick one and use it.
I don't, it's not simple for the user - you can't just pick one and forget the other or you'll end you wondering why your use of the other for regular text.l suddenly broke your whole paragraph because you didn't close a mark you never use.
This is the needless complexity you wished away
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.
Clickbait
These examples are contrived af.
Nobody uses markdown like that bro. We like markdown because it's easy to read both rendered and raw.
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.
There's another markdown spec that's better mystmd.org
[flagged]
[dead]
[dead]
[dead]
[dead]
You can say hell on your own blog.
Interestingly, you can also choose not to say it on your own blog.
Why the heck would you use the phrase "Why the heck" in any circumstance other than to avoid censorship/algorithmic penality on a social media platform?
Well, one good reason is that a person who generally doesn't "swear" can then choose to use them very effectively when the situation warrants. If you always go to strongest words when mild ones will do, you're out of things to say when you need to make a stronger/more forceful point.
And there is nothing better to use for the headline than a minced oath if you explicitly don't want to swear? Make it make sense.
Perhaps instead of worrying about someone else's free choice to use certain words iver others, it would be wise of you to ask: why would you complain about forced speech patterns in the context of censorship but then be angry when someone uses their free speech differently then you would use it?
[dead]
I say "heck" instead of "hell" all the time. I'm not religious, so the invented "heck" is more of a swearword.
Because being consistent helps prevent mistakes in circumstances where use of regular curse words is contraindicated. And why the fork should you care?
These things tend to get ingrained in you so you continue to use them even if you could technically use the words they replace.
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.