Markdown is holding you back

Original Article ↗ Hacker News Discussion ↗

Role & Strengths of Markdown

  • Widely seen as having “won” by being:
    • Extremely simple to learn (minutes, fits on an index card).
    • Readable as plain text without a renderer.
    • Supported in many tools: editors, Git platforms, chat, CMSes, AI systems, etc.
  • For many teams it’s “Markdown or no docs at all”; the low friction gets developers and non‑technical users to actually write.
  • Its minimalism keeps authors focused on content, not layout; some say the lack of richer structure “keeps them honest.”
  • Many workflows layer tools on top (Pandoc, mdBook, Docusaurus, Quarto) to get PDFs, slides, websites, and resumes from Markdown with acceptable quality.

Limitations & Critiques

  • For larger works (books, serious manuals, complex docs) people report pain around:
    • Cross‑references, numbered figures/tables, rich admonitions, TOCs, and multi‑format publishing.
    • Consistent semantics and structure for reuse, automation, accessibility, and translations.
  • The article’s focus on LLMs and semantics draws pushback:
    • Some argue docs are for humans; machines (including LLMs) should adapt to human‑oriented formats.
    • Others counter that machine‑readable structure is valuable for repurposing content, independent of LLMs.
  • Several commenters feel the article frames a false dilemma and underestimates the costs and UX problems of more complex systems.

Alternatives Proposed

  • For more structured docs:
    • AsciiDoc and reStructuredText (often with Sphinx) are praised for directives, roles, better semantics, and DocBook equivalence, but criticized as harder to learn, configure, and parse.
    • LaTeX and Typst for high‑quality typesetting, books, and papers; Typst is seen as a modern, fast, FOSS LaTeX‑like, though its ecosystem and HTML output are still maturing.
    • Org‑mode is loved by Emacs users but considered too tied to that ecosystem.
    • Djot, MyST, Pandoc Markdown, and custom syntaxes (e.g., TapirMD) aim to combine Markdown‑like readability with stronger structure.

Extensions, Dialects & Portability

  • Heavy use of inline HTML, MDX, custom directives, and platform‑specific “flavors” is common.
  • Supporters see this as pragmatic; critics say it fragments the ecosystem, harms portability, and undermines the “it’s just Markdown” claim.
  • Overall consensus: Markdown is excellent for quick, widespread, human‑readable text; richer formats make sense when you truly need strong semantics and complex publishing.