# reStructuredText

19 Hacker News commenters recommended reStructuredText and 9 criticized it, November 2025 to November 2026. It was recommended in 8 of 13 months. It meets the Hacker Approved badge rule.

**Verdict:** Plain-text markup with powerful directives, cross-references and a clear spec, favored for software documentation. Caveat: its syntax is hard to learn and write, and it looks cluttered in source form.

## Why people recommend it

- Powerful directives, roles and features (6 comments): "rST was better at structured content with its directives etc, but it was too complicated for non-techies" ([source](https://news.ycombinator.com/item?id=46581121)) "had cool admonition, import, glossary, and index features that made it better than markdown for me" ([source](https://news.ycombinator.com/item?id=47634109)) "rST is certainly more powerful, but I always found it harder to get into the flow of writing it." ([source](https://news.ycombinator.com/item?id=46569239))
- Built for software documentation and cross-references (3 comments): "are much better suited to build software documentation with cross-references" ([source](https://news.ycombinator.com/item?id=46575130)) "reStructuredText lets you link a single word with a trailing underscore" ([source](https://news.ycombinator.com/item?id=48801072)) "they have rich feature sets to actually build documentation" ([source](https://news.ycombinator.com/item?id=47819472))
- Clear specification and technical soundness (3 comments): "there seems to be only one canonical parser, that defines the format" ([source](https://news.ycombinator.com/item?id=46023969)) "reStructuredText which has a better specification for writing" ([source](https://news.ycombinator.com/item?id=47637632)) "reStructuredText is way more technically sound." ([source](https://news.ycombinator.com/item?id=46563683))
- Better than Markdown for complex content (2 comments): "Both ASCIIdoc and reStructured text are older and better" ([source](https://news.ycombinator.com/item?id=46567407)) "ReST delivers most of what Markdown can't." ([source](https://news.ycombinator.com/item?id=47381557))

## What people warn about

- Hard to learn, write or configure (6 comments): "rST was better at structured content with its directives etc, but it was too complicated for non-techies" ([source](https://news.ycombinator.com/item?id=46581121)) "rST is certainly more powerful, but I always found it harder to get into the flow of writing it." ([source](https://news.ycombinator.com/item?id=46569239)) "I remember attempting restructured text and latex and having a right hard time." ([source](https://news.ycombinator.com/item?id=48336880))
- Hard to read in source form (2 comments): "Other markups like restructured text don't look good in source form." ([source](https://news.ycombinator.com/item?id=46710133)) "without hurting my eyes like reStructuredText (used by Sphinx) does" ([source](https://news.ycombinator.com/item?id=45871782))
- Error-prone spec and governance concerns (2 comments): "the unlearnable syntax of rST and the so-called governance of docutils" ([source](https://news.ycombinator.com/item?id=46019222)) "a specification comprised entirely of footguns" ([source](https://news.ycombinator.com/item?id=47642718))

## Alternatives hackers recommend

- [Papermill Press](https://hackerapproved.com/p/papermill-press.md): 7 recommend

## Cite as

Hacker Approved, "reStructuredText", https://hackerapproved.com/p/restructuredtext/ (counts from 1,795,640 Hacker News comments, November 2025 to November 2026).