A ReStructuredText Primer =========================

:Author: Richard Jones :Version: $Revision: 1.17 $ :Copyright: This document has been placed in the public domain.

.. contents::

The text below contains links that look like "(quickref)". These are relative links that point to the Quick reStructuredText_ user reference. If these links don't work, please refer to the `master quick reference`_ document.

.. _Quick reStructuredText: quickref.html .. _master quick reference:

Structure


From the outset, let me say that "Structured Text" is probably a bit of a misnomer. It's more like "Relaxed Text" that uses certain consistent patterns. These patterns are interpreted by a HTML converter to produce "Very Structured Text" that can be used by a web browser.

The most basic pattern recognised is a **paragraph** (quickref). That's a chunk of text that is separated by blank lines (one is enough). Paragraphs must have the same indentation -- that is, line up at their left edge. Paragraphs that start indented will result in indented quote paragraphs. For example::

Results in:

quickref.html#paragraphs

Text styles


(quickref)

quickref.html#inline-markup

Inside paragraphs and other bodies of text, you may additionally mark text for *italics* with "*italics*" or **bold** with "**bold**".

If you want something to appear as a fixed-space literal, use "double back-quotes". Note that no further fiddling is done inside the double back-quotes -- so asterisks "*" etc. are left alone.

If you find that you want to use one of the "special" characters in text, it will generally be OK -- reStructuredText is pretty smart. For example, this * asterisk is handled just fine. If you actually want text \*surrounded by asterisks* to **not** be italicised, then you need to indicate that the asterisk is not special. You do this by placing a backslash just before it, like so "\*" (quickref), or by enclosing it in double back-quotes (inline literals), like this::

quickref.html#escaping

Lists


Lists of items come in three main flavours: **enumerated**, **bulleted** and **definitions**. In all list cases, you may have as many paragraphs, sublists, etc. as you want, as long as the left-hand side of the paragraph or whatever aligns with the first line of text in the list item.

Lists must always start a new paragraph -- that is, they must appear after a blank line.

**enumerated** lists (numbers, letters or roman numerals; quickref)

**bulleted** lists (quickref)

**definition** lists (quickref)

Preformatting (code samples)


(quickref)

quickref.html#literal-blocks

To just include a chunk of preformatted, never-to-be-fiddled-with text, finish the prior paragraph with "::". The preformatted block is finished when the text falls back to the same indentation level as a paragraph prior to the preformatted block. For example::

An example
  • Whitespace, newlines, blank lines, and all kinds of markup
    • (like *this* or \this) is preserved by literal blocks.
  • Lookie here, I've dropped an indentation level (but not far enough)
no more example

Results in:

An example
  • Whitespace, newlines, blank lines, and all kinds of markup
    • (like *this* or \this) is preserved by literal blocks.
  • Lookie here, I've dropped an indentation level (but not far enough)
no more example

Note that if a paragraph consists only of "::", then it's removed from the output::

  • This is preformatted text, and the last "::" paragraph is removed

Results in:

::

Sections


(quickref)

quickref.html#section-structure

To break longer text up into sections, you use **section headers**. These are a single line of text (one or more words) with adornment: an underline alone, or an underline and an overline together, in dashes "


", equals "======", tildes "~~~~~~" or any of the non-alphanumeric characters = -  : ' " ~ ^ _ * + # < >` that you feel comfortable with. An underline-only adornment is distinct from an overline-and-underline adornment using the same character. The underline/overline must be at least as long as the title text. Be consistent, since all sections marked with the same adornment style are deemed to be at the same level::



This results in the following structure, illustrated by simplified pseudo-XML::

(Pseudo-XML uses indentation for nesting and has no end-tags. It's not possible to show actual processed output, as in the other examples, because sections cannot exist inside block quotes. For a concrete example, compare the section structure of this document's source text and processed output.)

Note that section headers are available as link targets, just using their name. To link to the Lists_ heading, I write "Lists_". If the heading has a space in it like text styles_, we need to quote the heading "text styles_".

Document Title / Subtitle `

The title of the whole document is distinct from section titles and may be formatted somewhat differently (e.g. the HTML writer by default shows it as a centered heading).

To indicate the document title in reStructuredText, use a unique adornment style at the beginning of the document. To indicate the document subtitle, use another unique adornment style immediately after the document title. For example::



Note that "Document Title" and "Section Title" above both use equals signs, but are distict and unrelated styles. The text of overline-and-underlined titles (but not underlined-only) may be inset for aesthetics.

Images


(quickref)

quickref.html#directives

To include an image in your document, you use the the image directive. For example::

.. image
images/biohazard.png

results in:

.. image:: images/biohazard.png

The images/biohazard.png part indicates the filename of the image you wish to appear in the document. There's no restriction placed on the image (format, size etc). If the image is to appear in HTML and you wish to supply additional information, you may::

.. image
images/biohazard.png
  • :height: 100 :width: 200 :scale: 50 :alt: alternate text

See the full image directive documentation for more info.

../../ref/rst/directives.html ../../ref/rst/directives.html#images

What Next?


This primer introduces the most common features of reStructuredText, but there are a lot more to explore. The Quick reStructuredText_ user reference is a good place to go next. For complete details, the reStructuredText Markup Specification_ is the place to go [#]_.

Users who have questions or need assistance with Docutils or reStructuredText should post a message_ to the `Docutils-Users mailing list_.  The Docutils project web site`_ has more information.

.. [#] If that relative link doesn't work, try the master document:

.. _reStructuredText Markup Specification:

.. _post a message: mailto:docutils-users@lists.sourceforge.net .. _Docutils-Users mailing list:

.. _Docutils project web site: http://docutils.sourceforge.net/

WikiSandBox/test (last edited 2008-07-29 20:53:40 by BorisKocherov)