reStructuredText Markup

This document is an introduction to the reStructuredText (rST) markup language. It demonstrates the features of the Moin2 rST support. For details, follow the links to the reStructuredText Markup Specification.

There are two HTML version of this document: one is part of the Wiki Help generated by Moin, the other belongs to the external documentation generated by Sphinx. Some features and links only work in the Wiki Help page.

Section Headings

Section headings are underlined (or over- and underlined) with a printing nonalphanumeric 7-bit ASCII character (details).

  • The underline/overline must be at least as long as the title text.

  • A blank line after a heading is optional.

  • Instead of a fixed order of heading adornment styles, the level is determined by their order in the document:

    The first adornment style encountered is registered as page title style (<h1> in HTML), the second style is assigned to level 2, the third style to level 3, and so on.[1]

  • Once established, adornment styles must be consistent. Skipping a heading level results in a parsing error.

Markup

Result

 
=======
Level 1
=======

The first encountered style becomes the page title (if it is unique)[1].

 
Level 2
=======

See the heading of this section.

 
Level 3
-------
Level 4
*******
Level 5
:::::::
Level 6
+++++++

See below.

(Section headings may not be nested in body elements like lists, tables, or admonitions. You may use rubrics for informal headings outside the main document structure.)

Level 3

Level 4

Level 5
Level 6

Thematic Breaks

A thematic break represents a change in subject or emphasis. It is typically rendered as additional space between paragraphs, often with a horizontal line, a row of asterisks, or some other ornament. See below for an example.

HTML represents a thematic break with the <hr /> element. In reStructuredText, this element is called transition and represented by a horizontal line of 4 or more repeated punctuation characters (details).

Markup

Result

 
See below for an example.

------------------------

HTML represents […]

See above.

(Transitions may not be nested in body elements like lists, tables, admonitions, …).

Text Formatting

Inline markup can be applied to words or phrases within a text block to format text (details).

  • Less common styles are obtained via interpreted text roles.

  • reStructuredText does not support ***Nested** inline markup*. [2]

Markup

Result

Notes

*emphasis*

emphasis

**strong emphasis**

strong emphasis

``inline \literal\``

inline \literal\

In literal context, backslashes have no special meaning.

`Hamlet`

Hamlet

Interpreted text. The default text role is configurable, it defaults to the “title” role (see below).

:ab:`abbr.`

abbr.

Abbreviations, can be styled with custom CSS.

:code:`answer = 42`

answer = 42

For syntax highlight, see custom text roles.

:sub:`sub`\ script

subscript

Character-level markup …

:sup:`super`\ script

superscript

… requires escaped spaces.

:title:`Moin`

Moin

The title of a creative work (book, opera, coding project, etc.) Analog to HTML <cite>. This is the initial default text role.

Additional Text Roles

Including the “html-roles.txt” standard definition file adds roles that correspond to HTML elements representing edits to the document and text-level semantics.

Markup

Result

Notes

:del:`removed`

removed

removed content

:ins:`inserted`

inserted

editional additions

:b:`keyword`

keyword

highlight key words without marking them up as important

:dfn:`dfn`

dfn

the defining instance of a term

:i:`rôle`

rôle

alternate voice

:kbd:`Ctrl X`

Ctrl X

user input

:mark:`up`

up

highlight a run of text

:q:`Tagline!`

Tagline!

content quoted from another source

:s:`strike`

strike

text that is inaccurate or no longer relevant

:samp:`Ready!`

Ready!

computer output

:small:`print`

print

side comments

:u:`anotation`

anotation

unarticulated annotations of, e.g, mispellings

:var:`n`

n

variables

Custom Text Roles

Custom interpreted text roles can be used to attach CSS class values to inline text and set the code language for syntax highlight (details).

Markup

Result

Notes

 
.. role:: green

A :green:`dragon`.

A dragon.

Moin pre-defines some CSS classes for background color. Text with other classes can be styled with custom CSS.

 
.. role:: blue(emphasis)

The `Norwegian`:blue:.

The Norwegian.

Custom roles may be based on standard roles.

 
.. role:: em-tt(emphasis)
   :class: monospaced

*emphasis* and :em-tt:`emphasis monospace`

emphasis and emphasis monospace

Custom roles may be used as surrogate for nested inline markup.

 
.. role:: tex(code)
   :language: latex

:tex:`\frac{\pi}{4}`

frac{pi}{4}

There is highlight support for many languages.

See also code blocks.

Blockquotes

An indented text block is interpreted as a blockquote, a text part quoted from another source (details).

  • Blockquotes may contain arbitrary body elements.

  • To add an attribution, append a paragraph preceded by “--” or an em-dash.

Markup

Result

 
preceding paragraph

  It is my business to know
  things. That is my trade.

  -- Sherlock Holmes

succeeding paragraph

preceding paragraph

It is my business to know things. That is my trade.

—Sherlock Holmes

succeeding paragraph

Lists

reStructuredText provides syntax for unordered lists, ordered lists, definition lists, field lists, and option lists. See line blocks for the rST alternative to a “bulletless” list.

  • Lists must be separated from other body elements by blank lines. Blank lines between list items are optional.

  • The list marker must not be indented.

  • List items may contain arbitrary body elements.

Unordered Lists

A text block which begins with a *, +, -, •, ‣, or ⁃, followed by whitespace, is a bullet list item (details).

  • Item content must be left-aligned and indented relative to the marker.

  • Content may start on the same line as the marker or on the next line.

  • The first content line sets the indentation level for this item.

Sub-items 2.1 to 2.2.2 show some valid input variants.

Markup

Result

 
- item 1
- item 2

  -   item 2.1
  - item 2.2

    - item 2.2.1
    -
     item
     2.2.2

- item 3

  • item 1

  • item 2

    • item 2.1

    • item 2.2

      • item 2.2.1

      • item 2.2.2

  • item 3

 
Attention!

 * Indented lists
 * are nested
   in a block quote.

Attention!

  • Indented lists

  • are nested in a block quote.

Ordered Lists

Ordered lists are similar to unordered lists, but use enumerators instead of bullets (details).

  • Ordered lists can be automatically enumerated using the # character.

  • The first enumerator determines the enumeration sequence, formatting type [3], and start value.

Sub-items 2.1 to 2.2.2 show some valid indentation variants.

Markup

Result

 
#. item 1
#. item 2

   (a)   item 2.1
   (#) item 2.2

       i) item
          2.2.1
       #)
        item 2.2.2

#. item 3

  1. item 1

  2. item 2

    1. item 2.1

    2. item 2.2

      1. item 2.2.1

      2. item 2.2.2

  3. item 3

 
4) item 4 with

   C. uppercase
   #. letters and

      IV) custom
      #) start values

  1. item 4 with

    1. uppercase

    2. letters and

      1. custom

      2. start values

Definition Lists

Definition lists are formed by a term on one line followed by an indented definition or description on the next line (details).

Markup

Result

 
term
  Description
term 2 : classifier
  Optional *classifiers*
  may be appended to the term.
term

Description

term 2classifier

Optional classifiers may be appended to the term.

Field Lists

Field lists are mappings from field names to field bodies (details).

  • Field bodies may start on the same line as the field name or on the next line.

  • Field list syntax is also used for options in directives and for bibliographic fields.

Markup

Result

 
:Version:      2.0b2
:Release Date: 2001-08-16
:Authors: - Joe Doe
   - Erika Mustermann
   - Jan Kowalski
Version:

2.0b2

Release Date:

2001-08-16

Authors:

  • Joe Doe

  • Erika Mustermann

  • Jan Kowalski

Option lists

Option lists document the options of a command-line program (details).

  • There must be at least two spaces between the option(s) and the description (which may also start on the next line).

Markup

Result

 
-a      Output all.
-c arg  Output just arg.
--long  Output all day long.
-f FILE, --file=FILE  These
   two options are synonyms.
-a

Output all.

-c arg

Output just arg.

--long

Output all day long.

-f FILE, --file=FILE

These two options are synonyms.

Line Blocks

A line block is the reStructuredText syntax for forced line breaks (details). It resembles a plain (bulletless) list and is commonly used for verse and addresses

  • Line blocks may contain inline markup and nested line blocks. Block-level markup is not recognized.

Markup

Result

 
| Start lines with a vertical bar.
|    Indented lines
|    indicate a *nested* line block.
| Long lines may be
  continued on the next line
  (without vertical bar).
| In the output, all lines may wrap.
Start lines with a vertical bar.
Indented lines
indicate a nested line block.
Long lines may be continued on the next line (without vertical bar).
In the output, all lines may wrap.

Tables

There are four ways to specify tables in reStructuredText:

Markup within the table cells is supported (you can even nest a table in a table cell). Table directives allow customization and adding a title/caption.

Simple Tables

Simple tables use a compact and easy to type table representation (details):

  • Equals signs (=) are used for top and bottom table borders, and to separate header rows from the table body.

  • Each line of text starts a new row, except when there is a blank cell in the first column.

Markup

Result

Notes

 
==== ==== ====
 ..   A    B
==== ==== ====
  1   A1  B1
  2   A2  B2
==== ==== ====

A

B

1

A1

B1

2

A2

B2

To start a row without content in the first column, use empty comments (..) or escaped whitespace (\ ).

 
=== === ===
In      Out
------- ---
 a   b  a+b
=== === ===
 1   2   3
=== === ===

In

Out

a

b

a+b

1

2

3

Lines of hyphens or equal signs crossing column boundaries indicate column spans.

 
=====  ================
row 1  a cell with
       two *lines*

row 2  a cell with

       two *paragraphs*
-----  ----------------
row 3  a) list
       #) item 2
=====  ================

row 1

a cell with two lines

row 2

a cell with

two paragraphs

row 3

  1. list

  2. item 2

Cells of the first column must fit on one input line. Other cells may use continuation lines.

Blank lines or lines of hyphens may be used to visually separate rows.

See the “table” directive for styling options.

Grid Tables

Grid tables are a table representation via grid-like “ASCII art” (details).

Markup

Result

Notes

 
+---+----+----+
|   | A  | B  |
+===+====+====+
| 1 | A1 | B1 |
+---+----+----+
| 2 | A2 | B2 |
+---+----+----+

A

B

1

A1

B1

2

A2

B2

 
+--------------+
| column span  |
+===+==========+
|* A| row span |
|* B|          |
+---+          |
|foo|          |
+---+----------+

column span

  • A

  • B

row span

foo

Grid tables allow arbitrary body elements in all cells and both row and column spans.

See the “table” directive for styling options.

Table Directives

Table directives use the “directive” syntax to pair the table content with a caption and/or options guiding the presentation.

csv-table

The csv-table directive supports CSV data (details).

Markup

Result

Notes

 
.. csv-table::
   :header-rows: 1
   :stub-columns: 1

   , A, B
   1, A1, B1
   2, A2, B2

A

B

1

A1

B1

2

A2

B2

Delimiter, quote character, escape character, and more can be customized with directive options.

Cell content is parsed as rST.

TODO: The :url: option to load data from an external source does not work with the syntax for wiki-internal items.

list-table

The list-table directive creates a table from data in a two-level bullet list (details).

Markup

Result

Notes

 
.. list-table::
   :header-rows: 1
   :stub-columns: 1

   * -
     - A
     - B
   * - 1
     - A1
     - B1
   * - 2
     - A2
     - B2

A

B

1

A1

B1

2

A2

B2

List-tables are suited for complex cell content. They are, for example, extensively used in the source of this document.

table

Use a table directive to attach a table caption, a reference name, or customization options to Simple Tables and Grid Tables (details).

Markup

Result

Notes

 
.. table:: Fruits
   :name:
     fruit salad
   :class: yellow
     moin-sortable
     no-borders

   ===== ====== ===
   Fruit Colour  #
   ===== ====== ===
   apple red     5
   plum  purple  3
   kiwi  brown   17
   ===== ====== ===
Fruits

Fruit

Colour

#

apple

red

5

plum

purple

3

kiwi

green

17

The “class” option allows styling with Moin CSS classes or custom CSS. (This also works with CSV tables and list tables.)

The “name” option provides a target for internal links.

Limitations

In comparison to other markup formats, you may miss some features that are not supported in reStructuredText:

  • There is no syntax for text alignment in cells or columns.

  • There is no syntax for table footer rows.

  • Attaching colour to individual rows or cells is not supported.

  • Attaching CSS class values to individual rows or cells is not universally supported.

Some features of reStructuredText tables are currently not supported by Moin (TODO):

  • The table caption/title is ignored.

  • The align, width, widths, and stub-columns options are ignored.

Preformatted Text

In a preformatted text block, line breaks and whitespace (except the minimal common indentation) are preserved. The font defaults to “monospace”.

Literal Blocks

A double-colon (::) at the end of a line or on a line of its own starts a literal block (details).

Markup

Result

 
In a literal block::

  Whitespace   and line
     breaks are preserved.

  *Markup* is `ignored\ `_.

In a literal block:

Whitespace   and line
   breaks are preserved.

*Markup* is `ignored\ `_.

Code Blocks

The “code” directive starts a code block. Specify the content language to enable syntax highlight.

Markup

Result

 
.. code:: rst

   .. |registered| replace::
      :sup:`®`
      :ltrim:

.. |registered| replace::
   :sup:`®`
   :ltrim:

Parsed Literal Blocks

The “parsed-literal” directive starts a parsed literal block. The content is parsed for inline markup.

Markup

Result

 
.. parsed-literal::

  A *pre*\ formatted   block
  with `text formatting_`.

A preformatted   block
with text formatting.

Directives

The directive markup syntax provides an extension mechanism for reStructuredText (details).

A set of standard directives is described in the reStructuredText Directives document. This section introduces a selection. See also Table Directives and Preformatted Text.

Applications may add domain-specific directives. Moin adapts the “contents” and “include” directives and adds the “macro” and “parser” directives.

Admonitions

Admonitions are used to draw the reader’s attention to an important information (details).

There are nine specific admonition types (”attention”, “caution”, “danger”, “error” [4], “hint”, “important”, “note”, “tip”, and “warning”) and one “generic” admonition.

Markup

Result

 
.. attention:: Mind the gap!

Attention

Mind the gap!

 
.. caution:: Use
   admonitions sparingly.

Caution

Use admonitions sparingly.

 
.. danger:: Slippery
            when wet!

Danger

Slippery when wet!

 
.. error::
   Something went wrong

Error

Something went wrong

 
.. hint::
   Think before you speak.

Hint

Think before you speak.

 
.. important::
   Back up your data!

Important

Back up your data!

 
.. note::
   :name: note

   The "name" option
   provides a target
   for `internal links`_.

Note

The “name” option provides a target for internal links.

 
.. tip:: Be consistent.

Tip

Be consistent.

 
.. warning:: Strong prose
   may provoke
   extreme mental exertion.

Warning

Strong prose may provoke extreme mental exertion.

 
.. admonition:: Custom

   The generic `"admonition"
   directive`_ expects
   a title as argument.

Custom

The generic “admonition” directive expects a title as argument.

Images

Images are inserted with the “image” directive. For inline images, use a substitution definition.

  • Moin does not support length units in the “width” and “height” options. Unitless numbers work fine.

Markup

Result

Notes

 
.. image:: help-common/logo.svg
   :width: 100
   :height: 150
   :alt: [MoinMoin logo]
   :name: MoinMoin logo
   :target: help-en/Home

A block-level image.

The “name” option provides a target for internal links.

The “target” option makes the image “clickable”.

The |MoinMoin| logo as inline image.

.. |MoinMoin| image::
   help-common/logo.svg
   :height: 18

The MoinMoin logo as inline image.

The substitution definition may be referenced more than once (cf. Wiki-Internal Links).

An external inline image |Python|.

.. |Python| image:: https://
   docs.python.org/3/_static/py.svg
   :height: 18

An external inline image Python.

Images from external sources may be blocked by the browser for security or privacy reasons.

  • Videos are recognized by the file extension.

    [demo video]

    TODO: currently, “width” and “alt” options are ignored by Moin.

  • [a cat]

    A right or left aligned image (using the “align” option) lets the following elements float up.

  • In Moin, images are not enclosed within a block level element so several images declared successively without any positioning will be displayed in a horizontal row:

    [MoinMoin logo] [MoinMoin logo] [MoinMoin logo]

  • In the external documentation, most image-URIs do not work and the alternate text is shown.

Figures

A figure consists of an image, a caption, and an optional legend. Figures are declared with the “figure” directive.

Markup

Result

 
.. figure:: help-common/logo.svg
   :height: 50
   :alt: [white M in blue circle]

   Moin Logo

   The image URI does not work in
   the `external documentation`_.
[white M in blue circle]

Moin Logo

The image URI does not work in the external documentation.

Inclusions

The “include” directive is adapted by Moin to include Wiki items.

Markup

Result

 
.. include:: help-common/audio.mp3

Not shown, because it prevents compilation of the external documentation.

 
.. include:: <html-roles.txt>

The roles defined in the included file can be used in the document. Cf. additional text roles.

Rubrics, Sidebars, and Topics

The “rubric” directive creates an informal heading. Sidebars and topics are used for content that is only tangentially related to the main subject.

Markup

Result

 
.. rubric:: Why "Rubric"?

A *rubric* was traditionally
a text part written in red.

Why “Rubric”?

A rubric was traditionally a text part written in red.

 
.. sidebar:: Floating Sidebars
   :class: float-right

   Use `Moin CSS classes`_ to let the
   sidebar float to the right or left.

.. topic:: Topics and Blockquotes

   A *topic* is like a blockquote
   with a title, or a self-contained
   section with no subsections.

See below.

(Topics and sidebars may not be nested in body elements like lists, tables, admonitions, …)

Table of Contents

The “contents” directive generates a table of contents.

Markup

Result

 
.. contents::
   :depth: 3

See the ToC at the top.

Comments

A comment is a text block that starts with “.. ” and ends with the first non-indented line (details).

  • An “empty comment” followed by a blank line does not consume any indented text. It serves to terminate a preceding construct.

  • In Moin, comments may be made visible/invisible by clicking the “Comments” link in the “Item Views” menu/toolbar.

  • Tip: to prevent mix-up with other “explicit markup blocks”, start the text on the line below the “.. “.

Markup

Result

 
.. This is a comment.
.. [This] is a citation_.
..
   [This] is a comment.
..

   [This] is a blockquote.
[This]

is a citation.

[This] is a blockquote.

Backslash Escapes

A backslash escapes the following character (details).

Markup

Result

Notes

*hot* \*dogs*

C:\\WINDOWS

hot *dogs*

C:\WINDOWS

The escaped character represents itself.

H\ :sub:`2`\ O

H2O

Escaped whitespace is removed, …

`</Subitem\ Exam ple>`__

/Subitem Example

… except in URI context (where whitespace is removed by default).

Error Handling

Problems with a severity level above the report level generate system messages.

Markup

Result

Unbalanced *inline markup triggers a warning.

Unbalanced *inline markup triggers a warning.