I Prefer RST to Markdown (2024)

Power vs. simplicity and use cases

• Many see reStructuredText (reST) as clearly more powerful: built-in ToCs, indices, cross‑refs, glossary, requirements tooling (e.g. Sphinx‑Needs), automatic link fixing on reorg, multi‑format output (HTML, PDF, EPUB). Favored for books, large doc sets, and complex technical docs (e.g. MAME docs).
• Others argue Markdown is “powerful enough” for large, non‑trivial systems and is widely used in production docs. Most real‑world setups add site‑specific extensions or shortcodes, but 90%+ of content is still plain Markdown.
• Some say Markdown is ideal for quick notes, READMEs, comments, and short pages; reST (or LaTeX/DocBook) is better once documents get long or structurally complex.

Syntax ergonomics and aesthetics

• reST syntax (directives with .., required indentation, odd link forms, underline headers, complex tables, :: literal rules) is often described as ugly, over‑clever, or “groffy”.
• Defenders say it’s consistent once you accept directives as a general mechanism, and that “ugliness” is a valid reason not to use a tool if it causes friction.
• Markdown is praised as easy to remember, close to plain text, and ubiquitous in tools (GitHub, editors, chat). This familiarity is a major practical advantage.

Specification, parsing, and extensions

• Markdown’s original underspecification led to many incompatible parsers and weird edge cases (HTML blocks, nesting, underscores/asterisks). Some say these almost never matter; others report frequent silent formatting or content loss.
• reST has one canonical Python implementation: this gives consistent behavior but ties you to a single language stack.
• Some argue Markdown being hard to extend is beneficial: it stays minimal and avoids fragmentation, encouraging people to keep docs simple.

Internationalization and language model

• reST’s word‑boundary and whitespace assumptions make inline markup awkward in languages without reliable space-separated words (Korean, Japanese, Chinese, scriptio continua in general). Workarounds exist but are clumsy.
• Markdown handles such languages better but still has quirks around emphasis delimiters.

Tooling and alternatives

• Tooling strongly favors Markdown; reST has decent Sphinx support but weak WYSIWYG/editor ecosystem; some reST extensions lag maintenance.
• AsciiDoc is widely seen as a “best of both worlds” syntax but hampered by tooling and adoption.
• Other contenders mentioned: Org mode (great but niche), Djot (Markdown-like but more regular, still immature), Typst (nice for typesetting, not yet mainstream), MyST (Sphinx directives with Markdown), and simply writing HTML directly.