Products · Product
reStructuredText
Raised as a usability problem by 31 people on Hacker News over 14 years (2013–2026), in 22 threads.
No issue was raised by at least 3 people in 3 threads this year.
- 1Syntax is hard to write and readUnreviewed
- 1Syntax is hard to write and readUnreviewed
Every issue, all time, most people first
Syntax is hard to write and readUnreviewed
20132026- ReStructuredText tables are hard to write, described as worse than Markdown2025-08-18
- RST syntax looks confusing and overly explicit to the reader2024-07-31
- RST syntax is hard to understand and work with2022-03-25
Unreviewed issues were grouped by machine: Claude Haiku labelled each comment as a usability complaint, named what it's about and summed up the problem in a line, and a small model grouped similar problems. Nobody has checked them by hand. Expect mistakes.
The newest 32 complaints
- Too complicated for non-technical users, with repeated punctuation and careful indenting2026-01-11
- ReStructuredText tables are hard to write, described as worse than Markdown2025-08-18
- Markup rules like indentation, '..' comments and whitespace-dependent '::' are confusing and error-prone2025-08-18
- Unusable for Korean text because it was not designed for agglutinative languages2025-08-18
- Tooling is so finicky that engineers stopped updating the docs2024-07-31
- RST syntax looks confusing and overly explicit to the reader2024-07-31
- Double backticks and matching heading underlines are frustrating and annoying to type and edit2024-07-31
- Nested lists accidentally end up inside blockquotes because of indentation rules2024-03-05
- Docs are badly organized, seem half-finished, and assume readers already know the reading order2022-11-04
- Too fancy and complex, and unforgiving of content errors2022-06-28
- Docutils API so poorly documented that custom directives were extremely frustrating to build2022-05-11
- RST syntax is hard to understand and work with2022-03-25
- Whitespace sensitivity makes documents fiddly, with inscrutable warnings and silent mis-compilation2022-02-21
- Making an image into a link needs several lines of awkward markup2021-12-15
- No clean way to make link text contain monospace formatting2020-03-24
- Cannot explicitly define inline code, so trailing spaces get eaten and workarounds are needed2020-03-24
- Writing hyperlinks needs many special characters, tedious and hard to read2020-03-24
- A typo in a header underline makes RST silently ignore the header2019-04-10
- The syntax is too hard to remember2019-02-12
- Writing docs in reStructuredText is just slightly painful, so the writer drags their feet2018-12-01
- Its markup differs from Markdown, so Markdown users find it hard to learn and onboarding is a chore2018-11-30
- Users get confused about which heading character maps to which heading level2017-09-24
- Writing section underlines requires holding keys and matching the heading length exactly2017-06-14
- ReST syntax is too complicated compared to Markdown2017-02-26
- Text-only editing gives no live feedback, so writers must imagine how text will render2016-06-17
- Features have obtuse names, docs have gaps, and error messages are unhelpful, making debugging very hard2016-06-17
- Nested markup gets verbose and inconsistent, hard to style and read2016-06-17
- Basic features like bullet lists and titles are annoying to write2016-06-17
- Syntax is unintuitive, users keep forgetting how to do things2016-03-15
- Has to look up the link syntax every single time2016-02-02
- ReStructuredText syntax is hard to write and read2015-03-25
- ReST syntax fights the writer on small things, requiring constant doc lookups2013-04-26