Menu
Home
People
Places
Arts
History
Plants & Animals
Science
Life & Culture
Technology
Reference.org
reStructuredText
open-in-new
<h2 id="history">History</h2> <p>reStructuredText evolved from an earlier lightweight markup language called StructuredText<a class="footnote-ref" id="fnref:2" href="#fn:2"><sup>2</sup></a> (developed by <a href="/facts/Zope/QUkJsd03">Zope</a>). There were a number of problems with StructuredText, and reST was developed to address them.<a class="footnote-ref" id="fnref:3" href="#fn:3"><sup>3</sup></a> The name reStructuredText was chosen to indicate that reST is a "revised, reworked, and reinterpreted StructuredText."<a class="footnote-ref" id="fnref:4" href="#fn:4"><sup>4</sup></a> </p><p>Parts of the reST syntax were inspired by the <a href="/facts/Setext/cHfAvGN7">Setext</a> language from the early 1990s. Elements of the common <a href="/facts/Email/6pD9GLtI">RFC822 Internet Message Format</a> and <a href="/facts/Javadoc/pm72Xvlf">Javadoc</a> formats were also considered for inclusion in the design.<a class="footnote-ref" id="fnref:5" href="#fn:5"><sup>5</sup></a> </p><p>reStructuredText was first released in June 2001.<a class="footnote-ref" id="fnref:6" href="#fn:6"><sup>6</sup></a> It began to see significant use in the Python community in 2002.<a class="footnote-ref" id="fnref:7" href="#fn:7"><sup>7</sup></a> </p> <h2 id="reference-implementation">Reference implementation</h2> <p>The reference implementation of the reST <a href="/facts/Parser/nRKB01S3">parser</a> is a component of the Docutils text processing framework in the <a href="/facts/Python_(programming_language)/YbuGqofa">Python programming language</a>, but other parsers are available. </p><p>The Docutils project has not registered any <a href="/facts/Media_type/A31N5Fwj">MIME type</a> for reStructuredText nor designated any unregistered MIME type as official, but documents the MIME type text/x-rst as in <i>de facto</i> use by, for example, the build system for the Python website.<a class="footnote-ref" id="fnref:8" href="#fn:8"><sup>8</sup></a> The same MIME type is used in the <a href="/facts/Freedesktop.org/qGlctGYA">freedesktop.org</a> file type database used by <a href="/facts/Desktop_environment/VXBpMWnG">desktop environments</a> on <a href="/facts/Linux_desktop/9FvCKSTq">Linux</a>.<a class="footnote-ref" id="fnref:9" href="#fn:9"><sup>9</sup></a> Another MIME type, text/prs.fallenstein.rst, was registered as a <a href="/facts/Media_type/A31N5Fwj">vanity MIME type</a> by a third party in 2003 to represent reStructuredText, and remains the only <a href="/facts/IANA/b6MlP6zQ">IANA</a>-registered MIME type for reStructuredText,<a class="footnote-ref" id="fnref:10" href="#fn:10"><sup>10</sup></a> although it is not acknowledged as such by the Docutils project.<a class="footnote-ref" id="fnref:11" href="#fn:11"><sup>11</sup></a> </p> <h2 id="applications">Applications</h2> <p>reStructuredText is commonly used for technical documentation, for example, in documentation of Python libraries.<a class="footnote-ref" id="fnref:12" href="#fn:12"><sup>12</sup></a> However, it is suitable for a wide range of texts. </p><p>Since 2008, reST has been a core component of Python's <a href="/facts/Sphinx_(documentation_generator)/IuRGEnRK">Sphinx</a> document generation system. </p><p><a href="/facts/Trac/vYhkdoA3">Trac</a> also supports reStructuredText,<a class="footnote-ref" id="fnref:13" href="#fn:13"><sup>13</sup></a> as do <a href="/facts/GitHub/n1hNCsc3">GitHub</a> and <a href="/facts/Bitbucket/Roe2ucoa">Bitbucket</a>. </p><p>In 2011, <a href="/facts/Distributed_Proofreaders/1FzTqkGI">Distributed Proofreaders</a>, which prepared texts for <a href="/facts/Project_Gutenberg/2l0R6GgQ">Project Gutenberg</a>, was considering adoption of reST as a basic format from which other ebook formats could be generated.<a class="footnote-ref" id="fnref:14" href="#fn:14"><sup>14</sup></a>[<i>needs update</i>] </p><p>In July 2016 the <a href="/facts/Linux_kernel/dlkduHuA">Linux kernel</a> project decided to transition from <a href="/facts/DocBook/8RpRVfCQ">DocBook</a> based documentation to reStructuredText and the <a href="/facts/Sphinx_(documentation_generator)/IuRGEnRK">Sphinx</a> toolchain.<a class="footnote-ref" id="fnref:15" href="#fn:15"><sup>15</sup></a><a class="footnote-ref" id="fnref:16" href="#fn:16"><sup>16</sup></a>[<i>circular reference</i>] </p><p>The software build tool <a href="/facts/CMake/ICCBEBKF">CMake</a> switched from a custom markup language to reStructuredText in version 3.0 for its documentation.<a class="footnote-ref" id="fnref:17" href="#fn:17"><sup>17</sup></a> </p> <h2 id="examples">Examples</h2> <table><tbody><tr><th>Text using rST syntax</th><th>Corresponding HTML produced by an rST processor</th><th>Text viewed in a browser</th></tr><tr><td>================Document Heading================Heading=======Sub-heading-----------Paragraphs are separated by a blank line.</td><td><h1>Document Heading</h1><h2>Heading</h2><h3>Sub-heading</h3><p>Paragraphs are separatedby a blank line.</p></td><td>Document HeadingHeadingSub-heading<p>Paragraphs are separatedby a blank line.</p></td></tr><tr><td>Text attributes *emphasis*, **strong emphasis**, ``monospace``.Horizontal rule:----</td><td><p>Text attributes <em>emphasis</em>,<strong>strong emphasis</strong>, <code>monospace</code>.</p><p>Horizontal rule:</p><hr /></td><td>Text attributes <i>emphasis</i>,strong emphasis, monospace.<p>Horizontal rule:</p></td></tr><tr><td>Bullet list:* apples* oranges* pearsNumbered list:1. lather2. rinse3. repeatNested lists:1. fruits * apple * banana2. vegetables * carrot * broccoli</td><td><p>Bullet list:</p><ul> <li>apples</li> <li>oranges</li> <li>pears</li></ul><p>Numbered list:</p><ol> <li>lather</li> <li>rinse</li> <li>repeat</li></ol><p>Nested lists:</p><ol> <li>fruits <ul> <li>apple</li> <li>banana</li> </ul> </li> <li>vegetables <ul> <li>carrot</li> <li>broccoli</li> </ul> </li></ol></td><td>Bullet list:<ul><li>apples</li><li>oranges</li><li>pears</li></ul><p>Numbered list:</p><ol><li>lather</li><li>rinse</li><li>repeat</li></ol><p>Nested lists:</p><ol><li>fruits<ul><li>apple</li><li>banana</li></ul></li><li>vegetables<ul><li>carrot</li><li>broccoli</li></ul></li></ol></td></tr><tr><td>An `example <http://example.com>`_... image:: Icon-pictures.png :alt: ImageIf text is indented, it is treated as a block quotation: Should array indices start at 0 or 1? My suggested compromise of 0.5 was rejected without, I thought, proper consideration. -- Stan Kelly-BootlereST uses :: at the end of the paragraph prior to a pre-formatted code block:: Y = lambda f: (lambda x: f(x(x)))(lambda x: f(x(x)))| Multi-line text can| span in tables| with a pipe character.</td><td><p>An <a href="http://example.com">example</a>.</p><p><img alt="Image"src="Icon-pictures.png" /></p><p>If text is indented, it is treated as a block quotation, and the final attribution line is handled automatically:</p><blockquote>Should array indices start at 0 or 1?My suggested compromise of 0.5 was rejected without, I thought, proper consideration.-- Stan Kelly-Bootle</blockquote><p>reST uses :: at the end of the paragraph prior to a pre-formatted code block:</p><pre class="literal-block">Y = lambda f: (lambda x: f(x(x)))(lambda x: f(x(x)))</pre><p>Multi-line text can<br/>span in tables<br/>with a pipe character.</p></td><td>An <a href="http://example.com/">example</a>.<p>If text is indented, it is treated as a block quotation, and the final attribution line is handled automatically:</p><blockquote><p>Should array indices start at 0 or 1?My suggested compromise of 0.5 was rejected without, I thought, proper consideration.</p><p>-- Stan Kelly-Bootle</p></blockquote><p>reST uses :: at the end of the paragraph prior to a pre-formatted code block:</p>Y = lambda f: (lambda x: f(x(x)))(lambda x: f(x(x)))<p>Multi-line text canspan in tableswith a pipe character.</p></td></tr></tbody></table> <h2 id="see-also">See also</h2> <ul><li><a href="/facts/Comparison_of_document_markup_languages/6BQwzvLU">Comparison of document markup languages</a></li> <li><a href="/facts/Comparison_of_documentation_generators/xLydRU5z">Comparison of documentation generators</a></li> <li><a href="/facts/Comparison_of_note-taking_software/27dWExtb">Comparison of note-taking software</a></li></ul> <h2 id="external-links">External links</h2> <ul><li><a href="https://docutils.sourceforge.io/rst.html">Official reStructuredText website with reference pages</a></li></ul> <h2 id="references">References</h2> <ol> <li id="fn:1"><p>Mertz, David (2003-02-01). "XML Matters: reStructuredText". IBM developerWorks. Retrieved 2016-10-05. <a href="https://www.ibm.com/developerworks/library/x-matters24/" target="_blank">https://www.ibm.com/developerworks/library/x-matters24/</a> <a href="#fnref:1" class="footnote-back-ref">↩</a></p></li> <li id="fn:2"><p>"zope.structuredtext Documentation". Read the Docs. Retrieved 2022-08-16. <a href="https://zopestructuredtext.readthedocs.io/en/latest/" target="_blank">https://zopestructuredtext.readthedocs.io/en/latest/</a> <a href="#fnref:2" class="footnote-back-ref">↩</a></p></li> <li id="fn:3"><p>Goodger, David (2016-05-24). "Problems With StructuredText". Docutils Project. Retrieved 2022-08-16. <a href="https://docutils.sourceforge.io/docs/dev/rst/problems.html" target="_blank">https://docutils.sourceforge.io/docs/dev/rst/problems.html</a> <a href="#fnref:3" class="footnote-back-ref">↩</a></p></li> <li id="fn:4"><p>Goodger, David (2016-02-26). "Docutils FAQ (Frequently Asked Questions)". Docutils Project. Retrieved 2016-10-05. <a href="http://docutils.sourceforge.net/FAQ.html#why-is-it-called-restructuredtext" target="_blank">http://docutils.sourceforge.net/FAQ.html#why-is-it-called-restructuredtext</a> <a href="#fnref:4" class="footnote-back-ref">↩</a></p></li> <li id="fn:5"><p>Goodger, David (2022-04-02). "A Record of reStructuredText Syntax Alternatives". docutils.sourceforge.io. Docutils Project. Retrieved 2022-08-16. <a href="https://docutils.sourceforge.io/docs/dev/rst/alternatives.html" target="_blank">https://docutils.sourceforge.io/docs/dev/rst/alternatives.html</a> <a href="#fnref:5" class="footnote-back-ref">↩</a></p></li> <li id="fn:6"><p>"Project: reStructuredText - File List". SourceForge. Archived from the original on 19 October 2001. Retrieved 5 February 2023. <a href="https://sourceforge.net/projects/structuredtext/files/restructuredtext/" target="_blank">https://sourceforge.net/projects/structuredtext/files/restructuredtext/</a> <a href="#fnref:6" class="footnote-back-ref">↩</a></p></li> <li id="fn:7"><p>"Introduction to reStructuredText". Write The Docs. Retrieved 2022-06-25. <a href="https://www.writethedocs.org/guide/writing/reStructuredText/" target="_blank">https://www.writethedocs.org/guide/writing/reStructuredText/</a> <a href="#fnref:7" class="footnote-back-ref">↩</a></p></li> <li id="fn:8"><p>"What's the official MIME type for reStructuredText data? in Docutils FAQ". Docutils Project. Retrieved 2017-12-20. <a href="http://docutils.sourceforge.net/FAQ.html#what-s-the-official-mime-type-for-restructuredtext-data" target="_blank">http://docutils.sourceforge.net/FAQ.html#what-s-the-official-mime-type-for-restructuredtext-data</a> <a href="#fnref:8" class="footnote-back-ref">↩</a></p></li> <li id="fn:9"><p>"freedesktop.org.xml.in". shared-mime-info. freedesktop.org. <a href="https://gitlab.freedesktop.org/xdg/shared-mime-info/-/blob/815b520eb01992a05d41a5434f1227a8be101e15/data/freedesktop.org.xml.in#L6708" target="_blank">https://gitlab.freedesktop.org/xdg/shared-mime-info/-/blob/815b520eb01992a05d41a5434f1227a8be101e15/data/freedesktop.org.xml.in#L6708</a> <a href="#fnref:9" class="footnote-back-ref">↩</a></p></li> <li id="fn:10"><p>Fallenstein, Benja (2003-10-02). "text/prs.fallenstein.rst". IANA. ReStructuredText was designed and implemented by David Goodger, not by the registrant of this media type. The registrant just happened to have need of a registered media type for it. […] Change control for this registration is currently with Benja Fallenstein. (If anybody more intimately involved with ReStructuredText wants to take it over, it will be surrendered gladly.) <a href="https://www.iana.org/assignments/media-types/text/prs.fallenstein.rst" target="_blank">https://www.iana.org/assignments/media-types/text/prs.fallenstein.rst</a> <a href="#fnref:10" class="footnote-back-ref">↩</a></p></li> <li id="fn:11"><p>"What's the official MIME type for reStructuredText data? in Docutils FAQ". Docutils Project. Retrieved 2017-12-20. <a href="http://docutils.sourceforge.net/FAQ.html#what-s-the-official-mime-type-for-restructuredtext-data" target="_blank">http://docutils.sourceforge.net/FAQ.html#what-s-the-official-mime-type-for-restructuredtext-data</a> <a href="#fnref:11" class="footnote-back-ref">↩</a></p></li> <li id="fn:12"><p>Goodger, David (2002-04-02). "PEP 287 -- reStructuredText Docstring Format". Python Software Foundation. Retrieved 2016-10-05. <a href="https://www.python.org/dev/peps/pep-0287/" target="_blank">https://www.python.org/dev/peps/pep-0287/</a> <a href="#fnref:12" class="footnote-back-ref">↩</a></p></li> <li id="fn:13"><p>"reStructuredText Support in Trac". Trac. 2016-09-13. Retrieved 2016-10-05. <a href="https://trac.edgewall.org/wiki/WikiRestructuredText" target="_blank">https://trac.edgewall.org/wiki/WikiRestructuredText</a> <a href="#fnref:13" class="footnote-back-ref">↩</a></p></li> <li id="fn:14"><p>Newby, Greg (2011-01-08). "Minutes of 2010 December 11 meeting". Distributed Proofreaders. Retrieved 2011-01-08. <a href="http://www.pgdp.net/phpBB2/viewtopic.php?t=44456" target="_blank">http://www.pgdp.net/phpBB2/viewtopic.php?t=44456</a> <a href="#fnref:14" class="footnote-back-ref">↩</a></p></li> <li id="fn:15"><p>"Kernel documentation with Sphinx, part 1: how we got here". LWN.net. 2016-07-06. Retrieved 2016-10-27. <a href="http://lwn.net/Articles/692704/" target="_blank">http://lwn.net/Articles/692704/</a> <a href="#fnref:15" class="footnote-back-ref">↩</a></p></li> <li id="fn:16"><p>"Sphinx. Linux kernel". Wikipedia. 2024-04-02. Retrieved 2024-04-02. <a href="https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)#Linux_kernel" target="_blank">https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)#Linux_kernel</a> <a href="#fnref:16" class="footnote-back-ref">↩</a></p></li> <li id="fn:17"><p>"CMake 3.0.0 Release Notes". Kitware, Inc. 2014-06-10. Retrieved 2016-10-05. <a href="https://cmake.org/cmake/help/v3.0/release/3.0.0.html" target="_blank">https://cmake.org/cmake/help/v3.0/release/3.0.0.html</a> <a href="#fnref:17" class="footnote-back-ref">↩</a></p></li> </ol>