reStructuredText

This article is a stub. You can help the IndieWeb wiki by expanding it.

reStructuredText (AKA ReST) is a plaintext-based markup syntax and parser system in use by at least one IndieWeb community member for a personal site or IndieWeb service. It is similar to Markdown, but has a more formal specification.

More info: https://www.docutils.org/docs/ref/rst/introduction.html
Syntax reference summary: https://www.docutils.org/docs/user/rst/quickref.html

IndieWeb Examples

This section is a stub. You can help the IndieWebCamp wiki by expanding it.

Ryan Barrett

Ryan Barrett uses Read the Docs to auto-generate docs for most of his open source projects like granary, Bridgy, etc. He uses pandoc to convert the source docs from Markdown to ReST, which then gets fed into Sphinx to create the final HTML docs.

Features

Extendable through directives and roles

Unlike most lightweight markup language such as Markdown, ReST has official syntax support for extensions through roles (inline text) and directives (blocks). This allows new use-case or product specific transformations to be introduced.

Example use-cases:

Text marked up with :indieweb:`reStructuredText` might be transformed into a link to this page on the IndieWeb wiki.
A line containing only .. twitter:: https://twitter.com/indiewebcamp/status/1667294256959225856 might embed the This Week in the IndieWeb Twitter post.

Parsers that do not have these extensions will still be able to gracefully fallback (or report errors) as this is part of the ReST syntax.

How to support extensions in different parsers:

Python: docutils
- Creating reStructuredText Interpreted Text Roles
- Creating reStructuredText Directives
PHP: Doctrine RST Parser
- Custom Directives

Criticisms

Python Monoculture

Summary: There is difficulty parsing reStructuredText outside of Python or finding any resources to do so.

Martijn van der Ven noted in chat https://chat.indieweb.org/dev/2024-01-03/1704267398609300:

looked at ReST at different times. I always thought it would be easier to use as a base type than Markdown because its extensibility through tags (.. tag::). But always ran into trouble parsing it with anything other than Python :(

Martijn van der Ven:
- It always felt like there was a monoculture problem with ReST. There is a big ecosystem in Python land where everyone depends on the docutils package.
- Lots of tools will shell out to Python docutils to handle the parsing. One of the few WordPress plugins for ReST required installing docutils on the server first.
- It is extremely hard to even discover parsers for other languages. Searching npm (JavaScript package manager) for “restructuredtext” turns up several plugin-like libraries first such as gitbook-restructuredtext and hexo-renderer-restructuredtext (both shell out to run Python docutils’ rst2html) before ending up at restructured. restructured is an actual JavaScript based parser, but not updated in many years with limited support for the ReST syntax.
- There does not seem to be a public list of parsers nor any sort of compatibility comparison.

More Complicated Than Markdown

capjamesg noted in chat https://chat.indieweb.org/dev/2024-01-03#t1704304887461200:

I don’t like ReST 😅
Maybe it is the “it is the thing I don’t know” effect at play.
But it felt even more complicated than markdown.