1
A ReStructuredText Primer
2
=========================
5
:Version: $Revision: 1.11 $
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/rst/quickref.html
25
From the outset, let me say that "Structured Text" is probably a bit
26
of a misnomer. It's more like "Relaxed Text" that uses certain
27
consistent patterns. These patterns are interpreted by a HTML
28
converter to produce "Very Structured Text" that can be used by a web
31
The most basic pattern recognised is a **paragraph** (quickref__).
32
That's a chunk of text that is separated by blank lines (one is
33
enough). Paragraphs must have the same indentation -- that is, line
34
up at their left edge. Paragraphs that start indented will result in
35
indented quote paragraphs. For example::
37
This is a paragraph. It's quite
40
This paragraph will result in an indented block of
41
text, typically used for quoting other text.
47
This is a paragraph. It's quite
50
This paragraph will result in an indented block of
51
text, typically used for quoting other text.
55
__ quickref.html#paragraphs
62
__ quickref.html#inline-markup
64
Inside paragraphs and other bodies of text, you may additionally mark
65
text for *italics* with "``*italics*``" or **bold** with
68
If you want something to appear as a fixed-space literal, use
69
"````double back-quotes````". Note that no further fiddling is done
70
inside the double back-quotes -- so asterisks "``*``" etc. are left
73
If you find that you want to use one of the "special" characters in
74
text, it will generally be OK -- reStructuredText is pretty smart.
75
For example, this * asterisk is handled just fine. If you actually
76
want text \*surrounded by asterisks* to **not** be italicised, then
77
you need to indicate that the asterisk is not special. You do this by
78
placing a backslash just before it, like so "``\*``" (quickref__), or
79
by enclosing it in double back-quotes (inline literals), like this::
83
__ quickref.html#escaping
88
Lists of items come in three main flavours: **enumerated**,
89
**bulleted** and **definitions**. In all list cases, you may have as
90
many paragraphs, sublists, etc. as you want, as long as the left-hand
91
side of the paragraph or whatever aligns with the first line of text
94
Lists must always start a new paragraph -- that is, they must appear
97
**enumerated** lists (numbers, letters or roman numerals; quickref__)
98
__ quickref.html#enumerated-lists
100
Start a line off with a number or letter followed by a period ".",
101
right bracket ")" or surrounded by brackets "( )" -- whatever you're
102
comfortable with. All of the following forms are recognised::
106
A. upper-case letters
107
and it goes over many lines
109
with two paragraphs and all!
111
a. lower-case letters
113
3. with a sub-list starting at a different number
114
4. make sure the numbers are in the correct sequence though!
116
I. upper-case roman numerals
118
i. lower-case roman numerals
124
Results in (note: the different enumerated list styles are not
125
always supported by every web browser, so you may not get the full
130
A. upper-case letters
131
and it goes over many lines
133
with two paragraphs and all!
135
a. lower-case letters
137
3. with a sub-list starting at a different number
138
4. make sure the numbers are in the correct sequence though!
140
I. upper-case roman numerals
142
i. lower-case roman numerals
148
**bulleted** lists (quickref__)
149
__ quickref.html#bullet-lists
151
Just like enumerated lists, start the line off with a bullet point
152
character - either "-", "+" or "*"::
154
* a bullet point using "*"
156
- a sub-list using "-"
158
+ yet another sub-list
164
* a bullet point using "*"
166
- a sub-list using "-"
168
+ yet another sub-list
172
**definition** lists (quickref__)
173
__ quickref.html#definition-lists
175
Unlike the other two, the definition lists consist of a term, and
176
the definition of that term. The format of a definition list is::
179
Definition lists associate a term with a definition.
182
The term is a one-line phrase, and the definition is one or more
183
paragraphs or body elements, indented relative to the term.
184
Blank lines are not allowed between term and definition.
189
Definition lists associate a term with a definition.
192
The term is a one-line phrase, and the definition is one or more
193
paragraphs or body elements, indented relative to the term.
194
Blank lines are not allowed between term and definition.
196
Preformatting (code samples)
197
----------------------------
200
__ quickref.html#literal-blocks
202
To just include a chunk of preformatted, never-to-be-fiddled-with
203
text, finish the prior paragraph with "``::``". The preformatted
204
block is finished when the text falls back to the same indentation
205
level as a paragraph prior to the preformatted block. For example::
209
Whitespace, newlines, blank lines, and all kinds of markup
210
(like *this* or \this) is preserved by literal blocks.
211
Lookie here, I've dropped an indentation level
220
Whitespace, newlines, blank lines, and all kinds of markup
221
(like *this* or \this) is preserved by literal blocks.
222
Lookie here, I've dropped an indentation level
227
Note that if a paragraph consists only of "``::``", then it's removed
232
This is preformatted text, and the
233
last "::" paragraph is removed
239
This is preformatted text, and the
240
last "::" paragraph is removed
247
__ quickref.html#section-structure
249
To break longer text up into sections, you use **section headers**.
250
These are a single line of text (one or more words) with adornment: an
251
underline alone, or an overline and an overline together, in dashes
252
"``-----``", equals "``======``", tildes "``~~~~~~``" or any of the
253
non-alphanumeric characters ``= - ` : ' " ~ ^ _ * + # < >`` that you
254
feel comfortable with. An underline-only adornment is distinct from
255
an overline-and-underline adornment using the same character. The
256
underline/overline must be at least as long as the title text. Be
257
consistent, since all sections marked with the same adornment style
258
are deemed to be at the same level::
266
Subsection 1.1.1 Title
267
~~~~~~~~~~~~~~~~~~~~~~
275
This results in the following structure, illustrated by simplified
286
Subsection 1.1.1 Title
294
(Pseudo-XML uses indentation for nesting and has no end-tags. It's
295
not possible to show actual processed output, as in the other
296
examples, because sections cannot exist inside block quotes. For a
297
concrete example, compare the section structure of this document's
298
source text and processed output.)
300
Note that section headers are available as link targets, just using
301
their name. To link to the Lists_ heading, I write "``Lists_``". If
302
the heading has a space in it like `text styles`_, we need to quote
303
the heading "```text styles`_``".
305
To indicate the document title, use a unique adornment style at the
306
beginning of the document. To indicate the document subtitle, use
307
another unique adornment style immediately after the document title.
322
Note that "Document Title" and "Section Title" both use equals signs,
323
but are distict and unrelated styles. The text of
324
overline-and-underlined titles (but not underlined-only) may be inset
333
__ quickref.html#directives
335
To include an image in your document, you use the the ``image`` directive__.
338
.. image:: images/biohazard.png
342
.. image:: images/biohazard.png
344
The ``images/biohazard.png`` part indicates the filename of the image
345
you wish to appear in the document. There's no restriction placed on
346
the image (format, size etc). If the image is to appear in HTML and
347
you wish to supply additional information, you may::
349
.. image:: images/biohazard.png
355
See the full image directive documentation__ for more info.
357
__ ../../spec/rst/directives.html
358
__ ../../spec/rst/directives.html#images
364
This primer introduces the most common features of reStructuredText,
365
but there are a lot more to explore. The `Quick reStructuredText`_
366
user reference is a good place to go next. For complete details, the
367
`reStructuredText Markup Specification`_ is the place to go [#]_.
369
Users who have questions or need assistance with Docutils or
370
reStructuredText should `post a message`_ to the `Docutils-Users
371
mailing list`_. The `Docutils project web site`_ has more
374
.. [#] If that relative link doesn't work, try the master document:
375
http://docutils.sourceforge.net/spec/rst/reStructuredText.html.
377
.. _reStructuredText Markup Specification:
378
../../spec/rst/reStructuredText.html
379
.. _post a message: mailto:docutils-users@lists.sourceforge.net
380
.. _Docutils-Users mailing list:
381
http://lists.sourceforge.net/lists/listinfo/docutils-users
382
.. _Docutils project web site: http://docutils.sourceforge.net/
added
removed
docs/rst/quickstart.txt
