Basic Functions of reStructured Text

1. Paragraphs

This is the main thing to remember in reStructured Text: to add paragraphs, just type them in as you would normally, leaving a space between each paragraph.

In other words, if you dont want to add links or images or any of that stuff, you can use reStructured Text without having to learn reStructured Text at all!

2. Links

If you type in

Internal link = `plone basics </plone_basics>`__

External Link = `reStructured text <http://docutils.sourceforge.net/rst.html>`__

This will show up like:

Internal link = plone basics

External Link = reStructured text

One thing to be careful of: links in reStructured Text use backquotes (`), not apostrophes ('). Backquotes can be found up in the top left corner of the keyboard beside the number 1, although that will vary depending on what language keyboard you are using.

3. Images

On a new line, type in:

.. figure:: /images/vasudevaserver.gif
     :alt: vasudevaserver

     This is the caption

This gives you:

This is the caption.

Note that for the caption, we skipped a line and added text in line with the colon.

To align the image left or right, it is best to define a css class. On sites where Vasudeva Service products are used we would define a 'float-left', 'float-centre' or 'align-right' class which is called by adding

:figclass: float-right

below the :alt:. So

.. figure:: /images/vasudevaserver.gif
   :alt: vasudevaserver
   :figclass: float-centre
   :width: 300

   Here is the caption for my image.

Produces something like

Here is the caption for my image.

Note that our float classes also made the caption nicer.

4. Literal Block

Literal blocks are written like this:

::

  (Content of literal blocks)
  Restructured text leaves it alone
  and puts it in a box

A literal block is content that ReStructured Text will leave untouched, including it exactly it as you wrote it. Note the way the paragraph is indented inwards from the double colon. The literal block stops if there is a blank line and the next line is unindented.

All of the boxed reStructured Text commands on this page are written as literal blocks.

However, you'll note that in the above example we pressed return at the end of each line. If you don't do it for long lines youll get a scrollbar like this.

5. White space

To add white space use | as shown below:

|
|
|

Which gives you three lines of white space:

6. Bold and Italics

Putting an asterisk either side gives *italics*,
two asterisks either side gives **bold**.

Putting an asterisk either side gives italics, two asterisks either side gives bold.

7. Bullets and numbered lists

- Bulleted lists have a very intuitive syntax,
  you can also use * or + in place of the dash.

- Just remember to leave a space between each entry

  - You can also create nested lists by indenting....


1. It is similarly very easy to create numbered lists.

2. The exact same rules apply.

This shows up as:

• Bulleted lists are very intuitive, you can also use * or + in place of the dash.
• Just remember to leave a space between each entry
  • You can also create nested lists by indenting....

1. It is similarly very easy to create numbered lists.
2. The exact same rules apply.

8. Using special characters normally.

As you see, `*`, `-`, `+`, `|` are all special
characters, but if you put backquotes around them
you can include them in normal text.

As you see, *, -, +, | are all special characters, but if you put backquotes around them you can include them in normal text.

9. Creating a headings and subheadings

Typing in

Create Heading
---------------

Create Subheading
~~~~~~~~~~~~~~~~~~

gives

Create Heading

10. Tables

We will look at 3 ways to make a table:

+------------+------------+-----------+
| Header 1   | Header 2   | Header 3  |
+============+============+===========+
| body row 1 | column 2   | column 3  |
+------------+------------+-----------+
| body row 2 | Cells may span columns.|
+------------+------------+-----------+
| body row 3 | Cells may  | - Cells   |
+------------+ span rows. | - contain |
| body row 4 |            | - blocks. |
+------------+------------+-----------+

=====  =====  ======
  Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======

.. csv-table:: 2-mile race!
   :header: "Runner", "Time", "Description"
   :widths: 15, 10, 30

   "Prachar", 10.19, "Way to go!"
   "Dhanu", 16.49, "Ouch."
   "Priyadarshan", 31.99, "No comment..."

More Advanced Restructured Text:

• A Restructured Text Primer
• Two Directives `Sidebar and Figure
• Changing to Restructured Text
• Restructured Text Blog Category
• Polaroid Effect - An example of using CSS classes in reStructured Text. This article is also very good to read if you want to know why we like reStructured Text so much.

For Comprehensive Guide to Restructured Text See:

• Quick Ref Guide