reStructuredText
Hacker ApprovedShares rank 4 of 9 markup languages by recommenders
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.
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.
28 people gave an opinion
- recommend it
- 19
- criticize it
- 9
- approval share
- 68%
Recommended in 8 of 13 months
- November 2025: recommended
- December 2025: recommended
- January 2026: recommended
- February 2026: recommended
- March 2026: recommended
- April 2026: recommended
- May 2026: recommended
- June 2026: not recommended
- July 2026: recommended
- August 2026: not recommended
- September 2026: not recommended
- October 2026: not recommended
- November 2026: not recommended (month in progress)
Why it carries the badge
- 19 people recommend itNeeds 10 or more, met.
- 2.1 recommenders for every criticNeeds 2 to 1 or better, met.
- Recommended in 8 of 13 monthsNeeds 4 or more, met.
The same three rules apply to every product, and the badge can’t be bought. How the badge works
What people say about it
The reasons people give, with the number of comments that give each one. Open a reason to read what they said.
Why people recommend it
Each mark is one comment
Powerful directives, roles and features
“rST was better at structured content with its directives etc, but it was too complicated for non-techies”
Comment from 11 Jan 2026 in “How Markdown Took over the World” “had cool admonition, import, glossary, and index features that made it better than markdown for me”
Comment from 4 Apr 2026 in “Why the heck are we still using Markdown?” “rST is certainly more powerful, but I always found it harder to get into the flow of writing it.”
Comment from 10 Jan 2026 in “How Markdown Took over the World” - Comment from 11 Jan 2026 in “How Markdown Took over the World”
- Comment from 7 Dec 2025 in “HTML as an Accessible Format for Papers (2023)”
- Comment from 9 Jan 2026 in “How Markdown Took over the World”
Built for software documentation and cross-references
“are much better suited to build software documentation with cross-references”
Comment from 11 Jan 2026 in “Show HN: Ferrite – Markdown editor in Rust with native Mermaid diagram rendering” “reStructuredText lets you link a single word with a trailing underscore”
Comment from 6 Jul 2026 in “Shrimple – A Simpler, Nicer Markdown” “they have rich feature sets to actually build documentation”
Comment from 18 Apr 2026 in “Show HN: MDV – a Markdown superset for docs, dashboards, and slides with data” Clear specification and technical soundness
“there seems to be only one canonical parser, that defines the format”
Comment from 23 Nov 2025 in “Markdown is holding you back” “reStructuredText which has a better specification for writing”
Comment from 4 Apr 2026 in “Why the heck are we still using Markdown?” “reStructuredText is way more technically sound.”
Comment from 10 Jan 2026 in “How Markdown Took over the World” Better than Markdown for complex content
“Both ASCIIdoc and reStructured text are older and better”
Comment from 10 Jan 2026 in “How Markdown Took over the World” “ReST delivers most of what Markdown can't.”
Comment from 14 Mar 2026 in “It's time to move your docs in the repo”
What people warn about
Each mark is one comment
Hard to learn, write or configure
“rST was better at structured content with its directives etc, but it was too complicated for non-techies”
Comment from 11 Jan 2026 in “How Markdown Took over the World” “rST is certainly more powerful, but I always found it harder to get into the flow of writing it.”
Comment from 10 Jan 2026 in “How Markdown Took over the World” “I remember attempting restructured text and latex and having a right hard time.”
Comment from 30 May 2026 in “Pandoc Templates” - Comment from 4 Apr 2026 in “Why the heck are we still using Markdown?”
- Comment from 22 Nov 2025 in “Markdown is holding you back”
- Comment from 23 Nov 2025 in “Markdown is holding you back”
Hard to read in source form
“Other markups like restructured text don't look good in source form.”
Comment from 21 Jan 2026 in “Nested Code Fences in Markdown” “without hurting my eyes like reStructuredText (used by Sphinx) does”
Comment from 10 Nov 2025 in “Zensical – A modern static site generator built by the Material for MkDocs team” Error-prone spec and governance concerns
“the unlearnable syntax of rST and the so-called governance of docutils”
Comment from 22 Nov 2025 in “Markdown is holding you back” “a specification comprised entirely of footguns”
Comment from 4 Apr 2026 in “Why the heck are we still using Markdown?”
Other markup languages people recommend
The four most recommended other markup languages, with the same counts for each, so you can compare like for like. The tick on each bar marks the 2 to 1 line the badge needs.
See all 9 markup languages, rankedWhat people said
30 of the 32 comments that mention it, newest first. Each links to the original comment.
“reStructuredText lets you link a single word with a trailing underscore”
“I remember attempting restructured text and latex and having a right hard time.”
“a pure markup language that is simple, plain text readable”
“I even switch away from rst to md”
“they have rich feature sets to actually build documentation”
“a specification comprised entirely of footguns”
“The in-betweens just don't seem to have a reason to exist.”
“This is my single biggest complaint about reStructuredText.”
“reStructuredText which has a better specification for writing”
“Writing custom rst code is a pain (and no one else in the world uses it)”
“had cool admonition, import, glossary, and index features that made it better than markdown for me”
“ReST delivers most of what Markdown can't.”
“are a part of reStructuredText & AsciiDoc for instance”
“Worked as advertised, no complaints.”
“It also seems like a fine format.”
“Other markups like restructured text don't look good in source form.”
“rST was better at structured content with its directives etc, but it was too complicated for non-techies”
“are much better suited to build software documentation with cross-references”
“rst has directives (blocks) and interpreted text (inline) which can also effectively do anything”
“rST is certainly more powerful, but I always found it harder to get into the flow of writing it.”
“Both ASCIIdoc and reStructured text are older and better”
“I love reST and I think it lost primarily because of distribution.”
“reStructuredText is way more technically sound.”
“Restructured Text is much more capable”
“reStructuredText is mostly indented but not with headings.”
“reStructuredText support :math: roles.”
“there seems to be only one canonical parser, that defines the format”
“can do impressive things but becomes a huge pain to configure”
“the unlearnable syntax of rST and the so-called governance of docutils”
“without hurting my eyes like reStructuredText (used by Sphinx) does”
Counts come from 1,795,640 Hacker News comments, November 2025 to November 2026. How we count. Report a mistake.