alt Hacker NewsWhy are we still using Markdown?
Comments
This may be the first time my reaction to an objectively terrible programming language is a shrug and a "whatever". I like using markdown. I use it for journaling in Obsidian. It does everything I want it to. I like that it's just flat files. I don't want my journaling to be stuck in some online database.
Yet, I am the same person who refuses to code in anything but Rust due to how not-awful it feels to me. Strange how a person can hold a completely opposite view for two instances of the same problem. Being human in a nutshell.
Somewhat related past discussion: https://news.ycombinator.com/item?id=41120254
Copying my thoughts from there which haven't changed:
>To which I say, are you really going to avoid using a good tool just because it makes you puke? Because looking at it makes your stomach churn? Because it offends every fiber of your being?"
Yes. A thousand times yes. Because the biggest advantage of Markdown is that it's easy to read, and its second-biggest advantage is that it's easy to write. How easy it is to parse doesn't matter. How easy it is to extend is largely irrelevant.
Markdown may or may not be the best tool for writing a book, but Markdown is the best tool for what it does - quickly writing formatted text in a way that is easy to read even for those who are not well versed in its syntax.
I don't want to write a book. If I did I'd use LaTeX before RST. I want something to take notes, make quick documentation and thread comments.
*****
My thoughts on strictly-defined XML-ish syntaxes are the same: they're harder for humans to read, write, and modify, which defeats the primary purpose and benefit of Markdown.
Very few people have to write a Markdown parser. Many orders of magnitude more have to read and write Markdown. Optimize for them even if it makes writing the parser painful.
It is because the primary target for markdown is what would in any other formatting language be the source. Markdown has no source. It is guidelines for good looking plain text layout that when followed can be used to make a typeset document.
Everybody sort of knows it sucks as a formatting language. But we love it anyway. The benefit of being able to get a typeset document from a nice looking plaintext document is just too convenient. It is why specialized markdown editors make no sense to me. Why would you target something as shitty as markdown if you have a specialized editor? But really, if you at all care about the semantics of your document don't write it in markdown. But more importantly please don't kill the utility of markdown by adding semantics to it, all that noise just make the plain text look bad.
One of markdown's greatest assets is that it's basically plaintext. Can't render it to HTML, it's still very readable.
This blog post makes no sense to me.
Mark down is great because it doesn't define a bunch of things. Headline? Its a headline, no font, no sizing, no colors... Just a headline. It means that it can be displayed on any device, printed on any paper, work with any accessibility tool and optimized for what ever requirements the reader has, not what ever the writer thought looked good. The web is full of great content being made hard to access because of poor/inflexible layout choices. Just give me the text and let me choose how to make it readable. The added fact that you can read raw markdown without even parsing it makes it even better. Not having total control over what its going to look like for the reader is a feature not a bug.
This is just like the debate over YAML. In both cases, the language is simple enough, and people use it sanely enough in practice that I just don't care about the warts. Contrast this with something like C++, where the warts are less avoidable and therefore more worthy of notice. Markdown as I use it is functional and simple and no one has suggested an alternative I like better, so I keep using it.
Also, as I use it, Markdown is effectively plain text. I very rarely look at "rendered" markdown. I guess in practice I actually use "plain text" that just happens to look a lot like markdown by this article's definitions.
Not many keystrokes to get a readable text. Yes, it has issues. But at its core, it is a plaintext with extra stuff, and no temptation to turn it into a webapp. (See my footnotes on HTML vs MD for saving text in https://p.migdal.pl/blog/2025/02/markdown-saves/).
Yes, there is a problem with "many ways to do the same thing". The solution is ease - use a linter or autoformatter. No more bikeshedding.
If you plan to use a clean yet expandable syntax, look at Typst. One of its core design principles (https://github.com/typst/typst?tab=readme-ov-file#design-pri...) is:
> Simplicity through Consistency: If you know how to do one thing in Typst, you should be able to transfer that knowledge to other things. If there are multiple ways to do the same thing, one of them should be at a different level of abstraction than the other. E.g. it's okay that = Introduction and #heading[Introduction] do the same thing because the former is just syntax sugar for the latter.
A few things here.
1. Use a proper Markdown parser. The grammar is easy to define EBNF style most implementations I see now days use some recursive descent parser, etc… Regex implementation was used in original authors parser when it became popular.
2. You can resolve ambiguities and define more consistent symbols that make sense. Most markdown implementations are decent and follow common sense best practice syntax.
3. The beauty is its simplicity. You can pick it up in a few minutes and utilize it anywhere you damn near see a text box.
4. Parsing to HTML isn’t the only option! I mostly use TUI markdown viewers that render the document via ANSI escape codes beautifully. Check out glow project. But once you parse and have a AST, you can easily walk it and render it in other ways as well. Again though. Everyone can read a text document and a html document. You can render it to a PDF if need be.
5. Do we really need a whole new markup text2<format of some kind>? Markdown is simple fast and widely supported. So I have to say.. I prefer it over most things and that includes Rst.
If you need real beauty and power you can move to LaTeX or something… My two cents anyway.
https://djot.net/ seems to be very sane and still very similar to markdown. And after reading the CommonMark spec, I appreciate the saneness very much. CommonMark did a great job at describing all the rules and edge cases, but it clearly shows how messy markdown is.
What do you all think of Djot?
I've written over a dozen books.
Have used asciidoc, HTML, word, latex, and rst.
Markdown is the least painful of all. It's not perfect but the others are worse.
(My custom stack uses markdown (or Jupyter notebooks converted to markdown). Pandoc plus some custom filters creates typst (for PDF) or epub.)
Because, and I cannot stress this enough:
Programming languages (and the like) are for humans, not for computers or for creating formal systems.
Understanding this simple fact will save you (and by you I mean me and the type of people who frequent sites like this) a ton of headache.
Ambiguous means unclear meaning, not that there is more than one way to achieve the same thing.
Html has that same problem. Think <b>, <strong>, <p style=“font-weight: 900;”>, etc.
That’s life. Get used to it.
Because it's Good Enough™ in many use-cases.
A critique of MD carries no wind in my sails when it can't even appreciate why marrying multiple contemporary chat-grade formats into a document format might be a helpful thing.
Of course there are problems as you veer away from chat-like messaging, but it does a lot, and allows HTML when it can't go any further.
I like HTML and will use it for my own projects, but I cannot send pure HTML to someone who's not a into tech, so to speak, and expect them to actually read it. It doesn't take much CSS to make a readable web page, and I actually kind of like the barebones no-CSS HTML style, but for many others, that style reads as 'this page is broken'. I guess I can write all my styles inline or in the header, but that's a big ask when I never do that normally.
Markdown though, especially if you're not using way too much of it and mostly using it sensibly, just to give your document some structure, can be read as plain text by pretty much everyone, and will be implicitly understood. Sure, they might not understand the exact different between a word with asterisks on either side and one with underscores on either side, but they'll get that you meant to emphasise that work. They'll also understand a list shown with asterisks, while <ul> and <li> tags will get too verbose for them and clutter the actual content (I don't really care, but I get why they do).
> These 2 produce IDENTICAL output.
This is my single biggest complaint about reStructuredText. You create headings by putting underlines and (optional!) overlines around the section heading text. But all of the following are valid title adornment characters:
! " # $ % & ' ( ) \* +
, - . / : ; < = > ? @
[ \ ] ^ _ ` { | } ~
==
H1
==
Normal text
--
H2
--
H1
~~
Normal text
!!
H2
!!The article correctly identifies the upsides of Markdown, then identifies a bunch of issues that I, as a casual user of it, don't care about.
Then, in the solution section, doesn't identify a solution.
No thank you, I'll stick with Markdown.
> how HTML is only a markup language and not a programming language.
This sentence is a great example of why such a pointless debate continues. Don't disparage HTML as "only" a markup language; it's a markup language. That's no 'better' or 'worse' than a programming language, just different.
I don't think Markdown should be (ab)used as a programming language. It should be treated as a plaintext container that has some formatting to organize the contents.
What was the Bjarne Stroustrup quote about two types of languages again? I certainly have gotten more mileage out of Markdown at this point in my long career as a programmer and web developer than I have out of hand-written HTML, XML, or other markup languages. The latter are good for automation and unambiguous representation needed for system building, but for the type of informal writing that is my bread and butter outside of coding, Markdown kills, and Obsidian is the killer app.
This post reminded me of Bjarne Stroustrup's famous quote "There are only two kinds of programming languages: those people complain about and those nobody uses".
"No, I was and remain against establishing extensions. Markdown has thrived because it’s a small idea, not a spec, and thus embraces many variants to suit particularly needs and contexts." https://x.com/gruber/status/1495119598148009991
A thread on markdown creator's stance https://x.com/nalband/status/1625541479295860752
I always advocate for XML. While Markdown is like "a car in any color as long as it's black", XML is a) exactly what you need and b) as precise as you need it, and also c) not more precise than necessary.
We all need headers and paragraphs, right. But I might want file listings. Or command-line snippets with my own color coding and marks. Or C declarations and precise references to them in text. Or todos. Or bibliographic information. Or I want to express the difference between emphasis and italics. Or I don't. And so on. With XML I grow my own notation that fits like a glove. There's no boilerplate, everything is there for a purpose.
Besides, it is not that incompatible with plain text. Here's plain text:
abc def ghi
<text>
abc def ghi
</text>
I'm in no way saying that markdown is perfect but it is much better than anything else I've used. It's got me through both a bachelors and masters.
The author of this article appears to be unaware of pandoc, and even better quarto. I started with pandoc and various plugins and my own scripts but moved to quarto, it is excellent.
Everyone seems to forget Markdown was invented for humans and incidentally for machines.
Almost everyone who complains has some parser or rendering related agenda. No one cares if you can't nest asterisks inside underscores. Most of these edge cases don't read well as Markdown, which defeats the purpose.
On one hand, yes, all true, it’s definitely a bit of a mess. On the other hand, what’s the alternative and don’t all languages with limitations ultimately get extended by various parties in non-compliant ways? Can anyone point to any alternative that has done it all correctly? Show me one language where someone says “This is all good and correct” and I’ll show you a language with 100 feature requests to extend it way further than its original authors intended and would create a similar mess if acted on. This is all to say, I’m going to coin Roberts’ Rule which says “All markup languages eventually end up as piles of poo with half a Turing-complete language bolted onto the side. Resistance is futile.”
Because we need to get information down quickly, but still have the option of parsing to a presentable format. Markdown is not perfect, but it's far better for the efficient capture of information or document authoring. I recently built AS Notes for VS Code (https://www.asnotes.io). It's markdown based, with wikilinks, mermaid diagrams, with the ability to publish to github pages etc. There is no way I'm writing my day to day notes with HTML and anchor tags without it being a huge distraction. And HTML is so much harder to read in longform if you need to come back end edit your writing. Markdown is for humans where HTML was designed to be simple, but is ultimately for parsers.
I used to write raw HTML for my blog because I needed more formatting and structural power than what Markdown could provide for Jekyll. Then I built my own little blog generator that uses Markdown and which pre-substitutes my own hacky syntax elements for the extras I need.
And this is what Markdown is for: its just enough above plain text such that you can get at least 95% of what you need for a blog post, whilst still have the source be easy to type and proof read.
All problems are solved once you embrace org-mode.
All you need is Emacs! Nothing more!
Strong disagree. Markdown is great. And the perfect format simply doesn't exist. You cannot be all things to all people. shrug
The "right element for the right meaning" crowd is always going to fall when they charge against the sheer walls of "but I like using Caution for my bulleted list" crowd. Or the "of course we put tire patches in the wiring element, it's when we use the tire patches".
Or a million other examples I've wrassled with over the literal decades.
Whatever sophisticated semantic scheme you move into the markup layer, is gonna get messed up. And then your fancy schema is just noise, very expensive noise. Markup layer needs to glue as closely to natural language constructs as possible, and then glue a little more closely than that, and let the bulk of the information derived come from natlang. It's boring, but it works, and it's easier than ever to get quantitative information out of natlang.
Keep the domain stuff out of the markup layer.
All that said, Asciidoc forever baby. Write actual books in it. Not really more complex than Markdown[1]. Beats up DITA, takes its lunch money. Win win win.
[1] Unless you go legit insane with `include` and `ifdef/ifndef/ifeval`
I've actually tried some other markup languages like asciidoc, but went back to markdown since I found it's hard to cooperate with others with another markup language like asciidoc and it's harder to find something else than asciidoctor to render it. I could write blog posts in asciidoc but in order to make it parse-able for my SSG I'd still have to compile it to markdown.
HTML tags contain letters. Naturel Language words also contain letters. But markdown tags don't contain letters, and when reading, tags and words don't get mixed up.
The issue is that simple.
Because to me it's good enough, the syntax is simple and it's totally readable in plaintext, which makes it the ultimate format against vendor lock-in.
As the comment count in this thread increases, the ratio responding to the headline alone, and nothing in the article, is approaching 1.0.
I'm mostly fine with markdown, but I just wanted to comment, this example in the post
# Hi
I am a <ins> simple </ins> _programmer_ doing
<span class="fancy-text"> elegant </span> programming.
<div class="animation">
And here is my portfolio
</div>
I am a <span style="color:green">super *grinch* yall</span>
<p>I am a <span style="color:green">super <b>grinch</b> yall</span></p
Similarly, the div in the first example produces div, p, close-p, close-div, because the rule isn't "find he closing tag". The rule is something like "if the line starts with html then stop parsing and just copy until the next blank line.
All that said, I know the rules and generally know how to follow them. Of course I still run into the issue that even though there's commonmark, every site and tool is running their own variation which are incompatible.
MD is not perfect, but it’s perfectly adequate.
Markdown apologist here - I think MD is the greatest thing since sliced bread and I use it a LOT. In fact, one project I work on has an entire git repo of just MD docs. It’s easy to maintain, and even non-tech people can author them with ease. In fat, I love that raw MD is entirely human-readable, and even if someone fat-fingers some of the syntax, it’s still very forgiving.
Don’t forget, many MD renderers support regular HTML embedding, including <style> tags, which makes it a very flexible choice.
I don’t think it’s going anywhere!
We use markdown because LLMs are great at it.
Markdown in the same directory as the code it documents is very readable by humans and LLMs.
Given LLMs proficiency in markdown and that reading it in view and edit mode is comparable I bet many engineering teams ditch confluence/Google docs for documentation in favor of just markdown plaintext docs adjacent to code (my team has moved design/RFCs to this as well, get feedback via PR commits, turn an LLM loose to implement design)
Also if you really don’t like it I bet you could just ask the LLM to translate it. No point wasting the human input characters or tokens on a ton of <></> etc
That is a lot of complaining for having no suggested better alternative.
And there is your answer to the clickbait title -- we're still using markdown because there's no alternative that is so much better that it is going to dethrone the one that has all the momentum from being the first good-enough take on this that got any traction.
As always, honorable mention to Typst [0] as a good balance between the readability & simplicity of Markdown with the flexibility & composability of LaTeX. I think and hoping that Typst will be the future, but for now I'm happy with Markdown.
[0]: https://typst.app
i use markdown because it's inherently limited to styling that is easy to represent. it's a good way to communicate the limitations of text-based content submission form.
if you tell somebody they can use HTML, they get frustrated when you tell them that tags other than anchor, bold, italic, list, heading, and paragraph aren't supported. but if you tell somebody they can use markdown, then they implicitly understand that the content they're submitting won't be rendered as green text on a purple background, and don't try to accomplish that.
As someone who has written his PhD thesis in LaTeX, I wish Markdown, or more specifically Quarto, would have existed at that time. Spent too mich time setting up basic stuff that is now just 2 pre-defines styles away.
I don't read HTML all the time, and I don't expect it to be easy to read when outside of a browser.
Markdown though, that's my slightly fancy readme. It has just enough structure that I can easily read and understand it on the command line.
I can easily grep it without need for an advanced parsing engine.
If you need something with font and style weight then go for HTML.
But if I see README.html with a project, it's going to put me off wanting to contribute. I do not want to learn that project's style guide for how to add some new parameters to a table or remember that they want to specify italics in one of a dozen different ways.
for me as a user, I like it it's simple to use, I know for the developers it's probably very hard to parse and what not, but for most people the experience matters most. Also markdown you can use it without any parser just a text editor.
Not sure I caught the author’s use case, but Markdown shines in the document space when you’re the author and user. It’s efficient and sufficient—lowest common denominator of ease of writing and formatting basic text.
And I say this while putting up with lousy Markdown rendering on a pet project (Django). Really needs a separate project which lets you massage the html to get the display looking it’s best.
When you look at wisdom principles, like those of the Solomonic kind, you observe that a proverb is profoundly true, wise, and useful when you first hear it, but it starts to feel less so when you subject it to intense scrutiny/deconstruction, or try to extrapolate it to places where it's not supposed to go.
Markdown is like that.
We use it because it's an incredibly human way of writing and reading data without having to wade too deeply into the various forms of overhead that allow machines to read, process, and display it.
Markdown is the Python of documents. As technology, and consequently technical writing increase in complexity, any reduction in barrier to access becomes increasingly necessary. The opposite of using markdown and python leads to bike shedding.
Personally, I always default to the simplest of tools. That's why I truly believe that anything meant for actual human use needs to have reasonable defaults. No "look at all the configs you can have", but a "let's get you what you need".
Why would anyone dislike markdown when it is so simple to use? My only gripe with markdown is that sometimes i forget how to include links.
This article is legit, but markdown is good enough to me. Actually, I was using reStructuredText which has a better specification for writing. I switched back to Markdown because its syntax is easier to remember and fulfill most of my needs. The thing I needed was comments for adding folding marks in vim. I use inline <!-- --> to do so and that's OK.
Because, like UNIX/Linux itself, worse is better: https://en.wikipedia.org/wiki/Worse_is_better - and perfect is the enemy of "good enough."
We want to encourage people to produce written output with minimal friction. Barriers to writing--and especially barriers to producing documentation--should be minimized. Writing well is difficult enough!
Markup is overhead. Complex markup is even more overhead. Markdown is the best compromise we know of today that provides just enough structure and typographic capability, while imposing very little cognitive load on the author.
Besides, if you need something more complicated these days, you can have your favorite AI agent do it.