reStructuredText – what-you-see-is-what-you-get plaintext markup language

Last Updated on March 19, 2024

reStructuredText (often abbreviated as reST) is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. It’s designed to be a simple, unobtrusive markup language.

This lightweight markup language is useful for in-line program documentation (such as Python docstrings), technical documentation, for quickly creating simple web pages, as well as standalone documents.

reStructuredText is part of the Docutils project. The purpose of the project is to create a set of tools for processing reStructuredText documentation into useful formats, such as HTML, LaTeX, ODT or Unix manpages. Docutils can extract comments and information from Python programs, and format them into various forms of useful program documentation.

All reST files use an indentation of 3 spaces; no tabs are allowed. The maximum line length is 80 characters for normal text, but tables, deeply indented code samples and long links may extend beyond that.

The reference implementation of the reST parser is a component of the Docutils text processing framework.

The name of the language derives from two other markup languages, Setext and StructuredText.

reStructuredText is the default plaintext markup language used by Sphinx.

Ways to Learn reStructuredText

The RestructuredText Book Documentation

By (Daniel Greenfeld, Eric Holscher PDF; 27 pages)

This is a syntax guide designed to provide very clear, understandable examples and tutorials of reST usage. It borrows information from several sources.

The incomplete guide covers the basics of the language, and block quotes. It then offers a tutorial and guide to Sphinx. A few sections are yet to be published.

Cheat Sheet – a refresher for this markup language.
A ReStructuredText Primer – an informal introduction to reST.


Readable and simple to learn syntax
Syntax can seem strange at times

Popular in the Python community
Confusing output from compiler

Often used for technical documentation
Limited support from editors and other types of software

Extensibility - provides standard extension mechanisms called directives and roles
Not as rich as DocBook XML

Designed to offer most of the same features as LaTeX

Useful Software for reST

pandoc – converts files from one markup format into another.
Docutils – an open-source text processing system for processing plaintext documentation into useful formats, such as HTML, LaTeX, man-pages, open-document or XML. It includes reStructuredText.
Formiko – a reStructuredText and MarkDown editor and live previewer. It’s written in Python with Gtk3, GtkSourceView and Webkit2.
Pelican – a static site generator, written in Python, that requires no database or server-side logic.

Project Page

Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Inline Feedbacks
View all comments