1 A ReStructuredText Primer
2 =========================
6 :Copyright: This document has been placed in the public domain.
11 The text below contains links that look like "(quickref__)". These
12 are relative links that point to the `Quick reStructuredText`_ user
13 reference. If these links don't work, please refer to the `master
14 quick reference`_ document.
17 .. _Quick reStructuredText: quickref.html
18 .. _master quick reference:
19 http://docutils.sourceforge.net/docs/user/rst/quickref.html
21 .. Note:: This document is an informal introduction to
22 reStructuredText. The `What Next?`_ section below has links to
23 further resources, including a formal reference.
29 From the outset, let me say that "Structured Text" is probably a bit
30 of a misnomer. It's more like "Relaxed Text" that uses certain
31 consistent patterns. These patterns are interpreted by a HTML
32 converter to produce "Very Structured Text" that can be used by a web
35 The most basic pattern recognised is a **paragraph** (quickref__).
36 That's a chunk of text that is separated by blank lines (one is
37 enough). Paragraphs must have the same indentation -- that is, line
38 up at their left edge. Paragraphs that start indented will result in
39 indented quote paragraphs. For example::
41 This is a paragraph. It's quite
44 This paragraph will result in an indented block of
45 text, typically used for quoting other text.
51 This is a paragraph. It's quite
54 This paragraph will result in an indented block of
55 text, typically used for quoting other text.
59 __ quickref.html#paragraphs
67 __ quickref.html#inline-markup
69 Inside paragraphs and other bodies of text, you may additionally mark
70 text for *italics* with "``*italics*``" or **bold** with
71 "``**bold**``". This is called "inline markup".
73 If you want something to appear as a fixed-space literal, use
74 "````double back-quotes````". Note that no further fiddling is done
75 inside the double back-quotes -- so asterisks "``*``" etc. are left
78 If you find that you want to use one of the "special" characters in
79 text, it will generally be OK -- reStructuredText is pretty smart.
80 For example, this lone asterisk * is handled just fine, as is the
81 asterisk in this equation: 5*6=30. If you actually
82 want text \*surrounded by asterisks* to **not** be italicised, then
83 you need to indicate that the asterisk is not special. You do this by
84 placing a backslash just before it, like so "``\*``" (quickref__), or
85 by enclosing it in double back-quotes (inline literals), like this::
89 __ quickref.html#escaping
91 .. Tip:: Think of inline markup as a form of (parentheses) and use it
92 the same way: immediately before and after the text being marked
93 up. Inline markup by itself (surrounded by whitespace) or in the
94 middle of a word won't be recognized. See the `markup spec`__ for
97 __ ../../ref/rst/restructuredtext.html#inline-markup
103 Lists of items come in three main flavours: **enumerated**,
104 **bulleted** and **definitions**. In all list cases, you may have as
105 many paragraphs, sublists, etc. as you want, as long as the left-hand
106 side of the paragraph or whatever aligns with the first line of text
109 Lists must always start a new paragraph -- that is, they must appear
112 **enumerated** lists (numbers, letters or roman numerals; quickref__)
113 __ quickref.html#enumerated-lists
115 Start a line off with a number or letter followed by a period ".",
116 right bracket ")" or surrounded by brackets "( )" -- whatever you're
117 comfortable with. All of the following forms are recognised::
121 A. upper-case letters
122 and it goes over many lines
124 with two paragraphs and all!
126 a. lower-case letters
128 3. with a sub-list starting at a different number
129 4. make sure the numbers are in the correct sequence though!
131 I. upper-case roman numerals
133 i. lower-case roman numerals
139 Results in (note: the different enumerated list styles are not
140 always supported by every web browser, so you may not get the full
145 A. upper-case letters
146 and it goes over many lines
148 with two paragraphs and all!
150 a. lower-case letters
152 3. with a sub-list starting at a different number
153 4. make sure the numbers are in the correct sequence though!
155 I. upper-case roman numerals
157 i. lower-case roman numerals
163 **bulleted** lists (quickref__)
164 __ quickref.html#bullet-lists
166 Just like enumerated lists, start the line off with a bullet point
167 character - either "-", "+" or "*"::
169 * a bullet point using "*"
171 - a sub-list using "-"
173 + yet another sub-list
179 * a bullet point using "*"
181 - a sub-list using "-"
183 + yet another sub-list
187 **definition** lists (quickref__)
188 __ quickref.html#definition-lists
190 Unlike the other two, the definition lists consist of a term, and
191 the definition of that term. The format of a definition list is::
194 Definition lists associate a term with a definition.
197 The term is a one-line phrase, and the definition is one or more
198 paragraphs or body elements, indented relative to the term.
199 Blank lines are not allowed between term and definition.
204 Definition lists associate a term with a definition.
207 The term is a one-line phrase, and the definition is one or more
208 paragraphs or body elements, indented relative to the term.
209 Blank lines are not allowed between term and definition.
212 Preformatting (code samples)
213 ----------------------------
216 __ quickref.html#literal-blocks
218 To just include a chunk of preformatted, never-to-be-fiddled-with
219 text, finish the prior paragraph with "``::``". The preformatted
220 block is finished when the text falls back to the same indentation
221 level as a paragraph prior to the preformatted block. For example::
225 Whitespace, newlines, blank lines, and all kinds of markup
226 (like *this* or \this) is preserved by literal blocks.
227 Lookie here, I've dropped an indentation level
236 Whitespace, newlines, blank lines, and all kinds of markup
237 (like *this* or \this) is preserved by literal blocks.
238 Lookie here, I've dropped an indentation level
243 Note that if a paragraph consists only of "``::``", then it's removed
248 This is preformatted text, and the
249 last "::" paragraph is removed
255 This is preformatted text, and the
256 last "::" paragraph is removed
264 __ quickref.html#section-structure
266 To break longer text up into sections, you use **section headers**.
267 These are a single line of text (one or more words) with adornment: an
268 underline alone, or an underline and an overline together, in dashes
269 "``-----``", equals "``======``", tildes "``~~~~~~``" or any of the
270 non-alphanumeric characters ``= - ` : ' " ~ ^ _ * + # < >`` that you
271 feel comfortable with. An underline-only adornment is distinct from
272 an overline-and-underline adornment using the same character. The
273 underline/overline must be at least as long as the title text. Be
274 consistent, since all sections marked with the same adornment style
275 are deemed to be at the same level::
283 Subsection 1.1.1 Title
284 ~~~~~~~~~~~~~~~~~~~~~~
292 This results in the following structure, illustrated by simplified
303 Subsection 1.1.1 Title
311 (Pseudo-XML uses indentation for nesting and has no end-tags. It's
312 not possible to show actual processed output, as in the other
313 examples, because sections cannot exist inside block quotes. For a
314 concrete example, compare the section structure of this document's
315 source text and processed output.)
317 Note that section headers are available as link targets, just using
318 their name. To link to the Lists_ heading, I write "``Lists_``". If
319 the heading has a space in it like `text styles`_, we need to quote
320 the heading "```text styles`_``".
323 Document Title / Subtitle
324 `````````````````````````
326 The title of the whole document is distinct from section titles and
327 may be formatted somewhat differently (e.g. the HTML writer by default
328 shows it as a centered heading).
330 To indicate the document title in reStructuredText, use a unique adornment
331 style at the beginning of the document. To indicate the document subtitle,
332 use another unique adornment style immediately after the document title. For
347 Note that "Document Title" and "Section Title" above both use equals
348 signs, but are distict and unrelated styles. The text of
349 overline-and-underlined titles (but not underlined-only) may be inset
358 __ quickref.html#directives
360 To include an image in your document, you use the the ``image`` directive__.
363 .. image:: images/biohazard.png
367 .. image:: images/biohazard.png
369 The ``images/biohazard.png`` part indicates the filename of the image
370 you wish to appear in the document. There's no restriction placed on
371 the image (format, size etc). If the image is to appear in HTML and
372 you wish to supply additional information, you may::
374 .. image:: images/biohazard.png
380 See the full `image directive documentation`__ for more info.
382 __ ../../ref/rst/directives.html
383 __ ../../ref/rst/directives.html#images
389 This primer introduces the most common features of reStructuredText,
390 but there are a lot more to explore. The `Quick reStructuredText`_
391 user reference is a good place to go next. For complete details, the
392 `reStructuredText Markup Specification`_ is the place to go [#]_.
394 Users who have questions or need assistance with Docutils or
395 reStructuredText should post a message to the Docutils-users_ mailing
398 .. [#] If that relative link doesn't work, try the master document:
399 http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html.
401 .. _reStructuredText Markup Specification:
402 ../../ref/rst/restructuredtext.html
403 .. _Docutils-users: ../mailing-lists.html#docutils-users
404 .. _Docutils project web site: http://docutils.sourceforge.net/