There is something quietly liberating about opening a plain text file and writing. No toolbar, no formatting panel, no dropdown menu asking you to choose a heading level. Just you, the text, and the knowledge that whatever you write will still be readable in twenty years.
I write my notes in Markdown. I write my blog posts in Markdown. I write my README files, my journal entries, my book notes, and most of my documentation in Markdown. It is not because Markdown is perfect. It is because Markdown is good enough while being almost nothing.
Why I keep coming back to it
The first reason is the simplest one: I can read it without a program. Open a .md file in any text editor on any machine and you can understand what it says. There is no binary format to decode, no proprietary software to license, no rendering engine required. The raw file is the readable version. While you might definitely say formatting and so on but shut up ik you can still read it and I can too.
That matters more than people think. I have lost documents to software deprecation, to corrupted .docx files, to formats that looked perfect on one machine and broke on another. A Markdown file has survived every platform change I have lived through. It will survive the next one too.
The second reason is friction. Writing in Markdown is almost the same as writing plain text. I do not break my flow to bold something. I do not stop thinking to add a link. The syntax lives at the margin of the text, not in the center of it. I can write a whole paragraph and the formatting markers barely intrude.
The third reason is universality. GitHub reads Markdown. My static site generator reads Markdown. Obsidian, Logseq, Notion, Discord, Slack, Reddit, and about a hundred other tools all speak some dialect of Markdown. Write once and it works almost everywhere. That is not a small thing.
The fourth reason is version control. Markdown plays perfectly with Git. Every change is a clean diff. You can see exactly what changed in a sentence, a paragraph, or a heading. Try doing that with a Word document and you will understand why people who care about their writing gravitate toward plain text.
ps. fuck docx just use odt — I wrote more about this in my previous post on ODT.
Is Markdown is broken?
So the honest part. Markdown is not a well-designed language. There is a great post over at BGs Labs (which i came across when i was surfing through hacker news) that goes into depth on why Markdown is essentially a mess, and a lot of it is true. Let me address some stuff.
There are too many ways to do the same thing
This is fair. You can write bold with **text**, __text__, or even <b>text</b>. You can write headings with # Heading or Heading\n======. Different flavors of Markdown support different subsets. What works on GitHub might not work on your static site generator. What renders in Obsidian might break on your forum.
The answer is simple: pick a dialect and stick to it. I use CommonMark. That is the specification. I do not use __bold__ because it creates visual confusion with underlines. I do not use setext headings (the ===== style) because they are ugly and easy to misread. I use the ATX heading syntax. I use ** for bold and * for italic. That is it. The fact that the language allows more does not mean I need to use it.
This is a discipline problem, not a language problem. C has undefined behavior in dozens of places. Good C programmers learn which corners of the language to avoid. The same applies here.
Inline HTML is a footgun
This is the strongest criticism. Markdown allows you to drop raw HTML anywhere in your document. This breaks the simplicity of the format, introduces XSS vulnerabilities, and forces every Markdown parser to also ship an HTML parser. The blog calls this out directly, and it is correct: inline HTML is the source of most Markdown parser CVEs.
But here is the thing: you do not have to use inline HTML. I almost never do. When I need something Markdown cannot express, I accept that limitation and work around it. If I need a complex layout, I am writing HTML directly, not pretending it is Markdown. The escape hatch exists, but using it is a conscious decision, not an accident.
Some tools let you disable inline HTML entirely. My static site generator can be configured to sanitize or strip it. This is a reasonable compromise.
Footnotes and reference links require context-sensitive parsing
Again, true. The moment you add footnotes, the grammar stops being context-free. A footnote definition can appear anywhere in the document, and the parser has to resolve references globally. This is technically a more complex grammar than the core language.
But this is a parser problem, not a writer problem. As someone writing, I do not care about the computational complexity of the parser. I care that footnotes work. And they do, in every tool I use. The fact that it makes the parser harder to write is the parser author’s problem, not mine. ( bro i sound petty asf rn)
Markdown is not powerful enough for real documents
This is where the blog starts tackling more issues, we keep asking Markdown to do things it was never designed for. Math, diagrams, callouts, custom styling, shortcodes, taxonomy, Bibtex, PlantUML, Mermaid, custom CSS. None of these are part of the core language. They are bolted on by individual tools.
And yet, for 95% of what I write, Markdown is exactly as powerful as I need it to be. I am writing blog posts, notes, and documentation. I am not writing academic papers with complex typesetting requirements. If I were, I would use LaTeX. If I were building a complex interactive document, I would use something else. But for writing words on a page, Markdown does the job. I do definitely rely on all those bolted tools too.
The real issue is not Markdown itself. It is that we keep demanding more from it instead of accepting its limits and choosing the right tool for harder jobs.
What I do to work around the limitations
I am not blind to Markdown’s problems. Here is how I handle them:
I stick to CommonMark. I do not use extensions unless I need them for a specific platform. This keeps my files portable.
I do not use inline HTML. If I need something Markdown cannot do, I either simplify or just use inline html cause wtf am I going to do.
I keep files short. Markdown works best for documents that fit in a single screen or two. If a document gets longer than a few thousand words, I split it. This also makes the files easier to navigate in version control.
I use a consistent style. One way to bold, one way to italic, one way to head. No setext headings. No alternative emphasis syntax. This eliminates ambiguity.
I treat Markdown as a first draft format, not a final format. The output on my blog is rendered HTML with CSS. The Markdown file is the source, not the product. I do not expect the raw file to look perfect. I expect it to be readable.
The bigger picture
The blog ends by suggesting we need a build system around a saner markup language with compile-time hooks. I agree that Markdown is not the final answer. But it is also the closest thing we have to a universal writing format that works well enough across enough platforms.
The alternatives are not clearly better. ReStructuredText is more consistent but harder to read and write. Org mode is incredibly powerful but locked into Emacs. AsciiDoc is well-specified but verbose. Plain text is beautiful but limited. HTML is powerful but unreadable in source form.
Markdown sits in the middle. It is flawed, inconsistent, and overextended. But it is also the only format I can write in any editor, version control with Git, publish to any platform, and still read twenty years from now.
That is why I keep using it. Not because it is perfect. Because nothing else comes close to its combination of simplicity, portability, and ubiquity.
The day someone builds something better that people actually adopt is the day I will switch. Until then, I will keep writing **bold** and # Headings and > blockquotes in my .md files, and I will be fine.