Why are we still using Markdown?
Markdown’s loose, human-friendly syntax keeps winning despite its many quirks, from ambiguous formatting rules to incompatible dialects and awkward edge cases for parsers. Commenters argue that its core strengths—plain-text readability, minimal typing overhead, wide tooling support, and “good enough” structure for documentation, notes, and AI agents—outweigh the messiness and the existence of stricter alternatives like AsciiDoc, reStructuredText, or XML. Many see Markdown as an intentional compromise: limited and inconsistent in places, but uniquely effective at lowering friction for everyday writing and lightweight publishing.
Why Markdown Remains Popular
- Seen as “good enough” for most common tasks: notes, READMEs, lightweight docs, comments, blogs.
- Easy for humans to read and write in raw form; many say they rarely need to see rendered output.
- Low friction encourages writing; less temptation to bikeshed layout compared with HTML/LaTeX/Word.
- Plain-text, portable, version-control-friendly; works well alongside code.
- Limited styling is viewed as a feature: avoids “webapp” bloat and inaccessible designs.
- Ubiquity and expectation: it’s the default “standard text formatting language” in many tools.
- AI angle: token-efficient, easy for LLMs to read/write, increasingly used for agent specs and docs.
Main Criticisms of Markdown
- Spec is underspecified historically; many dialects and inconsistent behavior across tools.
- Multiple syntaxes for the same thing (e.g., italics/bold, list markers) add cognitive load and style drift.
- Edge cases and parsing rules (lists, line breaks, HTML mixing) are surprisingly complex.
- Raw Markdown can be less readable than carefully formatted plain text, especially around line breaks and tables.
- Lack of explicit structure (e.g., explicit section boundaries, indentation-based folding) limits large/complex documents.
- Some want a stricter, single-true-way subset with no HTML and fewer ambiguities.
Alternatives and Comparisons
- HTML: more powerful and semantic, but verbose and harder to read/edit by hand; seen as “for machines.”
- AsciiDoc / reStructuredText: more fully specified and feature-rich (books, admonitions, includes), but heavier and easier to overcomplicate; nested lists and heading syntax are common complaints.
- Org-mode: powerful but tightly coupled to one editor ecosystem.
- Typst, Djot, Gemtext, Textile, XML: cited as cleaner or more principled in various ways, but lack Markdown’s adoption and tooling.
- Many argue no alternative is sufficiently better to overcome Markdown’s momentum.
Design Philosophy, Parsing, and Tools
- Defenders emphasize “worse is better”: prioritize human UX over parser simplicity or semantic purity.
- Critics note that the human-friendly façade hides significant parser complexity.
- Common approach: stay within a simple Markdown subset, use linters/formatters, and escape to HTML/LaTeX/Typst when needed.
- Editors like Obsidian, Zettlr, and TUI viewers (e.g., glow) are praised for making Markdown workflows pleasant.