Inline Markup Section Structure

Inline markup allows words and phrases within text to have character styles (like italics and boldface) and functionality (like hyperlinks). Title
Title
*emphasis* emphasis =====
**strong emphasis** strong emphasis Titles are underlined (or over- and underlined) with a nonalphanumeric
Titles are underlined (or over- and underlined) with character at least as long as the text.
`interpreted text` The rendering and meaning of interpreted text is domain- or a nonalphanumeric character at least as long as the A lone top-level section is lifted up to be the document's title.
application-dependent. text. Any non-alphanumeric character can be used, but Python convention
``inline literal`` inline literal
is:
reference_ reference A lone top-level section is lifted up to be the
`phrase reference`_ document's title. • # with overline, for parts
phrase reference
• * with overline, for chapters
anonymous__ anonymous
Any non-alphanumeric character can be used, but • =, for sections
_`inline internal target` inline internal target Python convention is: • -, for subsections
|substitution reference| The result is substituted in from the substitution definition. • ^, for subsubsections
footnote reference [1]_ footnote reference 1 * ``#`` with overline, for parts • ", for paragraphs
* ``*`` with overline, for chapters
citation reference [CIT2002]_ citation reference CIT2002
* ``=``, for sections
http://docutils.sf.net/ http://docutils.sf.net/ * ``-``, for subsections
* ``^``, for subsubsections
Escaping with Backslashes * ``"``, for paragraphs

reStructuredText uses backslashes ("\") to override the special meaning given to markup characters and get the literal characters themselves. To get a
Blocks
literal backslash, use an escaped backslash ("\\"). For example:
*escape* ``with`` "\" escape with "" This is a paragraph. This is a paragraph.
\*escape* \``with`` "\\" *escape* ``with`` "\" Paragraphs line up at their left edges, and are normally separated by
Paragraphs line up at their left edges, and are blank lines.
normally separated by blank lines.
Lists
A paragraph containing only two colons indicates A paragraph containing only two colons indicates that the following
- This is item 1. A blank line before the first the following indented or quoted text is a literal indented or quoted text is a literal block.
• This is item 1. A blank line before the first and last items is block or quoted text is a literal block. Whitespace, newlines, blank lines, and
and last items is required.
- This is item 2
required. all kinds of markup (like *this* or
• This is item 2 :: \this) is preserved by literal blocks.
- Item 3: blank lines between items are optional. • Item 3: blank lines between items are optional.
• Item 4: Bullets are "-", "*" or "+". Continuing text must be Whitespace, newlines, blank lines, and all kinds of You can also tack the :: at the end of a paragraph:
- Item 4: Bullets are "-", "*" or "+".
markup (like *this* or \this) is preserved here. It's very convenient to use this form.
Continuing text must be aligned after the bullet aligned after the bullet and whitespace.
and whitespace. • This list item contains nested items Per-line quoting can also be used for unindented blocks:
- This list item contains nested items You can also tack the ``::`` at the end of a > Useful for quotes from email and
• Nested items must be indented to the same level paragraph:: > for Haskell literate programming.
- Nested items must be indented to the same
level It's very convenient to use this form.
3. This is the first item
3. This is the first item Per-line quoting can also be used for unindented
4. This is the second item
5. Enumerators are arabic numbers,
4. This is the second item blocks::
single letters, or roman numerals 5. Enumerators are arabic numbers, single letters, or roman
numerals > Useful for quotes from email and
6. List items should be sequentially
6. List items should be sequentially numbered, but need not start > for Haskell literate programming.
numbered, but need not start at 1
(although not all formatters will at 1 (although not all formatters will honour the first index). | Line blocks are useful for addresses, Line blocks are useful for addresses,
honour the first index). 7. This item is auto-enumerated | verse, and adornment-free lists. verse, and adornment-free lists.
#. This item is auto-enumerated |
| Each new line begins with a Each new line begins with a
what what
| vertical bar ("|").
Definition lists associate a term with vertical bar ("|").
a definition.
Definition lists associate a term with a definition. | Line breaks and initial indents
Line breaks and initial indents
| are preserved.
are preserved.
how | Continuation lines are wrapped
how Continuation lines are wrapped portions of long lines; they begin with
portions of long lines; they begin
The term is a one-line phrase, and the spaces in place of vertical bars.
The term is a one-line phrase, and the definition is one or more with spaces in place of vertical bars.
definition is one or more paragraphs or
paragraphs or body elements, indented relative to the term. Block quotes are just: Block quotes are just:
body elements, indented relative to the
Blank lines are not allowed between term and definition. Indented paragraphs,
term. Blank lines are not allowed
between term and definition. Indented paragraphs,
and they may nest.
:Authors:
and they may nest.
Tony J. (Tibs) Ibbs, Authors: Tony J. (Tibs) Ibbs, David
David Goodger Goodger Doctest blocks are interactive Doctest blocks are interactive Python sessions. They begin with ">>>"
Python sessions. They begin with and end with a blank line.
Version: 1.0 of 2001/08/08 "``>>>``" and end with a blank line. >>> print "This is a doctest block."
:Version: 1.0 of 2001/08/08
:Dedication: To my father. Dedication: To my father. This is a doctest block.
>>> print "This is a doctest block."
-a command-line option "a" -a command-line option "a" This is a doctest block.
-b file options can have arguments
-b file options can have arguments A transition marker is a horizontal line A transition marker is a horizontal line of 4 or more repeated
and long descriptions
of 4 or more repeated punctuation punctuation characters.
--long options can be long also and long descriptions
characters.
--input=file long options can also have --long options can be long also
arguments A transition should not begin or end a section or document, nor should
------------
/V DOS/VMS-style options too --input=file long options can also have two transitions be immediately adjacent.
arguments
A transition should not begin or end a
/V DOS/VMS-style options too section or document, nor should two
transitions be immediately adjacent.

© 2009 Roberto Alsina <[email protected]> / Creative Commons Attribution-Noncommercial-Share Alike 2.5 Argentina License Based on quickref.txt from docutils Non-Commercial Share Alike
 Tables Internal crossreferences, like example_. Internal crossreferences, like example.
This is an example crossreference target.
There are two syntaxes for tables in reStructuredText. Grid tables are complete but cumbersome to create. Simple tables are easy to create but limited .. _example:
(no row spans, etc.).
This is an example crossreference target.
+------------+------------+-----------+
Header 1 Header 2 Header 3 Python_ is `my favourite Python is my favourite programming language.
| Header 1 | Header 2 | Header 3 |
+============+============+===========+ body row 1 column 2 column 3 programming language`__.
| body row 1 | column 2 | column 3 | body row 2 Cells may span columns.
+------------+------------+-----------+ .. _Python: http://www.python.org/
body row 3 Cells may span
| body row 2 | Cells may span columns.| • Cells
+------------+------------+-----------+ rows. __ Python_
body row 4 • contain
| body row 3 | Cells may | - Cells | Titles are targets, too
• blocks. Titles are targets, too
+------------+ span rows. | - contain | =======================
| body row 4 | | - blocks. | Implict references, like Titles are targets, too.
+------------+------------+-----------+ Implict references, like `Titles are targets, too`_.
===== ===== ====== Directives are a general-purpose extension mechanism, a way of adding support for new constructs without adding new syntax. For a description
Inputs Output
Inputs Output of all standard directives, see reStructuredText Directives (http://is.gd/2Ecqh).
------------ ------ A B A or B For instance: For instance:
A B A or B False False False
===== ===== ====== .. image:: magnetic-balls.jpg
False False False
True False True
:width: 40pt
True False True False True True
False True True True True True
True True True Substitutions are like inline directives, allowing graphics and arbitrary constructs within text.
===== ===== ====== The |biohazard| symbol must be used on containers used to The symbol must be used on containers used to dispose of medical
dispose of medical waste. waste.
Explicit Markup .. |biohazard| image:: biohazard.png
:align: middle
Explicit markup blocks are used for constructs which float (footnotes), have no direct paper-document representation (hyperlink targets, comments), or
:width: 12
require specialized processing (directives). They all begin with two periods and whitespace, the "explicit markup start".
Any text which begins with an explicit markup start but doesn't use the syntax of any of the constructs above, is a comment.
Footnote references, like [5]_. Footnote references, like 5. Note that footnotes may get rearranged,
Note that footnotes may get .. This text will not be shown
e.g., to the bottom of the "page".
rearranged, e.g., to the bottom of (but, for instance, in HTML might be
the "page". rendered as an HTML comment)
An "empty comment" does not An "empty comment" does not consume following blocks. (An empty
.. [5] A numerical footnote. Note consume following blocks. comment is ".." with blank lines before and after.)
there's no colon after the ``]``. (An empty comment is ".." with
blank lines before and after.) So this block is not "lost", despite its indentation.
Autonumbered footnotes are Autonumbered footnotes are possible, like using 1 and 2.
possible, like using [#]_ and [#]_. They may be assigned 'autonumber labels' - for instance, 4 and 3.
..
.. [#] This is the first one.
.. [#] This is the second one. So this block is not "lost",
despite its indentation.
They may be assigned 'autonumber
labels' - for instance, Credits
[#fourth]_ and [#third]_.

CP Font from LiquiType: http://www.liquitype.com/workshop/type_design/cp-mono

.. [#third] a.k.a. third_
Magnetic Balls V2 image by fdecomite: http://www.flickr.com/photos/fdecomite/2926556794/
.. [#fourth] a.k.a. fourth_ Sponsored by Net Managers http://www.netmanagers.com.ar
Auto-symbol footnotes are also * †
Auto-symbol footnotes are also possible, like this: and . Typeset using rst2pdf http://rst2pdf.googlecode.com
possible, like this: [*]_ and [*]_.

.. [*] This is the first one.

.. [*] This is the second one.
Citation references, like [CIT2002]_. Citation references, like CIT2002. Note that citations may get
Note that citations may get rearranged, e.g., to the bottom of the "page".
rearranged, e.g., to the bottom of Citation labels contain alphanumerics, underlines, hyphens and
the "page". fullstops. Case is not significant.
Given a citation like this, one can also refer to it like this.
.. [CIT2002] A citation
(as often used in journals).

Citation labels contain alphanumerics,

underlines, hyphens and fullstops. 5 A numerical footnote. Note there's no colon after the ].
Case is not significant. 1 This is the first one.
2 This is the second one.
Given a citation like [this]_, one
can also refer to it like this_.
3 a.k.a. third
4 a.k.a. fourth
.. [this] here. * This is the first one.
External hyperlinks, like Python_. External hyperlinks, like Python. † This is the second one.
CIT2002(1, 2) A citation (as often used in journals).
.. _Python: http://www.python.org/
this here.
External hyperlinks, like `Python External hyperlinks, like Python.
<http://www.python.org/>`_.

© 2009 Roberto Alsina <[email protected]> / Creative Commons Attribution-Noncommercial-Share Alike 2.5 Argentina License Based on quickref.txt from docutils Non-Commercial Share Alike