Why are we still using Markdown?

Original Article ↗ Hacker News Discussion ↗

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.