The documentation world is having a heated discussion about markup languages. A recent article defending reStructuredText (rST) over Markdown has sparked intense debate among developers about which tool serves them better.
The conversation centers around a fundamental trade-off in software tools: power versus simplicity. While the original article argues for rST's superior extensibility and document processing capabilities, the developer community's response reveals a clear preference divide.
Readability Trumps Features for Most Users
The strongest pushback from developers focuses on user experience. Many argue that Markdown's biggest advantage isn't its technical capabilities, but how easy it is for humans to read and write. The syntax feels natural, resembling how people already format plain text emails and messages.
This readability concern becomes even more pronounced for non-English languages. Korean developers have pointed out that rST's word-based inline syntax creates significant problems for agglutinative languages, where affixes attach directly to word stems without spaces. In these languages, applying markup requires awkward escape sequences that interrupt the flow of writing.
Language Support Issues:
- Korean/Agglutinative Languages: rST requires escape sequences like
*text*\ suffixfor inline markup - Markdown: Better handling of languages without word boundaries
- CommonMark: Has edge cases but generally more flexible for non-English text
The Tooling Gap Reveals Real-World Priorities
Community discussion reveals a critical weakness in rST adoption: tooling support. Developers report that rST extensions often lag behind main releases, forcing them to use outdated versions for compatibility. The lack of mature WYSIWYG editors and auto-correcting linters makes editing large rST documents painful compared to Markdown's ecosystem.
Meanwhile, Markdown has become ubiquitous across platforms. Developers use it daily in Slack, GitHub, Obsidian, and countless other tools. This familiarity reduces cognitive load and makes documentation writing feel effortless rather than burdensome.
Tooling Ecosystem:
- Markdown: Wide WYSIWYG editor support, integrated in Slack/GitHub/Obsidian
- rST: Limited editor options, extension compatibility issues
- Alternative Solutions: AsciiDoc mentioned as middle ground, Pandoc for conversions
Use Case Determines the Winner
The debate ultimately reveals that both tools serve different needs effectively. Large-scale documentation projects, books, and complex technical specifications benefit from rST's advanced features like cross-referencing, custom directives, and document transformation capabilities.
For books or significant document sets I definitely agree with the author on this. The builtin features for glossary and index are also nice. The extensibility is amazing.
However, for everyday documentation, quick notes, and collaborative writing, Markdown's simplicity wins. Major documentation systems at Microsoft, RethinkDB, and other large organizations successfully use Markdown-based solutions with custom extensions when needed.
The discussion highlights an important principle in tool selection: the best tool isn't always the most powerful one, but the one that best fits your specific workflow and constraints. For most developers, Markdown's combination of simplicity, ubiquity, and good enough functionality outweighs rST's superior technical capabilities.
Note: reStructuredText (rST) is a markup language designed for technical documentation, while Markdown is a lightweight markup language originally created for web writing. Agglutinative languages like Korean form words by combining morphemes (meaningful units) without spaces between them.
Reference: Why I prefer rST to markdown