References

• RestructuredText
• RestructuredText Specification
• RestructuredText Demo
• Notes on Markdown

Introduction

RestructuredText and Markdown are the 2 most popular markup languages, that are useful for taking notes. You can easily convert them to HTML (or other) format later.

The RestructuredText was originally designed to document python code (similar to Javadoc for Java). as part of docutils project. See RestructuredText Specification for more information.

This is not a comprehensive specification. See original specification pages for comprehensive information. This provides some brief notes and summary of important features.

Section Headers

The headers are underlined and must be at least as long as the title text. The first under-and-over lined header is document title and excluded from TOC:

========================================================
This Document Title should have both under and over line
========================================================

Section title1
==============

Section Subtitle1
-----------------

Note that the order of headers defines subsections;  Since --- header appeared
after the === header, it becomes a subsection.
Recommended choices for section title characters are ``" = - : ' ' ~ ^ _ * + # < > "``

Bullet Lists

* First bullet
* Second bullet
* Third bullet

#. any number
#. For numeric list
#. This will be 3rd bullet number

Rendered like below:

• First bullet
• Second bullet
• Third bullet

1. any number
2. For numeric list
3. This will be 3rd bullet number

Note that a blank line is required before the first item and after the last, but is optional between items.

Paragraph

Paragraph is text surrounded by whitespace. Paragraphs can be on one line or can span many lines.

Inline Image

Image can be inserted using image directive. Example:

.. image:: picture.jpeg
   :height: 100px
   :width: 200 px
   :scale: 50 %
   :alt: alternate text
   :align: right

Typically it is used with substitution syntax like below:

Here is a |cat|

.. |cat| image:: cat.png

Inline Markups

Basic inline markup examples

This is _italics_, *emphasised*,  **bold**, and `code()`.

Rendered like below:

This is _italics_, emphasised,  bold, and code().

Note

*emphasis*           Maps to html em tag and italicised.
**strong emphasis**  Maps to html strong tab and bold faced.
`code()`             Typically maps to monospaced (using cite tag for example)
``literal``          Maps to html tt tag, teletype text ie. monospaced text.
                     (tt tag is deprecated and not in HTML5)

The `interpreted text` is domain specific -- implementation is free to choose.
``inline literal``  literal  rendered as monospaced text with spaces preserved.

Definition lists

It is a list of (term, definition) tuples. A term can have multiple defintions. Multiple terms (synonyms) can have single definition.

Example:

what
  Definition lists associate a term with
  a definition.

  Definition2 goes here.

Rendered as:

what

Definition lists associate a term with a definition.

Definition2 goes here.

Field Lists

Example:

:Author: All contributors
         for this
         project
:version: 1.0
:Date: 2013/01/20

Rendered as

Literal Blocks (Escape from RST syntax)

Literal blocks end when text returns to the preceding paragraph's indentation.

Line Blocks

Line blocks are like literal block, but they are non-monospaced, using regular font. It is also useful when you want to preserve some initial indents:

| Line blocks are useful for addresses,
| verse, and adornment-free lists.
|
| Each new line begins with a
| vertical bar
|     Line breaks and initial indents
|     are preserved.
|
| Continuation lines are wrapped
  portions of long lines; they begin
  with spaces in place of vertical bars.

Comments

Use following format to define comment. Start the line with .. followed by any text which is not any predefined directive

.. This text is a comment,
   this may be rendered as an HTML comment, for example.

An empty comment is a line containing ".." with blank lines before and after:

..

Transition Marker

Often you would like to explicitly terminate a bullet list or a field list, etc. Then you need a transition marker. An empty comment is perfect for this purpose:

..

You can also use the following for explicit transition marker:

Any 4 or more punctuation marks like those used for section titles:
--------

Some implementations may convert this to horizontal rule to mark transition.

Hyperlink Targets

The hyper links are used like below

The Python_ programming language.
..  _Python: http://www.python.org/

Use link_ for refering to a link. (_ suffix)
.. _link: URL  ===> Use this to define what the link is. (_ prefix)

For linking a phrase, you would use something like below:

The `Python programming language`_.
..  _Python programming language: http://www.python.org/

If the link is internal, then your link definition should just
precede the target element in the document like below:

See the later example_  in this document.

.. _example:

Target Example here.
Note that empty line after the directive is required.

Anonymous targets use 2 underscores __ suffix for one-time use.

Example:

   See unix__ operating system.
         .. __ : http://en.wikipedia.org/wiki/Unix

   See `Unix Operating System`__ for more info.
         __  unixos_   <=== This aliases one target to other.
         ..  _unixos: http://en.wikipedia.org/wiki/Unix

  http://docutils.sf.net/   A standalone hyperlink will be auto linked.

Hyperlink Auto Targets

Section titles, footnotes, and citations automatically generate hyperlink internal targets. This is very useful:

Example:  This refers to `My Subtitle`_ section if that section exists.

Directives

There are predefined set of directives. Examples include image, figure (which is image plus more custom attributes), table (to associate title with table), csv-table (to turn csv lines to table), contents (to generate TOC), header, footer (to add a para at the bottom of the page), replace (to use abbreviated forms), unicode (to specify char using unicode), etc. A directive can accept a set of attributes.

Examples

To inline an image:
  .. image:: images/ball1.gif

Following directives are supported for HTML only

.. meta::
   :description: The reStructuredText plaintext markup language
   :keywords: plaintext, markup language

.. contents:: My TOC Title
    :depth: 2    .. Max depth for listing. This is inline comment.

You can write your own directive if you like. See RST directive to embed Youtube video for an example.

Specifying class directive

Use the class directive using following syntax:

.. class:: class1 class2

The classes apply to the next immediate element, be it paragraph or header, table, etc.

Admonition Directives

There is a special types of directives called admonition directives. They are: "attention", "caution", "danger", "error", "hint", "important", "note", "tip", and "warning". Example

.. warning::
   This feature is deprecated (example warning)!

.. tip::
   Use admonition directives to nicely format your text with tips and notes and warnings.

Rendered as:

See RestructuredText Demo for more information.

Substitutions

Substitutions can be used to use an abbreviation for text or image like below:

The |cat| is out.
.. |cat| image:: cat.png

Look at |html|
.. |html| replace:: Hypertext Markup Language

Sidebar

You can have a sidebar and include the contents which are local to that section:

.. sidebar:: Contents
   :class: myclass

   .. contents:: :local:
   .. sectnum::
       :depth: 2

A separate <div> is created which is floated to the right.

Footnote Reference

Footnote reference is exactly like any other internal hyperlink mechanism. Only difference is that the target is automatically moved to the bottom, and may be autonumbered.

Example:

Footnote references, like [5]_.
Note that footnotes may get rearranged, e.g., to the bottom of the "page".

.. [5] A numerical footnote. (this is footnote definition at the bottom)

Autonumbered footnotes are possible, like using [#]_ and [#]_.

.. [#] This is the first one. (The numbers assigned during rendering.)
.. [#] This is the second one.

Citation Reference

Citation reference is like footnote reference, only difference is that a word is used to refer to the note instead of a number.

Example:

Example citation reference is [CIT2002]_.
Note that citations may get rearranged, e.g., to the bottom of the "page".
Citations auto generates the references backlinks also.
.. [CIT2002] A citation
   (as often used in journals).

Tables

+------------+------------+-----------+
| 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
=====  =====  ======

Embed HTML in RST

Use raw directive

.. raw:: html
   <hr width=50 size=10>

Including Files

You can include one file from other

.. include:: anotherfile.rst

Block Quotes

Indented paragraphs are generated as <blokquote> ... </blockquote> elements

This is first level blockquote

  This is second level blockquote. Leave blank line between paragraphs.

Another supported block type is doctest block. No indentation required:

>>> print 'this is Doctest block example'
this is Doctest block example

Note that the general > and >> email type blocks are not recognized by RestructuredText.

Syntax Highlighting

To trigger syntax highlighting on a block, use code directive

.. code:: python

def my_function():
    "exmple function"
    a = 10
    print a/2

Rendered as:

def my_function():
     "exmple function"
     a = 10
     print a/2

Using Common Syntax Between RST and Markdown

See https://gist.github.com/1855764 for an article about using common markup language of Markdown and RST. This is useful if you ever bother to quickly port between RST and Markdown.

Some interesting points to note are:

For literal blocks always indent with min 4 spaces.
This is required by markdown. RST is OK with any amount of indentation.

For ``mono spaced text`` use double backquotes.
This is required by RST. Markdown is OK with single backquote.

For code (literal) blocks use :: at end of preceding para
and leave empty line after that. (Required by RST)

For hard line breaks with non-monospaced literal block:
End line with 2 spaces (for markdown) and start the line with "| ".

For inline urls, always enclose them with angle brackets (required by Markdown).

Note that there is no straight forward way of writing portable comments
between RST and markdown. Markdown requires HTML comment <!--  --> syntax.

Source Document

This document has been written using RestructuredText and converted to HTML using rst2html command.

See the document source text