I prefer rST to Markdown

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.