I prefer rST to Markdown

Original Article ↗ Hacker News Discussion ↗

Programmers are weighing the trade‑offs between Markdown’s simplicity and ubiquity and reStructuredText’s (rST) greater power and extensibility, especially for large, structured documentation and books. Many praise rST (often via Sphinx) for semantic linking, custom directives, and robust cross‑referencing, but criticize its verbosity, tooling pain, and weak ecosystem compared with Markdown’s “good enough” syntax and wide support. Alternatives like AsciiDoc, Typst, Org mode, and XML/DocBook also surface, yet most agree that for collaborative, everyday docs Markdown’s low barrier to entry often outweighs technically superior but more complex formats.

Use cases: books vs everyday docs

  • Many agree rST (especially with Sphinx) is strong for large, structured documentation and books: custom roles/directives, semantic constructs (exercises/solutions, bug links), and multi-format output.
  • Markdown is preferred for everyday notes, READMEs, comments, and small docs because it “gets out of the way” and is fast to write, especially for non‑technical or occasional contributors.
  • Several note that when writing an actual book, the bottleneck is often typesetting and multi-output pipelines; some solve this with Markdown + Pandoc or custom tooling instead of rST.

Expressiveness and extensibility

  • rST is praised as “midweight” and semantically rich: directives, roles, cross‑refs, and the Sphinx API make custom document objects easy to define and reuse.
  • Critics point out real limits (e.g., awkward or impossible inline markup nesting) and say Sphinx/docutils extensions are painful in practice.
  • Many argue Markdown can be effectively extended via dialects (Pandoc, MyST, Hugo shortcodes, markdown‑it plugins), making it “good enough” even for complex workflows.

Tooling and ecosystems

  • Sphinx + rST is seen as architecturally sound for big doc sites, with strong linking guarantees, extension ecosystem, and i18n/versioning features—but also slow builds, finicky configs, and fragile plugin compatibility.
  • Markdown wins on ubiquity: supported across languages, platforms, Git hosting, static site generators, and editors, with good linters and ergonomics.
  • Lack of rST support in modern tools and the Python‑only reference implementation are recurring complaints.

Readability and syntax preferences

  • Supporters of Markdown emphasize source readability and familiarity from email/Usenet conventions; many say non‑technical users can read and write it with almost no training.
  • rST is widely perceived as “ugly” or visually noisy (directives, underlined headers, trailing underscores), though some argue it’s still readable if used with discipline.
  • There’s disagreement over whether rST is “just as easy” as Markdown; multiple commenters report failed attempts to introduce rST in teams.

Alternative markup systems

  • AsciiDoc is repeatedly suggested as a better “power user” middle ground than rST (richer tables, includes, xrefs), but tooling—especially outside Ruby—is weaker.
  • Other contenders mentioned: Org mode, Djot, Typst, Scribble/Pollen, XML/DocBook/XSLT, SGML, HTML with custom elements, and YAML for structured data.
  • Consensus: no single format is ideal; choice depends on audience, tooling, and document complexity.