Sound write-up. It is missing the #1 reason I like it though - it's fundamentally text.
No format/vendor lock-in and very amenable to living in a git repo. For my note taking that's already game over right there against everything else. I don't want to worry about whatever cursed format OneNote uses is still something I can extract in 2035.
I also like that it's become a defacto standard that LLMs speak. I can tell it to look at the code in this server repo and make me a API_documentation.md and it'll grasp that I want a text based summary of how to use this endpoint
Not only that but Markdown use the conventions people already used in text files (point 3 in the article). People wrote Markdown before Markdown existed, they just formalized it.
In fact, I like to write notes and documentation in text form, and then I notice I have been using Markdown all along, so I rename my text file into .md, fix a couple of markers, and now it looks nice on a viewer that supports markdown, and I have syntax highlighting in my text editor.
That's the main reason I still like writing Markdown (and Typst nowadays as well); I can "render" it in my head very quickly.
When I'm reading Markdown, I almost don't even see the symbols. Beginning a statement with a # immediately just looks like a heading, surrounding a word with asterisks looks italic to me, wrapping a string with backticks looks like code formatting to me, and my assumptions are generally right so I don't need to render very often (which is why the Pandoc -> LaTeX -> PDF pipeline didn't bother me that much).
If I'm writing LaTeX or something, I generally have a very rough idea of what something will look like, but it's not terribly reliable for me. I need to render frequently because my assumptions about how something is going to look is likely to be wrong.
I mostly use Typst now because it is similar enough to Markdown, and the compilation time is so categorically faster that I see little reason not to use it, but I still respect the hell out of Markdown for popularizing this kind of syntax.
That made me think - are there any depictions of Markdown in movies and tv shows? I've seen a fair share of C, Java, HTML, and (in newer works) JavaScript and Python. And Perl in The Social Network.
> Not only that but Markdown use the conventions people already used in text files
So why not Markup? At the time, everyone was using markup because Wikipedia was in wikimarkUP, with # for numbered lists, {} for macros and === to denominate titles. The latter still works in Markdown, but the former doesn’t. Funny heritage: Confluence shortcuts are also expressed in markup because it was the trend at the time, but they changed the shortcuts when they went to the Cloud.
MediaWiki syntax was its own odd duck. It used '''bold''' and ''italics'', and [https://example.com/ external links like this] - almost nothing else followed their lead.
> It is missing the #1 reason I like it though - it's fundamentally text.
Sure, but that's table stakes.
There are much better formats: AsciiDoc, reStructuredText, etc. Yet I also primarily use Markdown. I could use a format that's perhaps 20% better, and well-specified. But I'd have to use Markdown somewhere anyway. So I just stick with Markdown. It's good enough for me.
The original Markdown has fewer features than listed for the more advanced formats in the table. Hence if someone uses reStructuredText it is more precise than just saying “Markdown” because Markown could refer to anything from the original minimalist featureset to the vastly extended format supported by pandoc if given the appropriate CLI arguments.
Some text-based formats have more options for tables e.g. alignment of columns (it may help with numbers to right-align them) or multirow/multicolumn options.
Some formats support definition lists (corresponds to <dl> in HTML) - a feature which I often find valuable but was not included in the original Markdown IIRC.
One advantage of using a text-based format is that it can be exported to either LaTeX or HTML and Markdown seems to prefer the HTML output by explicitly supporting inline HTML as an escape hatch for more complex constructs (e.g. tables with rowspan/colspan). In addition to often not being supported for a non-HTML export-type it also hurts the WYSIWYG experience when reading the file like plain text.
Markdown is fundamentally WYSIWYG - you edit something and you get it rendered 1 to 1. Either in plain text (a.k.a. "source") or when it converted to HTML/CSS and then presented.
WYSIWYG requires 1:1 mapping between "source" and "presentation". Markdown is exactly that. While HTML/CSS is 1:N mapping - same presentation can be achieved with many combinations of HTML/CSS rules. That's why "true WYSIWYG" is barely achievable with HTML/CSS.
I think that is the biggest reason why Markdown doesn't support table. There are alternatives that do (e.g. wikitext) but they didn't get as popular as Markdown. Why? Perhaps it's because that tables will never really look fine in pure text no matter how clever your syntax is.
I don't think that is sufficient for the general case because I would like to be able to use the markdown like _emphasis_ or [hyperlinks](https://www.example.com) even inside the table rows and this doesn't render properly when using fixed pitch “tables as source code blocks”
Then you need to re-pad everything (clean looking git diff be damned). It's just the reality of dealing with bounding boxes. Maybe we don't notice it in HTML and such since the browser redraws them for us for free.
A reasonable format would not insist you lay out tables visually any more than it would insist you center your headers if you'd like them horizontally centered when rendered. For instance, Asciidoctor has syntax for table cells that requires no whitespace and lets you put any content at all in a cell.
Same. I’m reading The UNIX Programming Environment (1984), and it’s made me want to use text for a lot more things. Proprietary formats come and go, but text is forever.
Eh, the things Markdown was made to compete with were also text. Including, you know, plain text. Sure, there were people out there doing README.RTF or README.DOC that annoyed us all -- nevermind those README.PDF monsters -- but just as frequently it was README.TXT or READ.ME (or README.DOC was in plain text). And GameFAQs and newsgroups got pretty far with plain text and ASCII graphics.
The problem is that people want to use a web browser to display their documents, they want rich documents, and web browsers are awful at displaying text they don't understand the structure for. And <code> tags look consistently awful when read back, which is why we so strongly prefer syntax highlighting when we read XML or HTML.
Really, the big competition was BBCode, whose main problem is that it's too much like HTML, and Wikitext, whose main problem was that it's too bare-bones and domain-specific. The big advantages of Markdown are:
1. It's simply more readable. It pulls from how people were naturally formatting plain-text documents meant to be read as plain text rather than pulling from markup languages, so it more closely matches how people want to write documents in plain text. That makes the document easy to read while you're writing it. Asterisks for highlighting is an old convention, so were dashes and asterisks for bullets. Really, it made the asterisk an English punctuation mark for emphasis, which I think it genuinely is now.
2. It was easy to parse and short, which made it popular with Web 2.0 social media. It got picked up by Slashdot, Reddit, and Stack Overflow as "good enough" and "better than BBCode" for user generated content. Nobody liked using WYSIWYG editor boxes then, either. They were slow, buggy, and were often Flash-based before HTML5. They needed plain text formatting options, and BBCode was both annoyingly unnatural to type (just like HTML tags) and a little inflexible.
And nobody wanted to repeat MySpace and just let users use HTML. That was a horrible idea (Samy, XSS, etc.).
Except there's a massive lack of Markdown VIEWERS. You find MD files in every open-source project and lots of other places, but almost no viewers that render them as intended. So you wind up looking at them as plain text, with a bunch of formatting characters in them. What's the point, then?
Only just now has Windows Notepad been revised to render Markdown (I think it does now, anyway). And after searching for a Mac one I finally bought Marked. But that's all I could find. Otherwise you have to load MD files in some kind of editor and "preview" them. NO! I just want to double-click on the file and READ it, with the formatting applied. Why is that so hard?
That is the point, markdown has nice looking plain text, It is a terrible formatting language, it has no semantic ability. The whole point of markdown is that it is nice looking plaintext that can be typeset. I would even go so far to say that the intended primary render of markdown is the plaintext
This is why I don't like proposals to make markdown a better markup language, I understand the intent, markdown sucks as a decent language, but these "improvements" make the plain text ugly, and that is most of the value of markdown lost right there.
Markdown viewing is one of the core use-cases I had in mind when building the Tachi Code browser extension (https://tachicode.com/).
Open a raw .md file in your browser and it'll automatically open in a side-by-side editor/preview. If viewing is all you want, you can set the default preview mode for markdown files to be fullscreen.
A lot of the responses to your comment imo are kinda missing your point. I don't use Apple products, but I do understand what you're saying. You want an editor that also has an option for previewing the markup text in its formatted view.
It's officially only available for Linux (the Windows version is currently under development), and like I said, I don't use Apple products, and idk how familiar you are with manually compiling source code or how good Wine is on Macs, but maybe [Remarkable](https://remarkableapp.github.io/) could be an option?
> You find MD files in every open-source project and lots of other places, but almost no viewers
Huh? Any open-source project on GitHub, at least, has the viewer right there. It's the default view of markdown files. I assume other repos are similar.
I mean markdown existed, but before that there's like... whatever format phpbb and friends let you use for forum posts right? There was stuff that was text-y.
But perhaps it was the first big format that was followed a Unix-y "here's a CLI tool to go to HTML from this" thing, instead of some php script
I use this feature DAILY at work, you built something great here. I tend to write in md locally, this makes sharing the work with others easy. Especially to those less plaintext inclined.
One thing I did notice, I can't seem to find a way to set a default codeblock font format. The default font option isn't totally monospaced and so some ascii art looks weird :/
I don't think that has anything to do with your contribution though.
Sorry to hear about the font issue. I'm no longer at Google, but going to forward to some friends who still work there (no guarantee anything changes, but we'll see!)
This was a great addition. That and using `alt+/` to open options/command palette are my favourite features, but you single handedly made Google Docs spark joy for me
Huh, can one natively edit Markdown in Google Docs? This would be one of my main requests for gDocs (as a long time NvAlt/NvUltra daily driver), but how?
> ...that it was too difficult or inconvenient to write out full HTML by hand
It's not necessarily that writing HTML or other markup flavors is harder (obviously it is), but the beauty of Markdown for me is that it's perfectly readable in its raw form as well as with an applied styling.
And speaking of customizing the 'look' of markdown, a shameless plug for a markdown editor I've been working on with extensive customization options: https://kraa.io/about
Off-topic a little bit, but some feedback for your editor:
I saw Kraa when you posted it here on HN, and decided to give it another go, even though I remembered that I dismissed it quickly the first time.
I only got shy beyond the first line -- Kraa breaks words anywhere to wrap to the next line, really a no go for me, at least in Markdown (it's different if I enable word-wrap in my code editor).
Played around a little more and the editing experience is not great (for my needs):
- Kraa hides '#', so I can't remove the header style from headers. The context menu does not offer to change to paragraph style.
- Kraa uses non-standart '[]' for tasks, instead of the more common '- [ ]' and '- [x]'.
Slick UI, sure. However if I cannot edit Markdown, I don't consider it a Markdown editor. Like Notion is also not a Markdown editor, even if I can type '# ' to get a heading.
Thank you, this is great feedback. I hope you will try to give Kraa another chance in the future as it should have at least these points covered.
- An option to render markdown syntax vs immediate translation is coming
- The horrendous bug around word-wrap (in firefox only) should be fixed within days
- adding [ ] for tasks as an alt to [].
As for changing paragraph style, this is purposefully 'hidden' inside the leaf settings (with tons of customization options for everything, not just paragraphs).
I've looked at your product before, but given that I can't self-host it and thus not control it, I think it's too vague on the security details. It does say some in the privacy policy, but there's no real details there. Given the potential sensitivity of personal notes, let alone work ones. Though, if that's no concern, I do think it looks good. So kudos in general. :) You planning to monetize it eventually?
Thanks! And fair enough, self-hosting isn't something we can easily do right now, but I can see why that would be a super valuable feature. For monetizaton – yes, we will soon have a 'pro' tier that will have more storage space for media.
I think it's a littly funny he characterizes "Had the right flavor for every different context" as an advantage. It drives me crazy that Markdown is not the same everywhere and I'm still regularly getting confused about *bold* or **bold** or *italics*. (Curse you, Slack's weirdo version.)
I respect Anil's argument that the extensibility has helped it be adapted to different contexts, and in practice the looseness of it doesn't cause a problem. I do wish CommonMark had more traction (and acceptance and use of the name Markdown). It'd be nice to have a standard, at least for the basic stuff.
That's exactly what we used in on usenet (except,without rendering unless you were using a nice GUI reader, not just tin/rtin)
The problem is that that's too many characters to reserve (they all have to be escaped when you want the actual character) making the resulting text look awful in plain text mode.
They are not reserved characters. They only express a special format when used in that way : a space on its left, and a character stuck to its right AND somewhere down the road : its twin with a character stuck to its left and a space on its right. I built an editor doing just that more than two decades ago, and it works fine.
So *this* and /that/ express formatting, but not 4 * 5 nor 4*5 nor 4/5 nor m/s.
In the contexts where Markdown is most often used, the distinction between bold and italics isn't really important. So long as *this* or **this** gets rendered in a way that conveys emphasis, the meaning is preserved.
Single-asterisk for bold is not Markdown. I believe Slack calls their thing "markup". I also find it annoying. So annoying that I just learned Slack's keyboard shortcuts instead.
Slack messages are formatted in mrkdwn <https://docs.slack.dev/messaging/formatting-message-text/#ba...>. Completely unrelated to Markdown, superficial resemblance only. If there were trademarks in play you’d absolutely attack them for trademark infringement.
But what you type isn’t even mrkdwn, but rather an input mode that supports most of the same syntax.
It took me a long time to see the variations as a plus and not a minus; as a veteran of the RSS-vs-Atom wars, I was long an advocate of Technical Correctness(tm) like any good coder. But the years since then have made me a lot more amenable to what I think of as a sort of Practical Postelism, which I guess is like applied worse-is-better, where we realize the reality is that we'll _always_ have forks and multiplicities, so we should see it as a feature instead of a bug. It's like accepting that hardware will fail, and building it into the system.
I mean, HTML itself is well specified in the streets, and infinitely different flavors in the sheets. I don't _like_ that, the part of me that writes code _hates_ that. But the part of me that wants systems to succeed just had to sort of respect it.
Ah, Anil, but have you fought the plaintext syntax wars yet?
Jokes apart, regular, standardised, visually-suggestive syntax is a key reason I've stuck with org-mode despite its limited acceptance in the world at large.
The many flavours of markdown make it /less/ portable than org syntax, in my experience. As the post below says, "Pandoc lists six different Markdown flavors as output formats." This is not great for collaboration --- now we need some sort of middleware or advanced editor to help people work with more than one syntax format. Besides, mixing syntax in the same document is a boo-boo, because parsers only work at file-level, not semantic token level.
Owing to this, at times, I go as far as to /author in orgmode, but share in markdown/ (org-export), and slurp back and forth (tangle / detangle).
I love Markdown. I'm a bit surprised, though, that you still can't open a .md file by default in most web browsers. It seems like it should be quite trivial to have the browser automatically convert it to html and display it.
You write your markdown file, but add the code snippet at the bottom of yor document and save it with a .md.html extension. Then when you double-click it it opens and renders in your browser.
I save my notes in a Google Drive, and it's now replaced all the note taking apps I've tried over the years
I don't think so. I think it would be sufficient to document the exact markdown it supports and let the chips fall where they may. Yes, it would push markdown in a certain direction, but that's OK as long as it stays faithful to some variant most people already know. For instance whatever variant Github or some other major, main stream tool uses. And then just ignore the critics.
It'll certainly make some people angry, but if we try to please everyone we can't get anything done. And I suspect that it is the fear of not being able to please everyone that is the reason browsers do not have markdown support. It takes a bit of courage to say "this is the variant we'll implement".
HTML was originally said to be an application of SGML. It wasn't. It was vaguely inspired by its syntax and that is the only reason HTML saw wide adoption. Had they tried to actually implement anything close to ISO 8879:1986 we would NOT have adopted HTML for the web. Mostly because it would have been too costly to implement. (Anyone doubting that: have a look at the ISO standard. You can get it in what is essentially annotated form in Charles Goldfarb's "The HTML Handbook").
Of course, Markdown is nowhere near as complex. So this is where perfect is the enemy of good and we end up getting nothing.
Why is this a problem? To me it sounds like a it would be an advantage because you have everything you need to render it already built into the software.
Rendering is trivial. The issue is standards, and the DOM. No-one can write a Markdown implementation for the core of any major web browser in a form that is simultaneously acceptable to both their technical and political governance.
Best you’ll get is a plugin. Strictly arm’s reach. Translation only.
As I was griping above, you usually can't just view a Markdown file with formatting applied at all. I think MAYBE Notepad has been updated just recently to render it, but otherwise... you're looking at plain text with a bunch of formatting characters in it. Why? It's baffling. Where are the simple Markdown READERS?
It really would be nice to have a convenient renderer for it though. It's genuinely surprising something like firefox doesn't have a markdown reader builtin already.
This is a good call. I know it's been suggested multiple times over the years; I wonder what the rationale was for rejecting the format, or at least having the option to render a file when it's loaded. (Maybe a "display as HTML" button or the like would be required before it would be rendered.)
The overlap between these Markdown formats is actually larger than with many other formats. Possibly even larger than HTML’s overlap back when MS Explorer was the dominant browser.
> Possibly even larger than HTML’s overlap back when MS Explorer was the dominant browser.
No way. You were never left in doubt about whether a normal HTML tag would work, or whether tables were available or would become a jumbled illegible mess, or whether a line break in the source would become a space or a hard break. And that’s just the first three things that occur to me.
Yeah, also missing a built-in JS API for turning Markdown into safe HTML. Sure, there are lots of different implementations, but maybe start with something small at least.
The writeup does not mention Jeff Atwood (Stackoverflow founder) trying to convince Gruber to standardize markdown. Atwood approached him publicly in a series of blog posts, but Gruber kept silent, and if I remember correctly finally declined stating that he didn't want to spend time jumping through other persons' hoops. Although it sucks that markdown is not standardized, I still see this as an inspiring example of a person just doing what he wants to do.
It happened a bit differently; Atwood and friends simply came out with a standard document and called it "standard markdown", which Gruber then refused to endorse. Eventually after the series of blog posts and some back and forth they renamed the project "CommonMark", which it is still called today.
I am not sure (of course), but I think Atwood simply thought standardizing this format was so obviously valuable that he didn't consider Gruber might not want to work with him. In retrospect it's kind of nice that it didn't happen, it really keeps everyone incentivized to keep the format simple.
The linked post contains three cases of Markdown syntax (underscores) leaking into the text, where actual italics were likely intended. This is the most basic Markdown syntax element failing to work. The problem CommonMark is trying to solve is not adding new features (the only one they added to Gruber Markdown is fenced code blocks), but rather specifying how to interpret edge cases to ensure the same Markdown code produces the same HTML everywhere.
I understand the goal of the spec. In my experience once some spec document gets adapted widely enough, there's a strong incentive to add new features to it, which renderers would then be compelled to implement. Before you know it, MD is a complicated spec that doesn't serve its original purpose.
In this case a few minor edge cases is really not a big deal compared to that (in my opinion).
The author of CommonMark and Pandoc has a new format called Djot: https://djot.net/ that I've been meaning to check out. Supposedly more sane to parse, and it comes from someone who would definitely know about that sort of thing.
Djot is great. I use it in my project ( client for https://timbran.org/moor.html ). It has all that I needed from markdown without any excess, and it's safe and easy to parse and familiar to people.
> Straight double quotes (") and single quotes (') are parsed as curly quotes
I don't know who actually likes curly quotes, they are clearly excess to me. And as parsing sometimes fails (as the site says it may), you get inconsistent results, and failures stick out like a sore thumb.
Here is another syntax: this is <*bold>. Very unlikely to clash, can be vibe coded in an hour. But it's more of the same.
For reading, I don’t know who prefers straight quotes.
For writing—
There are more than a few people on HN who deliberately type curly quotes and other non-ASCII punctuation, due to a strong preference for them. I’m one of them.
I use Compose sequences: ; ; for left single quote, : : for left double, ' ' for right single, " " for right double.
(Accordingly, I hate being subjected to automatic curlification, partly because it’s not always correct, but more because if I typed ' or " you better believe I meant ' or ".)
I'm fairly new to all this, but my understanding is that Markdown is great for a few reasons:
It's just plain text, so no vendor lock-in and you can ripgrep/fzf/grep through it
Lives happily in git repos with proper diffs
LLMs speak it natively - they output Markdown, they understand Markdown input
Way easier for agents to parse than PDFs (which are binary, layout-focused, tables turn to mush)
Can do tables (at least in GFM), headers, code blocks, links - all structure preserved
What it can't do (as far as I understand): complex layouts, precise typography, embedded binary content, anything that needs pixel-perfect rendering.
Am I missing anything? What are the other limitations I should know about?
> What it can't do (as far as I understand): complex layouts, precise typography, embedded binary content, anything that needs pixel-perfect rendering.
> What it can't do (as far as I understand): complex layouts, precise typography, embedded binary content, anything that needs pixel-perfect rendering. Am I missing anything? What are the other limitations I should know about?
Multi-level lists, annoyingly, get rendered as code at the deeper levels because of the 4+ spaces from the beginning of the line.
This is a serious and major drawback of markdown, making it good for developers only. The average person does not want to render code.
Remove that one drawback, and it'll get even better adoption.
I’m pretty sure many Markdown implementations would turn this into a code block. Unfortunately Babelmark seems to currently be broken so I can’t test it.
I don’t follow. Marked definitely isn’t a programming tool. There’s nothing about Markdown that says nested lists should look like code. That’s just an accident of whatever editor you might be using, not of others.
…as long as you ignore the context that it’s a nested listed under a less-nested list.
Also, note that CommonMark is not identical to Markdown. It intends to be a standard definition of the language, but may differ from the original definition and implementation.
(CommonMark) Markdown is a rough superset of HTML, like how YAML is a superset of JSON. So whatever can be expressed in HTML can also be expressed in Markdown. With the way the CommonMark spec is written, Markdown is effectively just an HTML preprocessor.
A major limitation of Markdown is the lack of standardization. For example, even within GFM there's multiple subtle variants: a single new line becomes a space when rendering Markdown files, but a line break in issue comments.
That’s because Gruber shut down the effort to standardize markdown. He declined to participate and then demanded that “Standard Markdown” be shut down when it went public. This is what yielded CommonMark.
So we are left in the mode where markdown remains needlessly fractured. Different flavors that render slightly different and everyone gets a little annoyed but they deal with it ands occasionally bemoan the fact that there’s no standardization.
I've started to "standardize" my own use of Markdown as "whatever works in the apps I use". For me these apps are iA Writer, Obsidian, and Astro's rendering pipeline (which uses the Remark/Rehype ecosystem under the hood).
This sucks for sharing documents with other people, but in practice it's not a problem. 99% of my writing never leaves my notes app or blog. And when it does, I often export it to PDF or Word to make it easy for non-techie people to read (I love Pandoc for this, it's easily one of the favorite tools in my daily toolkit).
> What are the other limitations I should know about?
It's completely inadequate for anything more than a memo or simple single-page note. Which is fine for many purposes a typical software developer encounters but quickly gets left behind for anything more.
It's exclusively a markup language, completely lacking in semantic meaning. If you're trying to write an actual document, the title is the title not some bold text in a bigger font, for example.
Like a hammer, it's a great tool for certain jobs. So many people assume all their writing tasks are nails.
> What it can't do (as far as I understand): complex layouts, precise typography, embedded binary content, anything that needs pixel-perfect rendering. Am I missing anything? What are the other limitations I should know about?
Off the top of my head: Math typesetting, semantic markup, small caps, document sectioning. (All of these things are very important for me.)
The mistake people do is thinking markdown is something else than a text file formatting convention that is easily converted to other formats to make it prettier.
If what you want to do can't be done by a text file hosted on a gopher server, it just means markdown is not for your usecase.
Markdown is not meant to replace Latex or Microsoft Publisher.
It’s not just “extended” flavours of Markdown that allow embedding HTML. The original reference implementation supports this too.[0]
> For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.
However, there is no way to switch back to Markdown inside HTML, so if, say, you want to have an <article> tag around your article, you need to write it entirely in HTML.
Both ASCIIdoc and reStructured text are older and better (subjective, of course), yet Markdown still won. Happens sometimes, nothing to see, I've moved on (with just a little grumbling). Now I often can't remember their syntaxes anymore, Markdown is everywhere.
The matrix, which you can download, aims to provide an objective comparison. Any idea what features are missing, or can you qualify what makes the other text formats "better"? From my perspective, they are largely equivalent.
I enjoyed "a curmudgeonly guy with a kind heart who right this minute is probably rewatching a Kubrick film while cheering for an absolutely indefensible sports team".
This reminds me of Adam Bosworth's talk on HTML (https://adambosworth.net/2004/11/18/iscoc04-talk/): It is an ironic truth that those who seek to create systems which most assume the perfectibility of humans end up building the systems which are most soul destroying and most rigid, systems that rot from within until like great creaking rotten oak trees they collapse on top of themselves leaving a sour smell and decay. We saw it happen in 1989 with the astonishing fall of the USSR. Conversely, those systems which best take into account the complex, frail, brilliance of human nature and build in flexibility, checks and balances, and tolerance tend to survive beyond all hopes.
Markdown is an 'improvement' over HTML, makes it even more flexible and tolerant and easier to write without using tags.
...until you want to write any tabular data. The Markdown syntax for tables might look pretty when you read it, but the only time I've ever bothered to produce it has been with the help of a WYSIWYG Markdown editor (e.g. Typora). And I actively recoil from the idea of modifying one (since that could potentially change the width of a column, requiring carefully adding/removing spaces from the other cells in the column... ugh.)
Meanwhile, I've been hand-rolling + hand-modifying HTML tables with ease since the HTML4 days. HTML tables do not emit ugh-fields. (With the tradeoff that they do not visually read as tables in their source-code representation. But they still do read as cells grouped into records — and for most cases, that's almost as good.)
And yeah, sure, for embedding wholly-plaintext data tables, you could just drop some lines of CSV in a quote-fenced code block. But that doesn't work if you want that table to render with MD semantics itself, such that you can style the contents of the cells using MD syntax. Think "links to additional resources in Github READMEs."
IMHO, a format that's mostly just Markdown, but which deprecates MD's existing table syntax in favor of a much-simpler-to-write "sigil-annotated list-of-lists" syntax, would be a big hit.
(And, now that I think about it, would also probably make it simple for LLMs to spit actual headered tables at you, rather than relying on endless hierarchical bulleted lists.)
Markdown got there first/early depending on your perspective. Things like AsciiDoc got popular much later when AsciiDoctor was released around 2009 (though it technically existed already when Markdown was created) and is aimed at people who care about structured documentation. It's not aimed at casual users.
Likewise, things like org mode, which also emerged around the same time, catered to a niche of emacs using people. Which almost by definition is a subset of techies. It wasn't a logical choice for a mainstream blogging tool.
Markdown was aimed at people that used blogging tools (initially), and later any other kind of tool that accepted text. It spreading to tools like Slack, Github, etc. is no accident. Github actually has supported plenty of alternatives for documents. But they picked markdown for issue tracking, pull requests, etc. Because they had to just pick something and Markdown was the most popular.
By the time AsciiDoc became more popular (2009ish), Github was already being developed. With Markdown support. AsciiDoc was a niche thing, Markdown was already somewhat widely used then. It was an obvious choice. Them picking Markdown was important because the whole OSS community started using Github and got exposed to Markdown that way.
The rest is history. Other formats existed (textile, and various other wiki formats). They have features that are important to some people. But getting people to switch who don't really care about those features is hard. It's a bit like VHS over Betamax. Was it better. Not really. But it was there and video rental shops had to pick a format. And that wasn't Betamax when the dust settled.
What's preventing browsers from rendering a common subset of markdown without the need for browser extensions, with fallback to the current default of plaintext if parsing fails? LLM output can be copy-pasted for rendering by chat messengers and notetaking apps (e.g. DevonThink). If LLM markdown output continues to proliferate, does it become the defacto common-by-volume subset of Markdown, which browsers could standardize and render?
There is no such thing as a common subset of Markdown. Even basic things are rendered inconsistently by different implementations. If browsers decided to add Markdown support, this would lead to another “works only in Internet Explorer” situation.
> There is no such thing as a common subset of Markdown.
That was true before the widespread use of generative AI. LLM-generated markdown could _become_ the most common subset of Markdown, since machines can generate Markdown faster than humans.
“LLM generated Markdown” is not a coherent description of a language. LLMs can generate anything they have seen in their training data, which includes many incompatible dialects of Markdown.
Major LLMs (e.g. ChatGPT) have a copy button for their output, yielding markdown that is already being consistently rendered by other apps, reflecting what was consistently rendered as HTML. Presumably LLM vendors have built a deterministic way of generating spec-compliant HTML and their well-defined dialect of Markdown, otherwise their chat UI output would not render consistently.
I love reST and I think it lost primarily because of distribution. I.e., the people using it did not have large audiences and didn't put much effort into promoting it.
It's a shame because reST is almost as easy on the eyes as Markdown and is much more capable without being too much more complex.
I was texting with John the other night while working on this piece, and reminiscing about my initial quibbles about the format, and I think I had been frustrated by just about everything on your list. I just need you to travel back in time to tell me to fuss more!
There's always room for a tool that does most of the things that people need to do, alongside far more complicated tools that do that plus a whole lot more. If all you want to do is maybe make some text bold or italic or have a bullet list, you can do it in Word, but it's way more than you need (plus it's not text), Markdown solves your problem, and if someone doesn't have a tool for viewing Markdown, it's still perfectly readable in a text editor.
I've seen people who prefer HTML for user-submitted messages and other stuff that might need some formatting - "But what if we need to add colors to the text? Markdown isn't even one coherent standard, there's multiple ways to render it! What about justifying text? What about..." all while fighting increasing amounts of XSS issues and also the HTML style classes (because ofc JS editors add those, instead of even inline styles if you care about portability so much or semantic HTML where possible), as well as inconsistent looks after storing the data in a relational DB and doing various transformations to it over the years.
If you ever hear any of that, don't listen to it. Just use Markdown. If you're building a messaging system or an announcement system instead of a fully fledged CMS - YAGNI/KISS. Or pick anything other than HTML, even BBCode.
The funny thing is that HTML was supposed to be a markup language that could be read/written by hand, while making it also machine-to-machine friendly - notably by making some "semantic" features accessible for browsers. One of these for instance is the structure of the document; marking section headers was supposed to let browser to automatically generate a table of contents. Additionally CSS was supposed to let users choose how all this was displayed.
All of this failed - or rather, was undone and cancelled by the "modernization" of the Web. Namely the arrival of for-profit companies on the Web, be it Facebook of the press like the New York Times.
It was a boon as they brought valuable content, but they brought it with their own rules. The first set of which is the ads-supported model, which is by definition the opposite of free content; an ad-supported website is not free in a very sneaky way, and it's not just about privacy and manipulative practices (targeted ads, as if ads were not already manipulative enough). Users are actively prevented from consuming the content the way the want.
The situation today is that very few browsers offer out-of-the-box a way to apply a personal CSS, and I think none will generate a ToC from the headers of a HTML page.
And the "semantic" part - far from specialized and more accurate semantic markup frameworks that were considered - is being completely taken over by LLMs; an insanely expensive brute-force solution IMHO.
The web has already be reinvented mostly the way you suggest, see for instance the Gopher and Gemini protocols, but they'll stay forever "niche" networks. Which could be not so bad, as it is very clear that the Web is full of actors malicious to various degrees. Tranquility by obscurity?
I used gopher before mosaic! And yes the issue is not the tech, but the social engineering of a community. Git(hub) has a community; IMHO GitHub users need to put more cool things on there like blogs.. perhaps..
This is good and detailed, but misses a broader trend: how "worse is better" started to win - first Java over C++, then python and javascript over Java, and here markdown over Word and docbook.
When markdown emerged, docbook was getting even more elaborate, and vendors everywhere had for decades been locking people into frameworks and languages with fantastic features that were hard to use -- and then the internet bubble had popped. Then people realized they'd thrown away years building complex system, and had little tolerance for promises.
Markdown is something you can use in its native form. It's both source and destination, with a touch of future-proofing: if the opportunity arrives, you can polish it into anything, and mostly parse it yourself.
(What's surprising to me is that pandoc barely registers when compared with markdown on google trends since 2004; pandoc is the reason I switched completely to markdown in ~2010)
Java isn't worse than C++; it has a much more capable run-time, something which is left as an implementation-defined footnote in C++.
Java had a leg-up over C++ by several decades in having a concurrency story (at all) in the language.
I wouldn't use std:: anything for threads even in a greenfield C++ project today.
Garbage collection is more advanced than the primitive management tools available in C++, like smart pointers to reference counted or exclusively owned objects: those approaches are strictly worse than the correct, gold-standard solution to the object lifetime problem.
It's hard to look at Java and not see it as a transitional language now. Electron, Node, and even .Net have fundamentally been more successful implementing ideas that first saw widespread adoption in Java. JSON is basically XML, which is what Java pushed so hard for for data exchange instead of really gross binary serialization formats.
Although, Java wasn't really trying to compete with C++ everywhere. It's just that, at the time, C++ was used at all levels. I mean, this was a time when it was C++, Visual Basic, or Turbo Pascal/Delphi for application programming. You couldn't easily get more abstract than that. That's wildly unlike today's landscape.
If XML dropped attributes and required everything to be an element -- which people always want to object to because they've used XML wrong their entire careers, but that's exactly what JSON did -- if they did that, and then also permitted `</>` as a universal close tag so that nesting isn't really a problem... which, again, is exactly what JSON did (and SGML)... then I think XML would not be so maligned. Like the problem with XML isn't that it wasn't capable. It's that it had too many features that actually aren't useful, and features that are distracting to the point of making people use it wrong.
Because almost the entirety of the remaining JSON ecosystem is just duplicating what XML did. We have JSON Path and JSON Query. We have JSON schema. There's even JSLT, although it didn't inherit the flaws of that XSLT library. About the only thing there still seems to be an argument about that XML did is JSON comments.
And, to be clear, JSON's perception as being better performing primarily comes from the fact that web browser developers had a vested interest in making JavaScript engines high performance for ordinary JavaScript, and they spent more effort on that than on their XML libraries simply because it was more important. That means the problem with the web hasn't been the use of XML. It's been the way we stapled half a dozen languages together to do one thing: display a document as a computer interface.
But if you use XML to the minimal level as JSON requires by it's nature, and if XML had gotten the performance interest that JavaScript did, then XML would be fine.
So I don't think JSON is better than XML. I think JSON just got lucky.
I couldn't possibly agree more. I remember the first time I saw JSON over HTTP. Within a week, I started ripping out all the SOAP code I'd written because "that's what you're supposed to use". JSON plus a few standard verbs is better than the old XML web services in every way.
"Worse is better" is about simplicity vs expressibility tradeoffs, not an absolute better/worse value judgement. By saying Java is worse than C++ here the OP is only saying that Java is simpler (less expressible) than C++.
Nope; worse is better is about simplicity versus correctness tradeoffs. I've read the P. Gabriel essay enough times that I can rely on my memory of it.
Like whether to hide interrupted system calls, or punt the responsibility for restarting them to the application. (That "PC loser-ing problem" example used in the essay).
Between C++ and Java, it is hard call, but I would say that the Java ecosystem values correctness more than C++.
I don't mean valuing the correctness of a delivered application, but valuing the contribution of the language stack to that goal.
Java manages memory, and defines the order of evaluation of operands in an expression. Need we go on? Java also has a security story for loading compiled code. There is no sandbox model of any kind in C++.
This is of course Correct (pun intended)... but IMO the underlying meaning of correctness was a correctness of the abstractions to the problem domain and that correctness ultimately boils down to the expressibility of the language that allows it to create the correct abstractions. This interpretation might have to do with my having known many fans of Lisp (of which I'm one) and that people who love Lisp (like the author of the paper) are usually big expressibility proponents.
> Java had a leg-up over C++ by several decades in having a concurrency story (at all) in the language.
While sort of technically true, concurrent code expressed in high level language was almost invented in C in the 1980's as the first Unix SMP devices took off (early multiprocessing work at the OS level was at the assembly level, Unix was almost alone in having a portable kernel and the need for SMP).
Java, coming along about a decade later from the same incubation environment, very much reflects that learning. But no, they did it right in Java because they had already done it in C.
I actually had a digression into "worse is better", but the piece was already pushing 5,000 words, so I figured I probably was better of leaving out such a big topic. But you're right that's a larger trend that mattered. I think of it more as a triumph of Postelism in the Internet at large as more people came online, too.
I think about this often as an org mode user who uses it exclusively for journaling with none of the GTD features. Org mode was released before markdown by over a year, but never saw the uptake like markdown did, despite being a more featureful syntax. I think that's because org mode was originally a GTD framework for emacs, and the syntax of org files was incidental to doing GTD in plaintext. It didn't get popularized as an alternative to other markup languages until long after markdown became popular.
I don't really know. I wasn't around back then to watch it unfold. But I still much prefer org mode due to better emacs support and (IMO) more intuitive syntax for things.
When you say "better Emacs support," you're kind of understating things: Org Mode was -- and to a large degree, still is -- tied intimately to Emacs. It was only available in Emacs for years, and if you didn't use Emacs, you probably didn't hear about it for years.
As someone who now uses both, I think the syntax between the two is really kind of a wash. I know Org Mode folks who insist that its syntax for links is more intuitive than Markdown's, for instance, whereas I used to insist that Markdown's was. Now I think neither is really intuitive -- the one that feels more natural to you is, very likely, the first one you learned and got comfortable with. Beyond that, most of the differences in syntax are kind of academic. (I would genuinely argue that Markdown's block quote formatting, which is the way that plain text email tended to quote messages, is more intuitive, at least to anyone who remembers writing email in plain text.) Org Mode partisans also correctly point out that you never have to worry about differences in syntax parsing the way you technically do with different flavors of Markdown, but I'd argue that's because there's effectively only one Org Mode parser out there, e.g., Org Mode in Emacs. There is no formal syntax specification for Org Mode any more than there is for Markdown, and if Org Mode had become as popular and had as many different implementations in as many different programming languages, it would absolutely have the same issue. (In fact, the few non-Emacs Org Mode parsers that I've seen are, to a one, at significant variance with Original Flavor Org Mode once you get past the basics.)
Org Mode's real strength isn't the syntax, it's everything else. I don't use it for GTD, either, but I use it as a task manager and an agenda system for work, and as a personal journal and fiction outliner. None of the power it gets for any of those things comes from using asterisks instead of hash marks for headlines, or slashes instead of underlines for italics. :)
I don't remember Vim's Markdown support to be anything special, either; I do a lot of Markdown work, and tended to use Markdown-specific editors on the Mac like Ulysses and iA Writer, while doing my technical writing in BBEdit. (I never found Vim to fit me particularly well for prose of any kind, even though I was pretty experienced with it. Apparently my writing brain is not modal.)
Semi-ironically given the Org mode discussion, the markdown-mode package for Emacs makes it one of the best Markdown editors I've used!
Same team! Also an orgmode user who uses it for all things longform... A decade+ and counting. Only recently do I see need to start adopting TODOs because work and life tasks are threatening to go beyond the capacity of my normie calendar and paper lists coping mechanisms.
Orgmode text is fairly well supported now, across a plethora of non-Emacs apps and editors. I've enumerated several in my post [0].
Quoting oneself...
> But seriously, Emacs winkwink, amirite?
> Utility is contextual, remember?
>
> So here are ways to use org-mode without Emacs, for useful-to-you purposes, without even caring it is orgmode text underneath.
>
> Mobile, Web, and Desktop apps:
mobile: Orgro, a mobile Org Mode file viewer for iOS and Android
mobile: Plain Org, org text view and editor for iOS
mobile: Orgzly, org text viewer and editor for Android (I use this on my phone, and sync notes to my PC with Dropbox).
mobile: beorg for iOS (tasks, projects, notes)
mobile: flathabits, inspired by Atomic Habits, with all your data stored in org files
web+desktop: logseq, a privacy-first, open-source knowledge base
web: organise, web-based org text editor and viewer
web: braintool.org, a Chrome plugin "to easily capture and categorize all the information and knowledge you want to keep track of, right at the point you discover it or create it"
For some time, I used org-mode for almost all type of note taking. I love the structure being functional without HTML rendering. However, it's pretty much locked to emacs and so the portability is very poor. I need most of my notes to be at least readable on my mobile devices.
When I discovered Obsidian, I decided to fully switch to Markdown. It's very nice that it supports vi bindings.
As someone who was immersed in C++ from the original Stroustrup book (I do not recommend it), then transitioned to Java, then (largely) to Python I disagree on the language comparison.
- Java is not worse than C++, it's actually better for most large-scale programming
- A (subset) of C++ is still far better for performance-intensive applications (games, low-level systems software, avionics, etc.).
- Related to previous, if you're using ALL of C++ in your projects you're "doing it wrong". It is not a well-designed language.
- I agree that Javascript is a win for "worse is better". Anyone remember Netscape Livewire? I try to avoid that language like the plague, but its runtime support is ubiquitous so it gets the most performance-tuning love.
- Python was, initially, just a better Perl, but its dominance in Scientific computing spilled over into data science. Also, Jupyter notebooks provide a unique value proposition for a FOSS-Mathematica.
IMO JS and its spinoffs made mostly the best choices for an interpreted language. The bad parts are pretty inconsequential, and the good parts are important things other langs didn't do well. Even Rust took after how it does async and package management.
Better than Python which also recently started copying over JS decisions, except that Py was easier to use with C libs from the start which made it capture math/data/science usage earlier.
Newlines work in markdown the same way they do in plain text, because markdown is plain text.
If you have something that’s converting markdown into a rich view and it’s not doing that, the problem isn’t with markdown, it’s with your markdown parser.
The thing this oversees is that the interface is important, simpler is not worse, it can in fact often mean better. For example while docbook may have some technical, the user experience for someone who just wants to write some basic stuff is absolutely horrible.
If I imagine beginner-coding me, the first thing I would ask for example is why the hell not just use html by that point. Markdown is a thing I could peesent my non-technical parents unrendered and they still would be able to read the content, just fine for the most part. Try that with docbook.
Now nerds like to pretend the more powerful format is automatically superior. It isn't. Markdown is sucessful because it is so barebones and opinionated and because it forces a focus on the content over formatting. If that is what you need markdown is perfect. If it isn't, go for Latex, HTML+CSS, Typst or use InDesign or whatnot.
Markdown is the opposite of opinionated; nearly everything in the original spec can be done in more than one way. There’s two separate syntaxes to do headers, links, italics, bold, and three ways to do unordered lists.
Markdown decided for the users what the needed formatting options are, instead of giving them a bunch of tools that they could then combine in many different ways. The latter would be unopinionated as it doesn't force the opinions of the devs onto the users.
For example, why doesn't markdown have columns? Why do tables have to have headers? Etc. The reason is someone decided to do it that way on purpose.
Markdown is limited because it covers what its creator (single), needed for his blog. That’s it. Markdown was birthed as a single Perl script (with bugs that are still present).
Tables don’t have to have headers in Markdown. It doesn’t even have tables to begin with! Not in the original specification which still exists. But there are certain flavours of Markdown which add support for tables, and those may or may not require headers. Each flavour implements features of Markdown as it see fit, and those may or not exist in other flavours or be implemented differently.
Markdown allows HTML to be mixed freely. Not all implementations allow it. But the whole point was allowing a fallback to HTML if Markdown couldn't do what you needed. So its not even an option of switching from MD to HTML/CSS, its just an addition when needed.
(I did not read TFA) Or maybe underdeveloped is better? No, that’s not a loaded word hear me out: the syntax is very unobtrusive and minimal if you ignore the whole HTML superset thing. So people can just start using it. Everyone wants to write bullet lists and some emphasis, a code block if they program. Only later do you want maybe a little more, some footnotes, maybe even admonitions. But that’s just a little extra. The syntax is already pretty minimal; there’s room for a little extra like using `^` (`[^1]`) for footnotes. So one extension uses that. Oh and maybe another extension uses something else. But whatever, it’s a trivial difference. Okay now some book-publishing Markdown has become quite different from some static website builder Markdown and it’s kind of annoying to have to keep the differences in mind because you have a blog but you are also writing a book. And it turns out that implementing Markdown in a way that doesn’t have dozens of weird corner cases is annoying because the whole inline markup thing wasn’t specified that well.
It’s like a microcosm of the burden of code. You publish some Perl script that happens to catch on. It’s good enough; any immediate problems are really trivial. Ten years later though they are annoying. But a new lightweight markup variant? Yeah, we should make it close to compatible with “Markdown” because everyone knows Markdown. Maybe specifically GitHub Markdown. Because if it doesn’t render on GitHub it isn’t real.[1] And so it perpetuates through microgenerations.
I did, and Word version 2 was an excellent product. WordBasic was incredible. There was even a graphical dialog-builder, so you could invoke dialogs from your macros. I wrote a macro that parsed and re-wrote SQL queries for a Big-6 consulting firm, saving them man-weeks if not months.
I used to work with a guy that used docx files for all his note taking. Basically did all text writing (other than code) in Word. We had Notepad++ at the time as well, so he just preferred Word for some reason.
I'm sorry, what? Markdown over Word is "Worse is Better". You are shitting me. Markdown over Word is "Better is Better". Haha, dear god. MS Word? It must be some other word surely. MS Word is awful today.
You are misinterpreting the phrase. "Worse", here, means "having less functionality"[0]. Whatever your belief about the usability, speed, consistency, etc. of Microsoft Word (and we probably agree there!), Markdown is certainly "worse" in terms of features.
Java is based on Objective-C/Smalltalk, not on C++. It's strictly worse than its original too. There's a lot to be said for the rule of least power, but it's not nearly powerful enough.
Just joined your Early Reader's list. I've already self-published a novel written partially in Markdown, and starting work on another, so I'm anxious to see what you have to say!
markdown is horrible, horrible format to parse; there are so many ambiguities; CommonMark is so complex because of that and still has so many ambiguities.
it's like YAML: it looks so simple at first, and then the horrors start if you try to use it seriously.
in both cases the most horrors lie in the spaces/tabs/newlines.
> markdown is horrible, horrible format to parse...
I agree entirely. But it's a lovely format to use. Programming as a profession is entirely about making things easier for our users, even if it means making things harder for ourselves.
After all, that's the whole ethos around the web as a platform. Throw some broken HTML soup at a browser and it'll still try its best to render it.
Found myself needing to read a lot of MD docs and wanted to read them quickly in the terminal. didn't find any light, so I whipped one up quickly with Codex.
It's a TUI md reader, fast and cheap on the memory, because of Rust.
Give it a try if you find yourself wanting a quick MD reader in a terminal.
Markdown filled an obvious void: the need for something with more formatting capability than plain text, but editable and version-controllable as plain text, without the obnoxious verbosity and complexity of typical markup languages: i.e. more or less readable as plain text also.
Markdown took over because GitHub decided it should, instead of picking ASCIIDoc which is a better format, has a standard, and is literally used by the git documentation itself.
I'm a big fan of markdown, it's easy enough to remember the basic syntax and your files are portable across hundreds of different editors. If one day I decide to switch away from Obsidian, I can just plug the same files into another good editor.
I like Markdown, and generally agree that it strikes a nice balance between correctness and usability...
...but it's delicious that this blog post also demonstrates an ambiguity in Markdown: how to handle intra-word emphasis. In the rendered output, "mark_up_" and "mark_down_" were probably intended to be "mark<em>up</em>" and "mark<em>down</em>", but the underscores were instead rendered literally.
I do appreciate that Markdown's solution to ambiguities like this is dead simple - just inline some HTML.
I think it's delicious how nobody, absolutely nobody, wants _ to mean "emphasis," they want italics, and yet despite there being a markdown-to-HTML build step nobody has ever done what they were told they were supposed to do to circumvent the semantic issue and use <span class="italic"> instead of <em>.
It wouldn't even make sense for markdown if it were language-agnostic to output <em> when that's HTML-only.
I'm going to go to my grave repeating that <em> is just <i> version 2.
Totally fair. At least in part, I blame the choice of <em> and <strong>: it's really not clear what the hierarchy between them is, so I just think of them as the online versions of italic and bold.
<mild> and <strong>, or <em> and <emem> (or <double-em>, or <very-em>) might have been clearer, but at this point we'll never know.
<em> and <strong> were introduced as the supposedly semantic counterparts to the supposedly physical <i> and <b>. That never made a lot of sense, and then later <i> and <b> were redefined to be some subtly different semantic elements. Which also never really made sense. In the end, they both still mean italics and bold, unless you go out of your way to give them a different styling.
90%+ of its value is that its plain text. with just a few simple conventions for annoting
the individual also claimed (in so many words) that the trillion-dollar AI industry is "controlled" by Markdown. he has either a deeply wrong understanding of the technology, or a shameless ambition for making wild claims to boost traffic
strong writing skills. but weak on technology and nuance, or history of our field
Here's a fun trick: if you add .text to any URL on Markdown creator John Gruber's blog you'll get to see the hand-authored (bar the metadata and tags bits) Markdown he wrote for that entry.
"Too late now, I suppose, but the only file extension I would endorse is “.markdown” [...]
(I personally use “.text” for my own files, and have BBEdit set to use Markdown syntax coloring for that extension, which is why I never saw a need to endorse an official extension.)"
It is my assumption that Gruber chose ‘.text’ over ‘.txt’ for several reasons. To give it a little difference when searching for files. To be more legible to non-computer people. And finally, while Classic MacOS did not use file extensions, the Resource Fork type code for text files was ‘TEXT’
Also a little extra distinction: “.txt” is a relic of 8.3 DOS filename conventions. He was not bound by these. If you’ve got the space, of course you’ll go with “.text” over “.txt” because text is the input, HTML is the output, Markdown is the tool for converting one into the other, per the first line of the introduction:
> Markdown is a text-to-HTML conversion tool for web writers.
Ergo they’re not Markdown documents, they’re text files that can be converted into HTML using Markdown.
for me, the idea of structuring and formatting texts keyboard-only was fundamental for my adoption of markdown. iA Writer as an app that pushed me in that direction. Markdown, iA Writer, and my Keychron are part of my routine.
For me this is the superior format, but alas, almost no one uses it. Even Python projects usually go with.md docs.
What new projects have you seen using.rst docs?
This is a good article, although I wish it had talked a little more about the standardization (or rather, the lack thereof) in Markdown. I get why it didn't, it's trying to be positive about something that is an overwhelming net positive for the world, but I think a "warts-and-all" treatment of the history would be more honest.
I appreciate that Gruber brought this very helpful thing into the world, but OTOH he was such a prick about the whole Standard Markdown debate, for no real reason other than ego. And it resulted in Markdown remaining an ill-defined standard to this day, with occasional compatibility issues still cropping up even though most platforms support most of "Github-flavored Markdown" (itself a stupid name and indicative how badly this has gone).
You've pretty much said what I was going to say. I think John was absolutely inspired in coming up with Markdown, but was a terrible steward. Or perhaps I should say he was unwilling to steward it.
My impression was he pretty much threw up a Perl implementation that was good enough for what he wanted, refused to refine it at all, and declared by the power vested in him by nobody in particular that if any parser implementation differed in behaviour to his (like, to fix bugs or make it better), wasn't true Markdown and wasn't allowed to be called Markdown.
Or perhaps I am being uncharitable in my interpretation of events.
I _don't_ think it was just ego. I think it was a smart strategy because formal standardization tends to bring in complexity, and just letting folks go off on their own and document their own usage (or "flavors") ends up being Good Enough in actual practice. It sucks from a standpoint of what I personally find satisfying, to be clear. But based on what I've seen over the last 20+ years, it is the strategy that is much less likely to yield a format that gets captured by giant companies that own a hyper-corporate standardization process that eventually gets enshittified.
Thanks for responding, Anil! Like I said, I really liked the article overall.
I don't agree that the Standard Markdown effort, had it succeeded as originally laid out, would've resulted in "hyper-corporate standardization". I mean, one of the main actors was Jeff Atwood, just about the least "hyper-corporate" guy there is. And I also don't really see any possible trajectory for Markdown to get "enshittified": after all, for the most part it's just plaintext with formatting conventions that existed way before it. Even if some corporate entity had somehow badly messed it up, markdown.pl and the other pre-existing implementations would have continued to exist.
I just hate that (1) you can't nest anything into a table (2) it's different everywhere.
Restructured Text is much more capable, and yet here we are, still using Markdown.
My markdown pages often also have HTML in them, I mainly use Markdown so if I decide some overlong thing I wrote on Reddit actually doesn't suck, I can copy-paste it into a webpage, and my web-server's .smd handler does the convertion. Lowest common denominator. :(
I can never remember what's what with Markdown. HTML has the important feature of providing a hint to function in the tag. I struggled learning HTML, but I eventually memorized all the tags to the point that I can still hammer out boilerplate all these years later. It's always a coin toss on whether I'll bold or italicize the first time I use Markdown in a while.
Markdown was cool for a while. I have switched to typst and boy is that an improvement. It’s the love child of latex and markdown. With markdown you’d still have to embed latex, while typst has its own thing that is nicer than latex.
I've been enjoying Typst. I worry that much of it is too complex for many end users. I'm musing about having end users draft stuff in markdown, then render that markdown with Typst templates.
Best thing about markdown is the barrier to entry of non technical folks, it stops them shitting over technical documentation and steers them to Confluence or sharepoint for their die on the vine slop.
A brown bag I did almost a decade ago informed some fellow developers about Markdown. Almost all of them dismissed it and confided that they didn't think it would catch on. Once again, I'm glad the gatekeepers are communicating this, one less humiliation ritual.
There's something really interesting about the constraints given by plain text that you would lose with What You See Is What You Get (or, the ever-unfortunate acronym WYSIWYG) controls. I almost think what you get in that case is an unfortunate mindset-shift towards What You See Is All There Is (or, an incredibly dope acronym, WYSIATI).
I liked Textile a lot better initially, and it came out first. And interestingly, both launched at the same time on the platform (Movable Type) where Markdown debuted. So it really was sort of a clean A-B test about which one users chose.
This piece was already pretty long, so I cut out most of the sidebar about Dean Allen and Textile, but he was a special guy, and certainly influential on so many parts of this era, not just Markdown.
I felt that Textile was the superior Sony Betamax to Markdown's VHS.
Also, IME any no-coders I've known get freaked out by Markdown and always chose to use a rich text editor instead.
Fun fact: For my first SW job I had to develop a site for a bunch of academics, and they wanted a way to enter rich text. I suggested textile, and they loved it. At the time, Markdown was not more popular, and I thought textile had the better syntax (it may also have had better library support).
> that year’s largely uninspiring slate of U.S. presidential candidates like Wesley Clark, Gary Hart and, yes, Howard Dean helped propel blogs into mainstream awareness
It was a strange time in Democratic politics: The assumption after 9/11 and the success of the GOP in the 2002 midterms was that GWB was going to be reelected in a walk. So not a lot of big names crowding the field.
I know it seems quite absurd! I actually just added in to this piece a photo I took of the CNN screen that (I believe) was the first mention of the word "blog" that they ever put on-screen; it also has a mention of Hart's campaign. Very low-res, but the potato quality is worth it for the historical value, I think.
The history told here has many errors and omissions and, I would say, paints a misleading picture.
Markdown did not come up with the idea of lightweight markup languages (LMLs). It just happened to become the most popular one, for reasons that the article doesn’t really address. There were other LMLs before and after Markdown. (It does mention Textile later on, but doesn’t mention that there were a number of others, and that it was a field that had been steadily developing.)
> What if you could just write out the text and then the link, sort of like you might within an email? Like: [Anil Dash’s blog](https://anildash.com)!
No one would ever have spelled it like that. It would rather have been either “Anil Dash’s blog (https://anildash.com)” or “Anil Dash’s blog <https://anildash.com>”.
> If mark_up_ is complicated, then the opposite of that complexity must be… markd_own_.
I’m guessing this was intended to have actual italics. (Clearly it wasn’t checked after writing, or else the third underscore would have been shifted before the d.) This shows one of the problems of Markdown. (“_anti_commercial” later has the same problem.) Also why you should prefer * for italics rather than _ when writing Markdown, because in CommonMark it allows you to mark up partial words. Throw away Prettier’s Markdown formatting, by the way, it’s terrible and if you’re not careful may destroy your content, and it insists on underscore for italics.
> Hitting the Mark
> [Stuff about Markdown becoming supported by Google Docs, Microsoft Notepad, Slack, WhatsApp, Discord, Apple Notes.]
A lot of this is wrong:
• What most of them have added is an input mode for their WYSIWYG editor which is best expressed as inspired by Markdown. If you want to actually deal in Markdown, they are always infuriatingly incomplete and incompatible. At best (and it’s never even that good) you’re only typing Markdown, not editing Markdown.
• What most of the rest of them have is a lightweight markup language only superficially similar to Markdown. Slack’s mrkdwn and WhatsApp’s formatting are this.
> The Ten Technical Reasons Markdown Won
I’ll grant 1 as valid but non-technical. 2 as valid for Markdown and less valid for other LMLs for reasons that I’ll get into shortly. 3 as valid for Markdown but also some other LMLs that already existed. 4 as valid and somewhat technical. 5 I won’t grant as distinct from 4. 6… well, the key there is actually that correctness isn’t as important as some of us would like. The flavours part of it was more a building up of technical debt. 7, 8, 9 and 10 I will not grant as reasons that Markdown won—several other LMLs already existed with the same benefits.
But it really misses out on the big reason, though 2 and 6 nudge on it:
Markdown won because it was simple, and extended HTML. It was horribly underspecified and all early implementations were all awfully buggy, inconsistent and incompatible, but it was simple and we didn’t care so much about those problems in those days (for better or for worse). People could implement Markdown themselves in an hour or two.
Nowadays, people familiar with Markdown will look baffled at some of reStructuredText’s syntaxes, but at the time I’d say Markdown and reStructuredText were similarly weird, just in different areas. When getting away from things like BBCode which was almost just HTML with square brackets, and Textile which had more idiosyncratic spellings (I mean things like “bq. ” where email had “> ” on every line), reStructuredText and Markdown were about equal.
reStructuredText is way more technically sound. It’s more capable than Markdown, and there’s none of the wild and incompatible fragmentation. But reStructuredText is heavy to implement, and if you only care about outputting HTML and only for yourself, it’s actually harder to extend—you’ll have to define a node type and extend the writer to know what to do with it, or else use the “raw” directive or role. Whereas with Markdown, you just wrote HTML and hoped for the best. Because Markdown was such a mess. But you’d get it right faster than in reStructuredText.
It’s no coincidence that there’s only one major implementation of each of reStructuredText and AsciiDoc, and only three or four total for each. They were designed for bigger, heavier things. Markdown was designed for simplicity at the cost of correctness… just like HTML was.
Sorry, I'm going to be a downer. I've been around for a long time too, saw many formats come and go (even contributed to some myself). I think Markdown is super neat and handy, but this statement "The trillion-dollar AI industry's system for controlling their most advanced platforms is a plain text format... Their achievement is every bit as impressive as yours." ..is way off. NN math & engineering has been refined for ~50 years (give or take) and scaled to mindboggling levels. For better or worse, it is in the process of transforming how society functions (just like the internet and mobile phones did).
Building modern advanced NN/AI requires extremely sophisticated and advanced science, hardware & algorithms; the format of the prompts conventionally used by some are a handy but fairly trivial part of the endeavor.
No format/vendor lock-in and very amenable to living in a git repo. For my note taking that's already game over right there against everything else. I don't want to worry about whatever cursed format OneNote uses is still something I can extract in 2035.
I also like that it's become a defacto standard that LLMs speak. I can tell it to look at the code in this server repo and make me a API_documentation.md and it'll grasp that I want a text based summary of how to use this endpoint
In fact, I like to write notes and documentation in text form, and then I notice I have been using Markdown all along, so I rename my text file into .md, fix a couple of markers, and now it looks nice on a viewer that supports markdown, and I have syntax highlighting in my text editor.
When I'm reading Markdown, I almost don't even see the symbols. Beginning a statement with a # immediately just looks like a heading, surrounding a word with asterisks looks italic to me, wrapping a string with backticks looks like code formatting to me, and my assumptions are generally right so I don't need to render very often (which is why the Pandoc -> LaTeX -> PDF pipeline didn't bother me that much).
If I'm writing LaTeX or something, I generally have a very rough idea of what something will look like, but it's not terribly reliable for me. I need to render frequently because my assumptions about how something is going to look is likely to be wrong.
I mostly use Typst now because it is similar enough to Markdown, and the compilation time is so categorically faster that I see little reason not to use it, but I still respect the hell out of Markdown for popularizing this kind of syntax.
n.b.: the above quote is from The Matrix.
So why not Markup? At the time, everyone was using markup because Wikipedia was in wikimarkUP, with # for numbered lists, {} for macros and === to denominate titles. The latter still works in Markdown, but the former doesn’t. Funny heritage: Confluence shortcuts are also expressed in markup because it was the trend at the time, but they changed the shortcuts when they went to the Cloud.
Simple and Universal: A History of Plain Text, and Why It Matters
https://amontalenti.com/2016/06/11/simple-and-universal-a-hi...
You might enjoy it!
Sure, but that's table stakes.
There are much better formats: AsciiDoc, reStructuredText, etc. Yet I also primarily use Markdown. I could use a format that's perhaps 20% better, and well-specified. But I'd have to use Markdown somewhere anyway. So I just stick with Markdown. It's good enough for me.
https://keenwrite.com/blog/2025/09/08/feature-matrix/
Are many features missing from the list? From what I can tell, objectively, plain text formats offer largely equivalent functionality.
Some text-based formats have more options for tables e.g. alignment of columns (it may help with numbers to right-align them) or multirow/multicolumn options. Some formats support definition lists (corresponds to <dl> in HTML) - a feature which I often find valuable but was not included in the original Markdown IIRC.
One advantage of using a text-based format is that it can be exported to either LaTeX or HTML and Markdown seems to prefer the HTML output by explicitly supporting inline HTML as an escape hatch for more complex constructs (e.g. tables with rowspan/colspan). In addition to often not being supported for a non-HTML export-type it also hurts the WYSIWYG experience when reading the file like plain text.
Markdown is fundamentally WYSIWYG - you edit something and you get it rendered 1 to 1. Either in plain text (a.k.a. "source") or when it converted to HTML/CSS and then presented.
WYSIWYG requires 1:1 mapping between "source" and "presentation". Markdown is exactly that. While HTML/CSS is 1:N mapping - same presentation can be achieved with many combinations of HTML/CSS rules. That's why "true WYSIWYG" is barely achievable with HTML/CSS.
I think that is the biggest reason why Markdown doesn't support table. There are alternatives that do (e.g. wikitext) but they didn't get as popular as Markdown. Why? Perhaps it's because that tables will never really look fine in pure text no matter how clever your syntax is.
Isn't this a table?
I feel like I've been doing this at least since about 2013?Edit: I get it now. It was not a part of the original spec.
It can look better if we use fixed width font and add padding I guess?No doubt some janky one exists somewhere, but nobody uses that.
The problem is that people want to use a web browser to display their documents, they want rich documents, and web browsers are awful at displaying text they don't understand the structure for. And <code> tags look consistently awful when read back, which is why we so strongly prefer syntax highlighting when we read XML or HTML.
Really, the big competition was BBCode, whose main problem is that it's too much like HTML, and Wikitext, whose main problem was that it's too bare-bones and domain-specific. The big advantages of Markdown are:
1. It's simply more readable. It pulls from how people were naturally formatting plain-text documents meant to be read as plain text rather than pulling from markup languages, so it more closely matches how people want to write documents in plain text. That makes the document easy to read while you're writing it. Asterisks for highlighting is an old convention, so were dashes and asterisks for bullets. Really, it made the asterisk an English punctuation mark for emphasis, which I think it genuinely is now.
2. It was easy to parse and short, which made it popular with Web 2.0 social media. It got picked up by Slashdot, Reddit, and Stack Overflow as "good enough" and "better than BBCode" for user generated content. Nobody liked using WYSIWYG editor boxes then, either. They were slow, buggy, and were often Flash-based before HTML5. They needed plain text formatting options, and BBCode was both annoyingly unnatural to type (just like HTML tags) and a little inflexible.
And nobody wanted to repeat MySpace and just let users use HTML. That was a horrible idea (Samy, XSS, etc.).
If you only use headlines and bulletpoints, I have a very pleasing result for a simple text file.
Only just now has Windows Notepad been revised to render Markdown (I think it does now, anyway). And after searching for a Mac one I finally bought Marked. But that's all I could find. Otherwise you have to load MD files in some kind of editor and "preview" them. NO! I just want to double-click on the file and READ it, with the formatting applied. Why is that so hard?
I like MacDown [1]. Someone recently forked it to MacDown 3000 [2].
[1] https://macdown.uranusjr.com
[2] https://macdown.app
This is why I don't like proposals to make markdown a better markup language, I understand the intent, markdown sucks as a decent language, but these "improvements" make the plain text ugly, and that is most of the value of markdown lost right there.
Try copying some markdown into these places:
- A reddit comment
- Microsoft Teams
- Slack
- Whatsapp
- Discord
- Google Docs
- Discord
- Notion
- Facebook Messenger (although only on desktop I think)
Etc.
Open a raw .md file in your browser and it'll automatically open in a side-by-side editor/preview. If viewing is all you want, you can set the default preview mode for markdown files to be fullscreen.
Markdown is the intended rendering medium.
https://obsidian.md/download
It's officially only available for Linux (the Windows version is currently under development), and like I said, I don't use Apple products, and idk how familiar you are with manually compiling source code or how good Wine is on Macs, but maybe [Remarkable](https://remarkableapp.github.io/) could be an option?
Just thought I'd give my $2.70. ;)
Huh? If you find a markdown file in a project on Github, I have every confidence that it renders as intended in Github's markdown viewer.
Huh? Any open-source project on GitHub, at least, has the viewer right there. It's the default view of markdown files. I assume other repos are similar.
E.g. The readme https://github.com/jquery/jquery
But perhaps it was the first big format that was followed a Unix-y "here's a CLI tool to go to HTML from this" thing, instead of some php script
The question is more why Markdown is slowly but surely outcompeting them.
One thing I did notice, I can't seem to find a way to set a default codeblock font format. The default font option isn't totally monospaced and so some ascii art looks weird :/
I don't think that has anything to do with your contribution though.
THANK YOU!
Sorry to hear about the font issue. I'm no longer at Google, but going to forward to some friends who still work there (no guarantee anything changes, but we'll see!)
And yup, the command palette search change was awesome. Can't take credit for that one though haha
1. Notion-style realtime "autocomplete" for heading and inline formatting Markdown
2. Full Markdown import/export and copy/paste
These features make Docs interoperable with Markdown, but don't make it a Markdown _editor_ in my view.
Anyway, you can enable the features from Tools > Preferences > Enable Markdown
Out of curiosity, do you mean the "autocomplete" feature or the import/export/copy/paste feature? (I did both)
It's not necessarily that writing HTML or other markup flavors is harder (obviously it is), but the beauty of Markdown for me is that it's perfectly readable in its raw form as well as with an applied styling.
And speaking of customizing the 'look' of markdown, a shameless plug for a markdown editor I've been working on with extensive customization options: https://kraa.io/about
I saw Kraa when you posted it here on HN, and decided to give it another go, even though I remembered that I dismissed it quickly the first time.
I only got shy beyond the first line -- Kraa breaks words anywhere to wrap to the next line, really a no go for me, at least in Markdown (it's different if I enable word-wrap in my code editor).
Played around a little more and the editing experience is not great (for my needs):
- Kraa hides '#', so I can't remove the header style from headers. The context menu does not offer to change to paragraph style. - Kraa uses non-standart '[]' for tasks, instead of the more common '- [ ]' and '- [x]'.
Slick UI, sure. However if I cannot edit Markdown, I don't consider it a Markdown editor. Like Notion is also not a Markdown editor, even if I can type '# ' to get a heading.
- An option to render markdown syntax vs immediate translation is coming
- The horrendous bug around word-wrap (in firefox only) should be fixed within days
- adding [ ] for tasks as an alt to [].
As for changing paragraph style, this is purposefully 'hidden' inside the leaf settings (with tons of customization options for everything, not just paragraphs).
I respect Anil's argument that the extensibility has helped it be adapted to different contexts, and in practice the looseness of it doesn't cause a problem. I do wish CommonMark had more traction (and acceptance and use of the name Markdown). It'd be nice to have a standard, at least for the basic stuff.
*bold*
/italics/
_underline_
The problem is that that's too many characters to reserve (they all have to be escaped when you want the actual character) making the resulting text look awful in plain text mode.
So *this* and /that/ express formatting, but not 4 * 5 nor 4*5 nor 4/5 nor m/s.
I see you, mlok, you fellow person of culture :)
-strikeout-
`code`
and bloody leave "-" as a dash. I so hate that it gets transformed into a dot for "bullet enthusiasts"
But what you type isn’t even mrkdwn, but rather an input mode that supports most of the same syntax.
I mean, HTML itself is well specified in the streets, and infinitely different flavors in the sheets. I don't _like_ that, the part of me that writes code _hates_ that. But the part of me that wants systems to succeed just had to sort of respect it.
Jokes apart, regular, standardised, visually-suggestive syntax is a key reason I've stuck with org-mode despite its limited acceptance in the world at large.
The many flavours of markdown make it /less/ portable than org syntax, in my experience. As the post below says, "Pandoc lists six different Markdown flavors as output formats." This is not great for collaboration --- now we need some sort of middleware or advanced editor to help people work with more than one syntax format. Besides, mixing syntax in the same document is a boo-boo, because parsers only work at file-level, not semantic token level.
Owing to this, at times, I go as far as to /author in orgmode, but share in markdown/ (org-export), and slurp back and forth (tangle / detangle).
Cue:
Org Mode Syntax Is One of the Most Reasonable Markup Languages to Use for Text: https://karl-voit.at/2017/09/23/orgmode-as-markup-only/
You write your markdown file, but add the code snippet at the bottom of yor document and save it with a .md.html extension. Then when you double-click it it opens and renders in your browser.
I save my notes in a Google Drive, and it's now replaced all the note taking apps I've tried over the years
[1] https://casual-effects.com/markdeep/
It'll certainly make some people angry, but if we try to please everyone we can't get anything done. And I suspect that it is the fear of not being able to please everyone that is the reason browsers do not have markdown support. It takes a bit of courage to say "this is the variant we'll implement".
HTML was originally said to be an application of SGML. It wasn't. It was vaguely inspired by its syntax and that is the only reason HTML saw wide adoption. Had they tried to actually implement anything close to ISO 8879:1986 we would NOT have adopted HTML for the web. Mostly because it would have been too costly to implement. (Anyone doubting that: have a look at the ISO standard. You can get it in what is essentially annotated form in Charles Goldfarb's "The HTML Handbook").
Of course, Markdown is nowhere near as complex. So this is where perfect is the enemy of good and we end up getting nothing.
Isn’t the beauty of MD supposed to be that if you can’t render it it should still look fine as plaintext?
https://git.sr.ht/~xigoi/markdown-monster/blob/master/monste...
Best you’ll get is a plugin. Strictly arm’s reach. Translation only.
https://github.com/sbarex/QLMarkdown
Related reading: https://www.rfc-editor.org/rfc/rfc7763.html text/markdown registration.
No way. You were never left in doubt about whether a normal HTML tag would work, or whether tables were available or would become a jumbled illegible mess, or whether a line break in the source would become a space or a hard break. And that’s just the first three things that occur to me.
I am not sure (of course), but I think Atwood simply thought standardizing this format was so obviously valuable that he didn't consider Gruber might not want to work with him. In retrospect it's kind of nice that it didn't happen, it really keeps everyone incentivized to keep the format simple.
In this case a few minor edge cases is really not a big deal compared to that (in my opinion).
https://blog.codinghorror.com/standard-markdown-is-now-commo...
And an interesting discussion on hn about it: https://news.ycombinator.com/item?id=4700383
Does CommonMark count?
https://spec.commonmark.org/
> Straight double quotes (") and single quotes (') are parsed as curly quotes
I don't know who actually likes curly quotes, they are clearly excess to me. And as parsing sometimes fails (as the site says it may), you get inconsistent results, and failures stick out like a sore thumb.
Here is another syntax: this is <*bold>. Very unlikely to clash, can be vibe coded in an hour. But it's more of the same.
For reading, I don’t know who prefers straight quotes.
For writing—
There are more than a few people on HN who deliberately type curly quotes and other non-ASCII punctuation, due to a strong preference for them. I’m one of them.
I use Compose sequences: ; ; for left single quote, : : for left double, ' ' for right single, " " for right double.
(Accordingly, I hate being subjected to automatic curlification, partly because it’s not always correct, but more because if I typed ' or " you better believe I meant ' or ".)
It's just plain text, so no vendor lock-in and you can ripgrep/fzf/grep through it Lives happily in git repos with proper diffs LLMs speak it natively - they output Markdown, they understand Markdown input Way easier for agents to parse than PDFs (which are binary, layout-focused, tables turn to mush) Can do tables (at least in GFM), headers, code blocks, links - all structure preserved
What it can't do (as far as I understand): complex layouts, precise typography, embedded binary content, anything that needs pixel-perfect rendering. Am I missing anything? What are the other limitations I should know about?
Please see:
* https://impacts.to/downloads/lowres/impacts.pdf
* https://keenwrite.com/docs/user-manual.pdf
* https://keenwrite.com/blog/2025/09/08/feature-matrix/pdf/jek...
* https://keenwrite.com/blog/2025/09/08/feature-matrix/pdf/sof...
Those are Markdown documents typeset using ConTeXt. Except for Jekyll & Hide, I wrote them all.
Multi-level lists, annoyingly, get rendered as code at the deeper levels because of the 4+ spaces from the beginning of the line.
This is a serious and major drawback of markdown, making it good for developers only. The average person does not want to render code.
Remove that one drawback, and it'll get even better adoption.
Not so. You just need to be principled with your indentation, adding four spaces or one tab for every level of nesting.
(You can leave or remove the two spaces of HN code formatting; zero to three spaces don’t matter.)indented code blocks are leaf blocks, while lists are containers that take precedence
> I just went 22 levels deep with Zed and Marked
Sounds like you're agreeing with me :-/
Or are you arguing that the average person is a programmer, using programming editors and JS libraries?
And that’s the main issue with Markdown.
Yes there is. The Common Mark spec, from 2014, says 4+ spaces indents are code. Nested lists go beyond 4+ indents pretty fast.
Also, note that CommonMark is not identical to Markdown. It intends to be a standard definition of the language, but may differ from the original definition and implementation.
A major limitation of Markdown is the lack of standardization. For example, even within GFM there's multiple subtle variants: a single new line becomes a space when rendering Markdown files, but a line break in issue comments.
If you allow Markdown input you have to give a cheatsheet showing which "flavor" you are using.
https://blog.codinghorror.com/standard-markdown-is-now-commo...
So we are left in the mode where markdown remains needlessly fractured. Different flavors that render slightly different and everyone gets a little annoyed but they deal with it ands occasionally bemoan the fact that there’s no standardization.
This sucks for sharing documents with other people, but in practice it's not a problem. 99% of my writing never leaves my notes app or blog. And when it does, I often export it to PDF or Word to make it easy for non-techie people to read (I love Pandoc for this, it's easily one of the favorite tools in my daily toolkit).
I suppose, since Commonmark specifically has HTML block and raw HTML inlines, any chunk of HTML is by definition valid Markdown.
It's completely inadequate for anything more than a memo or simple single-page note. Which is fine for many purposes a typical software developer encounters but quickly gets left behind for anything more.
It's exclusively a markup language, completely lacking in semantic meaning. If you're trying to write an actual document, the title is the title not some bold text in a bigger font, for example.
Like a hammer, it's a great tool for certain jobs. So many people assume all their writing tasks are nails.
Off the top of my head: Math typesetting, semantic markup, small caps, document sectioning. (All of these things are very important for me.)
If what you want to do can't be done by a text file hosted on a gopher server, it just means markdown is not for your usecase.
Markdown is not meant to replace Latex or Microsoft Publisher.
Some "extended" flavors will allow you to embed HTML and CSS which solves the layout problem. It's not really markdown at that point, though.
> embedded binary content,
If you're using one of the extended variants, you can b64 encode images... but again, that's not really the spirit/intent of markdown.
> For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.
[0] https://daringfireball.net/projects/markdown/syntax#html
https://keenwrite.com/blog/2025/09/08/feature-matrix/
The matrix, which you can download, aims to provide an objective comparison. Any idea what features are missing, or can you qualify what makes the other text formats "better"? From my perspective, they are largely equivalent.
Markdown is an 'improvement' over HTML, makes it even more flexible and tolerant and easier to write without using tags.
...until you want to write any tabular data. The Markdown syntax for tables might look pretty when you read it, but the only time I've ever bothered to produce it has been with the help of a WYSIWYG Markdown editor (e.g. Typora). And I actively recoil from the idea of modifying one (since that could potentially change the width of a column, requiring carefully adding/removing spaces from the other cells in the column... ugh.)
Meanwhile, I've been hand-rolling + hand-modifying HTML tables with ease since the HTML4 days. HTML tables do not emit ugh-fields. (With the tradeoff that they do not visually read as tables in their source-code representation. But they still do read as cells grouped into records — and for most cases, that's almost as good.)
And yeah, sure, for embedding wholly-plaintext data tables, you could just drop some lines of CSV in a quote-fenced code block. But that doesn't work if you want that table to render with MD semantics itself, such that you can style the contents of the cells using MD syntax. Think "links to additional resources in Github READMEs."
IMHO, a format that's mostly just Markdown, but which deprecates MD's existing table syntax in favor of a much-simpler-to-write "sigil-annotated list-of-lists" syntax, would be a big hit.
(And, now that I think about it, would also probably make it simple for LLMs to spit actual headered tables at you, rather than relying on endless hierarchical bulleted lists.)
Likewise, things like org mode, which also emerged around the same time, catered to a niche of emacs using people. Which almost by definition is a subset of techies. It wasn't a logical choice for a mainstream blogging tool.
Markdown was aimed at people that used blogging tools (initially), and later any other kind of tool that accepted text. It spreading to tools like Slack, Github, etc. is no accident. Github actually has supported plenty of alternatives for documents. But they picked markdown for issue tracking, pull requests, etc. Because they had to just pick something and Markdown was the most popular.
By the time AsciiDoc became more popular (2009ish), Github was already being developed. With Markdown support. AsciiDoc was a niche thing, Markdown was already somewhat widely used then. It was an obvious choice. Them picking Markdown was important because the whole OSS community started using Github and got exposed to Markdown that way.
The rest is history. Other formats existed (textile, and various other wiki formats). They have features that are important to some people. But getting people to switch who don't really care about those features is hard. It's a bit like VHS over Betamax. Was it better. Not really. But it was there and video rental shops had to pick a format. And that wasn't Betamax when the dust settled.
That was true before the widespread use of generative AI. LLM-generated markdown could _become_ the most common subset of Markdown, since machines can generate Markdown faster than humans.
My favorite Markdown creation was "GistDeck", a bookmarklet that turned a GitHub Gist of Markdown content into a slide show.
So much easier to make and share than a PowerPoint deck.
https://github.com/nzoschke/gistdeck
https://gistdeck.github.io/
I know that in my younger years I would get a lot of flak for converting .rst files into .md when I joined projects.
(As I got older I just stopped seeing .rst that much)
Why would you do that? Seems terribly impolite to join a project and start breaking things...
It's a shame because reST is almost as easy on the eyes as Markdown and is much more capable without being too much more complex.
If you ever hear any of that, don't listen to it. Just use Markdown. If you're building a messaging system or an announcement system instead of a fully fledged CMS - YAGNI/KISS. Or pick anything other than HTML, even BBCode.
Perhaps md is an opportunity to re invent the web: a browser for just md AND a search engine with an open algorithm that indexes just what is visible.
All of this failed - or rather, was undone and cancelled by the "modernization" of the Web. Namely the arrival of for-profit companies on the Web, be it Facebook of the press like the New York Times.
It was a boon as they brought valuable content, but they brought it with their own rules. The first set of which is the ads-supported model, which is by definition the opposite of free content; an ad-supported website is not free in a very sneaky way, and it's not just about privacy and manipulative practices (targeted ads, as if ads were not already manipulative enough). Users are actively prevented from consuming the content the way the want.
The situation today is that very few browsers offer out-of-the-box a way to apply a personal CSS, and I think none will generate a ToC from the headers of a HTML page.
And the "semantic" part - far from specialized and more accurate semantic markup frameworks that were considered - is being completely taken over by LLMs; an insanely expensive brute-force solution IMHO.
The web has already be reinvented mostly the way you suggest, see for instance the Gopher and Gemini protocols, but they'll stay forever "niche" networks. Which could be not so bad, as it is very clear that the Web is full of actors malicious to various degrees. Tranquility by obscurity?
When markdown emerged, docbook was getting even more elaborate, and vendors everywhere had for decades been locking people into frameworks and languages with fantastic features that were hard to use -- and then the internet bubble had popped. Then people realized they'd thrown away years building complex system, and had little tolerance for promises.
Markdown is something you can use in its native form. It's both source and destination, with a touch of future-proofing: if the opportunity arrives, you can polish it into anything, and mostly parse it yourself.
(What's surprising to me is that pandoc barely registers when compared with markdown on google trends since 2004; pandoc is the reason I switched completely to markdown in ~2010)
Java had a leg-up over C++ by several decades in having a concurrency story (at all) in the language.
I wouldn't use std:: anything for threads even in a greenfield C++ project today.
Garbage collection is more advanced than the primitive management tools available in C++, like smart pointers to reference counted or exclusively owned objects: those approaches are strictly worse than the correct, gold-standard solution to the object lifetime problem.
Although, Java wasn't really trying to compete with C++ everywhere. It's just that, at the time, C++ was used at all levels. I mean, this was a time when it was C++, Visual Basic, or Turbo Pascal/Delphi for application programming. You couldn't easily get more abstract than that. That's wildly unlike today's landscape.
JSON over XML is more of a "better is better" case, though.
Because almost the entirety of the remaining JSON ecosystem is just duplicating what XML did. We have JSON Path and JSON Query. We have JSON schema. There's even JSLT, although it didn't inherit the flaws of that XSLT library. About the only thing there still seems to be an argument about that XML did is JSON comments.
And, to be clear, JSON's perception as being better performing primarily comes from the fact that web browser developers had a vested interest in making JavaScript engines high performance for ordinary JavaScript, and they spent more effort on that than on their XML libraries simply because it was more important. That means the problem with the web hasn't been the use of XML. It's been the way we stapled half a dozen languages together to do one thing: display a document as a computer interface.
But if you use XML to the minimal level as JSON requires by it's nature, and if XML had gotten the performance interest that JavaScript did, then XML would be fine.
So I don't think JSON is better than XML. I think JSON just got lucky.
"Worse is better" is about simplicity vs expressibility tradeoffs, not an absolute better/worse value judgement. By saying Java is worse than C++ here the OP is only saying that Java is simpler (less expressible) than C++.
Like whether to hide interrupted system calls, or punt the responsibility for restarting them to the application. (That "PC loser-ing problem" example used in the essay).
Between C++ and Java, it is hard call, but I would say that the Java ecosystem values correctness more than C++.
I don't mean valuing the correctness of a delivered application, but valuing the contribution of the language stack to that goal.
Java manages memory, and defines the order of evaluation of operands in an expression. Need we go on? Java also has a security story for loading compiled code. There is no sandbox model of any kind in C++.
While sort of technically true, concurrent code expressed in high level language was almost invented in C in the 1980's as the first Unix SMP devices took off (early multiprocessing work at the OS level was at the assembly level, Unix was almost alone in having a portable kernel and the need for SMP).
Java, coming along about a decade later from the same incubation environment, very much reflects that learning. But no, they did it right in Java because they had already done it in C.
I don't really know. I wasn't around back then to watch it unfold. But I still much prefer org mode due to better emacs support and (IMO) more intuitive syntax for things.
As someone who now uses both, I think the syntax between the two is really kind of a wash. I know Org Mode folks who insist that its syntax for links is more intuitive than Markdown's, for instance, whereas I used to insist that Markdown's was. Now I think neither is really intuitive -- the one that feels more natural to you is, very likely, the first one you learned and got comfortable with. Beyond that, most of the differences in syntax are kind of academic. (I would genuinely argue that Markdown's block quote formatting, which is the way that plain text email tended to quote messages, is more intuitive, at least to anyone who remembers writing email in plain text.) Org Mode partisans also correctly point out that you never have to worry about differences in syntax parsing the way you technically do with different flavors of Markdown, but I'd argue that's because there's effectively only one Org Mode parser out there, e.g., Org Mode in Emacs. There is no formal syntax specification for Org Mode any more than there is for Markdown, and if Org Mode had become as popular and had as many different implementations in as many different programming languages, it would absolutely have the same issue. (In fact, the few non-Emacs Org Mode parsers that I've seen are, to a one, at significant variance with Original Flavor Org Mode once you get past the basics.)
Org Mode's real strength isn't the syntax, it's everything else. I don't use it for GTD, either, but I use it as a task manager and an agenda system for work, and as a personal journal and fiction outliner. None of the power it gets for any of those things comes from using asterisks instead of hash marks for headlines, or slashes instead of underlines for italics. :)
I have not been able to get markdown to walk in Vim, anywhere near as well.
Semi-ironically given the Org mode discussion, the markdown-mode package for Emacs makes it one of the best Markdown editors I've used!
Orgmode text is fairly well supported now, across a plethora of non-Emacs apps and editors. I've enumerated several in my post [0].
Quoting oneself...
> But seriously, Emacs winkwink, amirite?
> Utility is contextual, remember? > > So here are ways to use org-mode without Emacs, for useful-to-you purposes, without even caring it is orgmode text underneath. > > Mobile, Web, and Desktop apps:
> Text Editors (apart from Emacs): > > You can type org markup text (syntax) in any text editor, even Notepad. > > Vim: https://github.com/nvim-orgmode/orgmode > > Atom: https://atom.io/packages/org-mode > > VSCode: https://github.com/vscode-org-mode/vscode-org-mode > > A variety of utilities to: > I'm sure more people are making and releasing tools backed by org-mode text. > > The future is bright![0] Why and How I use "Org Mode" for my writing and more
discussed: https://news.ycombinator.com/item?id=43157672
When I discovered Obsidian, I decided to fully switch to Markdown. It's very nice that it supports vi bindings.
Why didn't you set up an automatic recurring export of your Org files to HTML files that are uploaded somewhere? That's what I did.
Using JSON for API calls was such a breath of fresh air!
- Java is not worse than C++, it's actually better for most large-scale programming
- A (subset) of C++ is still far better for performance-intensive applications (games, low-level systems software, avionics, etc.).
- Related to previous, if you're using ALL of C++ in your projects you're "doing it wrong". It is not a well-designed language.
- I agree that Javascript is a win for "worse is better". Anyone remember Netscape Livewire? I try to avoid that language like the plague, but its runtime support is ubiquitous so it gets the most performance-tuning love.
- Python was, initially, just a better Perl, but its dominance in Scientific computing spilled over into data science. Also, Jupyter notebooks provide a unique value proposition for a FOSS-Mathematica.
Better than Python which also recently started copying over JS decisions, except that Py was easier to use with C libs from the start which made it capture math/data/science usage earlier.
If you have something that’s converting markdown into a rich view and it’s not doing that, the problem isn’t with markdown, it’s with your markdown parser.
If I imagine beginner-coding me, the first thing I would ask for example is why the hell not just use html by that point. Markdown is a thing I could peesent my non-technical parents unrendered and they still would be able to read the content, just fine for the most part. Try that with docbook.
Now nerds like to pretend the more powerful format is automatically superior. It isn't. Markdown is sucessful because it is so barebones and opinionated and because it forces a focus on the content over formatting. If that is what you need markdown is perfect. If it isn't, go for Latex, HTML+CSS, Typst or use InDesign or whatnot.
Markdown is the opposite of opinionated; nearly everything in the original spec can be done in more than one way. There’s two separate syntaxes to do headers, links, italics, bold, and three ways to do unordered lists.
Markdown decided for the users what the needed formatting options are, instead of giving them a bunch of tools that they could then combine in many different ways. The latter would be unopinionated as it doesn't force the opinions of the devs onto the users.
For example, why doesn't markdown have columns? Why do tables have to have headers? Etc. The reason is someone decided to do it that way on purpose.
Tables don’t have to have headers in Markdown. It doesn’t even have tables to begin with! Not in the original specification which still exists. But there are certain flavours of Markdown which add support for tables, and those may or may not require headers. Each flavour implements features of Markdown as it see fit, and those may or not exist in other flavours or be implemented differently.
https://keenwrite.com/blog/2025/09/08/feature-matrix/
I wrote the feature matrix to objectively compare plain text-based documentation formats. How do DocBook's features compare against Markdown?
It’s like a microcosm of the burden of code. You publish some Perl script that happens to catch on. It’s good enough; any immediate problems are really trivial. Ten years later though they are annoying. But a new lightweight markup variant? Yeah, we should make it close to compatible with “Markdown” because everyone knows Markdown. Maybe specifically GitHub Markdown. Because if it doesn’t render on GitHub it isn’t real.[1] And so it perpetuates through microgenerations.
[1]: https://news.ycombinator.com/item?id=33873593
Word today is a ghastly, incompetent shitshow.
[0] https://en.wikipedia.org/wiki/Worse_is_better
> first Java over C++
...really? Java was literally created to fix C++ issues.
> then python and javascript over Java
That's just different, not worse.
> It's strictly worse than its original too.
Tell me more of those exiting stories. I’d like to hear them.
Check out my "Advent of Markdown" where I go through surprising markdown behavior: https://mastodon.social/@timokoesters/115643467322561173
https://www.48hourpress.com/publish-with-markdown/
it's like YAML: it looks so simple at first, and then the horrors start if you try to use it seriously.
in both cases the most horrors lie in the spaces/tabs/newlines.
I agree entirely. But it's a lovely format to use. Programming as a profession is entirely about making things easier for our users, even if it means making things harder for ourselves.
After all, that's the whole ethos around the web as a platform. Throw some broken HTML soup at a browser and it'll still try its best to render it.
It's a TUI md reader, fast and cheap on the memory, because of Rust. Give it a try if you find yourself wanting a quick MD reader in a terminal.
https://github.com/seymores/mdr
It's just like comedy, timing is everything.
...but it's delicious that this blog post also demonstrates an ambiguity in Markdown: how to handle intra-word emphasis. In the rendered output, "mark_up_" and "mark_down_" were probably intended to be "mark<em>up</em>" and "mark<em>down</em>", but the underscores were instead rendered literally.
I do appreciate that Markdown's solution to ambiguities like this is dead simple - just inline some HTML.
It wouldn't even make sense for markdown if it were language-agnostic to output <em> when that's HTML-only.
I'm going to go to my grave repeating that <em> is just <i> version 2.
<mild> and <strong>, or <em> and <emem> (or <double-em>, or <very-em>) might have been clearer, but at this point we'll never know.
Edit: apparently <i> has been redefined to be "the idiomatic text element" rather than just italic - so perhaps it's a semantically appropriate choice here after all! https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/...
Emphasis/italics is using /
the individual also claimed (in so many words) that the trillion-dollar AI industry is "controlled" by Markdown. he has either a deeply wrong understanding of the technology, or a shameless ambition for making wild claims to boost traffic
strong writing skills. but weak on technology and nuance, or history of our field
Easier to understand Shape it creates is scannable
GitHub render it by default
Example: https://daringfireball.net/linked/2026/01/09/moylan.text
... and if you look closely at some of the entries you might spot custom Markdown features that aren't part of the published spec.
(I personally use “.text” for my own files, and have BBEdit set to use Markdown syntax coloring for that extension, which is why I never saw a need to endorse an official extension.)"
https://daringfireball.net/linked/2014/01/08/markdown-extens...
It is my assumption that Gruber chose ‘.text’ over ‘.txt’ for several reasons. To give it a little difference when searching for files. To be more legible to non-computer people. And finally, while Classic MacOS did not use file extensions, the Resource Fork type code for text files was ‘TEXT’
> Markdown is a text-to-HTML conversion tool for web writers.
Ergo they’re not Markdown documents, they’re text files that can be converted into HTML using Markdown.
https://daringfireball.net/projects/markdown/
It would be insanely faster to render
pandoc readme.md | lynx -stdin
I like the results better than glow, bat and a few other viewers.
I appreciate that Gruber brought this very helpful thing into the world, but OTOH he was such a prick about the whole Standard Markdown debate, for no real reason other than ego. And it resulted in Markdown remaining an ill-defined standard to this day, with occasional compatibility issues still cropping up even though most platforms support most of "Github-flavored Markdown" (itself a stupid name and indicative how badly this has gone).
My impression was he pretty much threw up a Perl implementation that was good enough for what he wanted, refused to refine it at all, and declared by the power vested in him by nobody in particular that if any parser implementation differed in behaviour to his (like, to fix bugs or make it better), wasn't true Markdown and wasn't allowed to be called Markdown.
Or perhaps I am being uncharitable in my interpretation of events.
I don't agree that the Standard Markdown effort, had it succeeded as originally laid out, would've resulted in "hyper-corporate standardization". I mean, one of the main actors was Jeff Atwood, just about the least "hyper-corporate" guy there is. And I also don't really see any possible trajectory for Markdown to get "enshittified": after all, for the most part it's just plaintext with formatting conventions that existed way before it. Even if some corporate entity had somehow badly messed it up, markdown.pl and the other pre-existing implementations would have continued to exist.
Restructured Text is much more capable, and yet here we are, still using Markdown.
My markdown pages often also have HTML in them, I mainly use Markdown so if I decide some overlong thing I wrote on Reddit actually doesn't suck, I can copy-paste it into a webpage, and my web-server's .smd handler does the convertion. Lowest common denominator. :(
I know what I want, ffs. And I don't want html
I still prefer WYSIWYG.
Chatgpt is pushing markdown to the maximum expose, Google & Microsoft sooner or later should react.
IYKYK. Joyent. TextDrive. Textpattern CMS.
Imagining an alternate universe where it might have been Textile. https://textile-lang.com/
Really it comes down to historically the time and place when Markdown was needed and the power of momentum leading to its mass adoption.
This piece was already pretty long, so I cut out most of the sidebar about Dean Allen and Textile, but he was a special guy, and certainly influential on so many parts of this era, not just Markdown.
Gary Hart?
https://en.wikipedia.org/wiki/Gary_Hart
Yup.
It was a strange time in Democratic politics: The assumption after 9/11 and the success of the GOP in the 2002 midterms was that GWB was going to be reelected in a walk. So not a lot of big names crowding the field.
Markdown did not come up with the idea of lightweight markup languages (LMLs). It just happened to become the most popular one, for reasons that the article doesn’t really address. There were other LMLs before and after Markdown. (It does mention Textile later on, but doesn’t mention that there were a number of others, and that it was a field that had been steadily developing.)
> What if you could just write out the text and then the link, sort of like you might within an email? Like: [Anil Dash’s blog](https://anildash.com)!
No one would ever have spelled it like that. It would rather have been either “Anil Dash’s blog (https://anildash.com)” or “Anil Dash’s blog <https://anildash.com>”.
> If mark_up_ is complicated, then the opposite of that complexity must be… markd_own_.
I’m guessing this was intended to have actual italics. (Clearly it wasn’t checked after writing, or else the third underscore would have been shifted before the d.) This shows one of the problems of Markdown. (“_anti_commercial” later has the same problem.) Also why you should prefer * for italics rather than _ when writing Markdown, because in CommonMark it allows you to mark up partial words. Throw away Prettier’s Markdown formatting, by the way, it’s terrible and if you’re not careful may destroy your content, and it insists on underscore for italics.
> Hitting the Mark
> [Stuff about Markdown becoming supported by Google Docs, Microsoft Notepad, Slack, WhatsApp, Discord, Apple Notes.]
A lot of this is wrong:
• What most of them have added is an input mode for their WYSIWYG editor which is best expressed as inspired by Markdown. If you want to actually deal in Markdown, they are always infuriatingly incomplete and incompatible. At best (and it’s never even that good) you’re only typing Markdown, not editing Markdown.
• What most of the rest of them have is a lightweight markup language only superficially similar to Markdown. Slack’s mrkdwn and WhatsApp’s formatting are this.
> The Ten Technical Reasons Markdown Won
I’ll grant 1 as valid but non-technical. 2 as valid for Markdown and less valid for other LMLs for reasons that I’ll get into shortly. 3 as valid for Markdown but also some other LMLs that already existed. 4 as valid and somewhat technical. 5 I won’t grant as distinct from 4. 6… well, the key there is actually that correctness isn’t as important as some of us would like. The flavours part of it was more a building up of technical debt. 7, 8, 9 and 10 I will not grant as reasons that Markdown won—several other LMLs already existed with the same benefits.
But it really misses out on the big reason, though 2 and 6 nudge on it:
Markdown won because it was simple, and extended HTML. It was horribly underspecified and all early implementations were all awfully buggy, inconsistent and incompatible, but it was simple and we didn’t care so much about those problems in those days (for better or for worse). People could implement Markdown themselves in an hour or two.
Nowadays, people familiar with Markdown will look baffled at some of reStructuredText’s syntaxes, but at the time I’d say Markdown and reStructuredText were similarly weird, just in different areas. When getting away from things like BBCode which was almost just HTML with square brackets, and Textile which had more idiosyncratic spellings (I mean things like “bq. ” where email had “> ” on every line), reStructuredText and Markdown were about equal.
reStructuredText is way more technically sound. It’s more capable than Markdown, and there’s none of the wild and incompatible fragmentation. But reStructuredText is heavy to implement, and if you only care about outputting HTML and only for yourself, it’s actually harder to extend—you’ll have to define a node type and extend the writer to know what to do with it, or else use the “raw” directive or role. Whereas with Markdown, you just wrote HTML and hoped for the best. Because Markdown was such a mess. But you’d get it right faster than in reStructuredText.
It’s no coincidence that there’s only one major implementation of each of reStructuredText and AsciiDoc, and only three or four total for each. They were designed for bigger, heavier things. Markdown was designed for simplicity at the cost of correctness… just like HTML was.