Easily highlight source code for your blog with our Syntax Highlighter. Join Siafoo Now or Learn More

reStructured Text Atom Feed 0

1   About

1.1   What is reST?

reStructured Text is a customizable plaintext markup system for writing documents. For general information on reST, visit the official reST home page.

This tutorial will get you started writing reST syntax, including some directives we've created just for Siafoo.

If you are a hands-on sort of person, you might like to follow along using the Siafoo reST demo.

Already created some content, but it's in HTML format? You might want to use our HTML to reST translator.

1.2   What can it do?

What can reST do? The short answer is a lot. This whole help page is written in reST!


If you're interested in how to do things, skip down to Basics. This is just eye candy, and skips over a lot of details. :)

reST is of course capable of styling text bold, italic, and monospaced. Like every other text formatting system, it can create links, lists, and tables. You can organize your document into sections, which automatically get anchors. As you can see you can make a table of contents too. But that's not the cool part, that is just 'how to let users write HTML securely' (ok the TOC is a little cool).

What really makes Siafoo's reST powerful is what else you can do (and how integrated with the rest of the site it is).

You can reference Siafoo objects like snippets: :snippet:`9` creates Brainfuck Hello World. The title is fetched and updated automatically. You can also reference books by ISBN: :book:`978-0201889543` creates

Error:list index out of range
. The book's data is fetched from Amazon automatically.

You can easily include Siafoo snippets. When the snippet is updated, so is the article. (The syntax is just ".. snippet:: 1"):

# 's
1print 'Hello World!'
This snippet is licensed under the Public Domain license

Only have a bit of code? You can embed it straight into the article:

# 's
1a = [i for i in range(100) if i % 2 == 0]

Easily create and render a chart, like this completely fictitious one:


Use simple syntax to draw a flow graph like this one:

Write mathematical formulas and equations:

Embed an image you've uploaded...


xkcd, while awesome, is in no way associated with Siafoo. And images can have captions!

... or a YouTube video:

Ready to sign up for an account yet? :)

2   Basics

reStructured Text uses indentation and blank lines to distinguish between different sorts of elements. There is no required amount of indentation, but four spaces is a good number to use. You can tab to indent four spaces at once, or highlight a line and press tab or shift-tab to indent or dedent, using the full screen editor.

2.1   Paragraphs

Paragraphs are blocks of text, separated by blank lines. If you don't separate a blank line, text will run together. This is a common frustration of first time reST programmers, especially when cutting and pasting text from a README or something similar.

You can also indent paragraphs. Typically this is used for quoting.
It may appear possible to not separate the indented paragraph from the one above it,
but in this case you are actually creating a definition list. Use at your own risk : )

Here's an example:

This is a short paragraph.

    This is an indented paragraph.

This is another short paragraph.
Whoops, I've forgotten to put a blank line above this one.

This text creates:

This is a short paragraph.

This is an indented paragraph.

This is another short paragraph. Whoops, I've forgotten to put a blank line above this one.

2.2   Sections

To break up a document into sections, you underline (or underline and overline) the entire section title using one of the characters:

= - ` : ' " ~ ^ _ * + # < >

Sections decorated with the same character belong to the same 'section level'. However, a section underlined only counts as a different section than one overlined and underlined. Sections with the same 'section level' get the same size headline. For example, this page's section titles look something like:

Chapter 1 Title

Section 1.1 Title

Subsection 1.1.1 Title

Section 1.2 Title

Chapter 2 Title

Sorry, no live example for this one, but you can look at how this page is laid out to get an idea of how section titles work.

Note that a target is created for each section by default; the above "Chapter 1 Title" could be linked to with `Chapter 1 Title`_


You must use the same characters and style throughout your document. In other words, you cannot do something like this:

Chapter 1 Title

Section 1.1 Title

Chapter 2 Title

Section 1.2 Title

2.2.1   Table of Contents

When you're writing a complicated page like this one, we recommend you add a table of contents. You can do this with the following directives, which creates a TOC like the one on the top of this page:

.. sidebar:: Contents

    .. contents::

.. sectnum::

.. sidebar:: Contents creates a sidebar labeled 'Contents'. The indented .. contents:: creates the actual table of contents inside the sidebar. sectnum:: auto-numbers all your sections.

You can also create a TOC for only one section, by placing this code in that section and passing the :local: argument to .. contents::. You can specify the depth of the TOC with :depth:; the default is unlimited depth. For more information about this syntax, see Interpreted Text Roles and Directives.

2.3   Styles

Styles are easy:

For Italics, surround the text with asterisks. like *Italics*

For Bold, surround the text with double asterisks, like **Bold**

For Literals, surround the text with double backticks, like ``Literals``. Literals are monospace and the text inside is not evaluated further. Most of the inline reST on this page is created this way.

2.3.1   Block Literals

You can also do a block literal by ending a line with a double colon (or just putting a double colon on a line), and indenting the block you want to be literal. The majority of reST blocks on this page are created this way. For example:

Here is an example::

    Look, ``styles`` don't get **processed**

The result of this is:

Here is an example:

Look, ``styles`` don't get **processed**

Note that text does not get wrapped in a block literal, so make sure not to make your lines too long.

2.5   Lists

Lists must have a blank line below and above them.

To make a bulleted or 'unordered' list, prepend each item with *, +, - and a space. You must use the same sort of bullet for each item however. To make a numbered or 'ordered' list, prepend each item with a number or a '#' (for autonumbering) and a space. To create a definition list, indent text without leaving a blank line. You can nest lists by further indenting the nested list. For example:

* This is a bulleted list item
* So is this

    1. This is a nested numbered list
    #. Here's another item

And here's a definition title
    And the definition content

This text creates:

  • This is a bulleted list item

  • So is this

  • So is this

    1. This is a nested numbered list
    2. Here's another item
And here's a definition title
And the definition content

2.6   Interpreted Text Roles and Directives

Obviously there aren't enough characters to have a different way to mark up each thing you might want to do in reST. To work around this problem, reST has interpreted text roles and directives. These allow more complicated tasks.

Interpreted text roles are for advanced inline markup. They look like :role:`argument`. Think of it as passing an argument to a function.

Directives are similar, but create blocks. They accept multiple arguments and content. They look like this:

.. directive:: main_value
    :arg1: value1
    :arg2: value2

    content goes here

Not all directives take a main value, arguments, and content. They may take none, some, or all of these. Arguments are almost always optional.

Directives are very powerful, but it is easy to mess up the syntax: the '..' is separated from the directive name by a space, the '::' is NOT, and the main value is separated from the '::' by a space. Arguments and content are indented (at the same level). A blank line separates the directive, main value, and arguments from the content, even when there are no sub-arguments. Sometimes when you forget or add a character, the whole thing just disappears with no error! Don't worry though, it is easy to get the hang of it.

Many of the methods from here on out use either roles or directives.

2.7   Admonitions

Admonitions are notes, warnings, or other sorts of extra information set out from the rest of the text. To create one, you use a directive with the name of that admonition ('attention', 'caution', 'danger', 'error', 'hint', 'important', 'note', 'tip', 'warning'). You pass it the text you want used as the 'value' of the directive and/or as the directive's content. For example, a 'warning' admonition would be specified like:

.. warning:: Don't do that!

    I mean it!

It would then look something like this:


Don't do that!

I mean it!

The others look similar, but with slightly different styles.

You can also specify your own title with the admonition::title tag. In this case the text must be passed as directive content:

.. admonition:: Look a custom title!

    Here is some content.

When rendered, this one looks like:

Look a custom title!

Here is some content.

2.8   Tables

There are three or four ways of creating tables in reST, depending on how you count them. I think they are fairly self explanatory.

2.8.1   Basic Tables

The simplest way is to use lines of = above and below each column, and below each column title:

====================  ==========  ==========
Header row, column 1  Header 2    Header 3
====================  ==========  ==========
body row 1, column 1  column 2    column 3
body row 2            Cells may span columns
====================  ======================

You can also create tables more explicitly, ASCII-art-style:

| Header row, column 1   | Header 2   | Header 3 |
| body row 1, column 1   | column 2   | column 3 |
| body row 2             | Cells may span        |

Both of these definitions will result in:

Header row, column 1 Header 2 Header 3
body row 1, column 1 column 2 column 3
body row 2 Cells may span

The disadvantage of these methods is that you have to move around the 'art' symbols every time you change the width of anything in the table.

2.8.2   List Table

You can use also use the .. list-table:: directive to create a table:

.. list-table:: Frozen Delights!
   :widths: 15 10 30
   :header-rows: 1

   * - Treat
     - Quantity
     - Description
   * - Albatross
     - 2.99
     - On a stick!
   * - Crunchy Frog
     - 1.49
     - If we took the bones out, it wouldn't be
       crunchy, now would it?
   * - Gannet Ripple
     - 1.99
     - On a stick!

2.8.3   CSV Table

Finally, you can create a CSV (Comma-Separated Values) table using the .. csv-table:: directive:

.. csv-table:: Frozen Delights!
   :header: "Treat", "Quantity", "Description"
   :widths: 15, 10, 30

   "Albatross", 2.99, "On a stick!"
   "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
   crunchy, now would it?"
   "Gannet Ripple", 1.99, "On a stick!"

Both the list table and the CSV table create this:

Frozen Delights!
Treat Quantity Description
Albatross 2.99 On a stick!
Crunchy Frog 1.49 If we took the bones out, it wouldn't be crunchy, now would it?
Gannet Ripple 1.99 On a stick!

3   References

You can reference certain things by an id, and Siafoo will find the title for you, and keep it updated.

3.1   Books

You can reference a book by ISBN; Siafoo uses Amazon's API to look up the title of the book and to provide a link to Amazon. Why use the ISBN and not just the title? Two reasons:

  • Anyone reading will know exactly which version of the book you are talking about. The worst is to buy a book and realize that what you wanted was only in the next/previous edition.
  • We get a small commission for each book bought through one of these links, so you are supporting Siafoo. :)

You can get an inline link by using the role :book:`ISBN`. For example :book:`978-0201889543 ` will create

Error:list index out of range

For more information or to get a proper 'reference' format, you can use the directive:

.. book:: 978-0201889543

This creates:

System Message: ERROR/3 (<string>, line 439)

Error:list index out of range

.. book:: 978-0201889543

3.2   Snippets, Articles and other Siafoo Objects

You can put a link to an algorithm, article, group, library, or snippet by using an interpreted text role like :item_type:`id`. If the title is changed, it will be automagically updated in your page. For example:

Some of our post popular items are :algorithm:`5` and :article:`52`?
You should consider joining :group:`3`.  I really like the snippet :snippet:`9`.

This creates:

Some of our post popular items are BogoSort and Python Tips, Tricks, and Hacks? One of the first things on Siafoo was Language Demos. You should consider joining the Siafoo Users Group. I really like the snippet Brainfuck Hello World.

You can also reference help pages if for some reason you'd like to. Use the :help: role with the help page name (the 'name' is what the URL displays, as opposed to the full title). So :help:`reST` will create a link to the page you are at right now: reStructured Text.

4   Embedding

What can you do in reST besides text? Quite a bit it turns out.

4.1   Images

You can upload an image using your image management page, or by directly using the 'Add Image' fields in any create or edit form. When using the create or edit form, upon uploading an image the correct directive will be placed at the bottom of the reST content.

If the item you are creating or editing is owned by a Siafoo Group, you can upload images to the group as well.

You can only add images that are owned by you or the same group as the item you are creating or editing. However, you can move images that others have added within the reST for that item.

Naturally, you can't delete an image if it is used inside an article, as this will make things inconsistent.

To include an image, use the .. image::id directive, where id is the numerical id of the image.

For advanced use, the following arguments are supported. The image directive does not take any 'content'.

Arguments Description
A short description of the image (the "alt" attribute in the HTML <img> tag)
Height of image in pixels
Width of image in pixels
The scaling factor for the image, in percent
The alignment of the image, (the "align" attribute of the HTML <img> tag). The values "left", "center", and "right" control an image's horizontal alignment. Use these to float the image and have the text flow around it.
Makes the image into a link. This may be a URL or a target name with underscore suffix (e.g. name_).

For example:

.. image:: 39
   :alt: Volume Rendered Earth
   :width: 256

This code creates:

Volume Rendered Earth

4.1.1   Figures

You can also create figures, which are images with captions. You can use the .. figure:: directive, which acts exactly like the image directive except for two things: it accepts an argument :figwidth: specifying the width of the whole figure, and the directive's content area is used for the caption of the image:

.. figure:: 39
   :alt: Volume Rendered Earth
   :width: 256
   :figwidth: 300

   This is the Earth.  If I write a long caption it should be contained because of the figwidth option.

This code creates:

Volume Rendered Earth

This is the Earth. If I write a long caption it should be contained because of the figwidth option.

4.2   Videos

You can embed YouTube videos inside reST using the .. youtube:: id directive, where id can either be the YouTube video ID or the URL to the video. For example:

.. youtube:: http://www.youtube.com/watch?v=z2BgjH_CtIA

This results in:

4.3   Embedding Snippets and Code

There are two ways to embed code inside an article.

To embed an entire snippet, use the .. snippet:: id directive, where id is the snippet id. If an embedded snippet is updated it will be automagically updated inside the reST. This is the best thing to do for larger blocks of code (heh unlike this example), or code you'd like to set a separate license for. You get a link to the snippet too. For example:

.. snippet:: 1

will result in the following:

# 's
1print 'Hello World!'
This snippet is licensed under the Public Domain license

You can also embed arbitrary code using the .. code:: language_name directive where the language_name is the short name of the desired language. You can find a list of supported languages and their short names at Supported Languages.

The actual code should be the 'content' of the directive: indented and separated by a blank space. For example:

.. code:: Python

    print 'This is another Hello World'

This code creates:

# 's
1print 'This is an inline code block! Yay!'

4.4   Charts

You can create pie, bar, and line charts. For example:

.. piechart::
  :title: Visitors with Firefox
  :data: 36.30, 55.40, 8.3
  :colors: f5f700, 0087f7, f79b00
  :labels: Firefox 3 (36.0%), Firefox (55.40%), Other Firefox 2 (8.3%)

This code creates:


We have a whole page about creating charts: Charts

4.5   Flow Graphs

Siafoo lets you create flow graphs in the Graphviz format. Our rendering engine is quite powerful; this little bit of code:

.. graph::

  node.hdr { color: red; }
  node.src { fill: lightgreen; }
  node.stage { fill: lightblue; }

  (Libraries: [Library 1]{ shape: diamond;},
              [Library 2]{ shape: diamond;},
              [Library 3]{ shape: diamond;})

  [Header 1]{class: hdr;},
  [Header 2]{class: hdr;},
  [Header N]{class: hdr;}-> [Preprocessor]{shape:circle; class:stage;} -> [Intermediate 2],
                                                                          [Intermediate 1] ->[Compiler]
  [Source 1]{class: src;}, [Source 2]{class: src;}-> [Preprocessor]

  [ Compiler ]{shape:circle; class:stage;} -> [ Object 2], [ Object 1] -> [ Linker ]

  [Library 1], [Library 2], [Library 3] -> [Linker]{shape:circle; class:stage;}
  [Linker] -> [Binary2]

Creates a fairly complex graph:

For information on flow graphs, see Flow Graphs.

4.6   LaTeX Style Math

Finally, you can embed LaTeX-style math expressions using an inline text role or a directive. You can use the inline text role: :math:`E=mc^2` creates . Or you can use the directive for larger equations:

.. math:: align

    \nabla \cdot E &= \frac{1}{\epsilon_0} \rho\\
    \nabla \cdot B &= 0\\
    \nabla \times E &= -\frac{\partial B}{\partial t}\\
    \nabla \times B &= \mu_0 J + \mu_0 \epsilon_0 \frac{\partial E}{\partial t}

This code creates:

We have a whole page about this too: LaTeX Style Math

5   Reference

Below you will find a list of the allowed markup, list types, interpreted text roles, and directives on Siafoo. If a directive or text role is not listed, we've probably removed it from the parser. We have removed several directives, such as embedding raw html inside the reST blocks, because they pose a security or privacy threat to our users. Others like meta tags don't make sense when you're not making a whole page.

Note that just because something is supported doesn't mean it does anything cool. For example, as of this writing, pull-quotes don't have any special CSS, and so just look like everything else.

If you have any questions or comments feel free to contact us via the feedback link.

5.1   Explicit Markup

Explicit Markup Examples
.. [1] Manually numbered or [#] auto-numbered
(even [#labelled]) or [*] auto-symbol``
Citation .. [CIT2002] A citation.
Hyperlink Target .. _reStructuredText: http://docutils.sf.net/rst.html .. _indirect target: reStructuredText_ .. _internal target:
Anonymous Target __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html
Directive ("::") .. image:: 1337
Substitution Def .. |substitution| replace:: like an inline directive
Comment .. is anything else
Empty Comment (".." on a line by itself, with blank lines before & after, used to separate indentation contexts)

5.2   List Types

List Type Examples
Bullet list
  • items begin with "-", "+", or "*"
Enumerated list
  1. items use any variation of "1.", "A)", and "(i)"
  2. also auto-enumerated
Definition list
Term is flush-left : optional classifier
Definition is indented, no blank line between
Field list
field name:field body
Option list
-o at least 2 spaces between option & description

5.3   Interpreted Text Roles

Role Name Description
algorithm Reference to a Siafoo algorithm by id
article Reference to a Siafoo article by id
group Reference to a Siafoo group by id
help Reference to a Siafoo help page by id or name
library Reference to a Siafoo library by id
snippet Reference to a Siafoo snippet by id
math Inline LaTeX-style math
book Reference to a book by ISBN
emphasis Equivalent to emphasis
literal Equivalent to literal but processes backslash escapes
PEP Reference to a numbered Python Enhancement Proposal
RFC Reference to a numbered Internet Request For Comments
strong Equivalent to strong
sub Subscript
sup Superscript
title Title reference (book, etc.); standard default role

See http://docutils.sf.net/docs/ref/rst/roles.html for more information on specific interpreted text roles.

5.4   Directives Reference

Directive Name Description
image .. image:: image_id; many options possible
figure Like "image", but with optional caption and legend
youtube Embed a youtube video with .. youtube:: video_id_or_url
snippet Embed an auto-updating snippet with .. snippet:: id
code Highlight a code block by including it in a .. code:: language block
linechart Create a line chart
piechart Create a pie chart
barchart Create a bar chart
graph Create a flow graph in Graph::Easy, GraphViz or VCG formats
math Render LaTeX-style math
book Bibliography-style book references
attention Specific admonition; also "caution", "danger", "error", "hint", "important", "note", "tip", "warning"
admonition Generic titled admonition: .. admonition:: By The Way
topic .. topic:: Title; like a mini section
sidebar .. sidebar:: Title; like a mini parallel document
parsed-literal A literal block with parsed inline markup
rubric .. rubric:: Informal Heading
epigraph Block quote with class="epigraph"
highlights Block quote with class="highlights"
pull-quote Block quote with class="pull-quote"
compound Compound paragraphs
container Generic block-level container element
table Create a titled table
list-table Create a table from a uniform two-level bullet list
csv-table Create a table from CSV data
contents Generate a table of contents
sectnum Automatically number sections, subsections, etc.
target-notes Create an explicit footnote for each external target
replace Replacement text for substitution definitions
unicode Unicode character code conversion for substitution defs

See http://docutils.sf.net/docs/ref/rst/directives.html for more information on directives.