reStructuredText Back-End for Org Export Engine

Ox-Rst

Ox-Rst exports your Org documents to reStructuredText. Ox-Rst relies on the Org-mode 8.3 export framework.

Configuration

Add the following in your init.el

(require 'ox-rst)

reStructuredText export

ox-rst export back-end generates reStructuredText syntax for an Org mode buffer.

reStructuredText commands

To export your org document to, press C-c C-e, and then r.

C-c C-e r r (org-rst-export-to-rst)

Export as a text file written in reStructured syntax. For an Org file, myfile.org, the resulting file will be myfile.rst. The file will be overwritten without warning.

C-c C-e r R (org-rst-export-as-rst)

Export as a temporary buffer. Do not create a file.

Title, Author, E-Mail and Date

Org:

#+TITLE: This is the title of the document
#+AUTHOR: Author
#+EMAIL: [email protected]
#+DATE: 2013/12/31 00:00
#+OPTIONS: author:t date:t email:t

reStructuredText:

This is the title of the document
==================================================================

    :Author: Author
    :Contact: [email protected]
    :Date: 2013/12/31 00:00

Headings

Org:

* Heading 1

contents 1

** Heading 1-1

contents 1-1

*** Heading 1-1-3

contents 1-1-3

reStructuredText:

Heading 1
---------

contents 1

Heading 1-1
~~~~~~~~~~~

contents 1-1

Heading 1-1-3
^^^^^^^^^^^^^

contents 1-1-3

Table of contents

Org:

#+OPTIONS: toc:t

reStructuredText:

.. contents::

Lists

Org:

** Lord of the Rings
1. The attack of the Rohirrim
2. Eowyn's fight with the witch king
   + this was already my favorite scene in the book
   + I really like Miranda Otto.
3. Peter Jackson being shot by Legolas
   - on DVD only
   He makes a really funny face when it happens.
But in the end, no individual scenes matter but the film as a whole.
Important actors in this film are:
- Elijah Wood :: He plays Frodo
- Sean Austin :: He plays Sam, Frodo's friend.  I still remember
  him very well from his role as Mikey Walsh in The Goonies.

reStructuredText:

Lord of the Rings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. The attack of the Rohirrim

2. Eowyn's fight with the witch king

   - this was already my favorite scene in the book

   - I really like Miranda Otto.

3. Peter Jackson being shot by Legolas

   - on DVD only

   He makes a really funny face when it happens.

But in the end, no individual scenes matter but the film as a whole.
Important actors in this film are:

Elijah Wood
    He plays Frodo

Sean Austin
    He plays Sam, Frodo's friend.  I still remember
    him very well from his role as Mikey Walsh in The Goonies.

Special Characters

Org:

special characters * asterisk \ backspace
.. reStructuredText comment line

reStructuredText:

special characters \* asterisk \\ backspace
\.. reStructuredText comment line

Paragraphs

note Org line breaks \\ will be ignored.

Verse block

Org:

#+BEGIN_VERSE
 Great clouds overhead
      Tiny black birds rise and fall
      Snow covers Emacs

          -- AlexSchroeder
#+END_VERSE

reStructuredText Line Blocks:

| Great clouds overhead
|      Tiny black birds rise and fall
|      Snow covers Emacs
|
|          -- AlexSchroeder

Quote block

Org:

#+BEGIN_QUOTE
Everything should be made as simple as possible,
  but not any simpler -- Albert Einstein
#+END_QUOTE

reStructuredText Literal Blocks:

::

    Everything should be made as simple as possible,
      but not any simpler -- Albert Einstein

Org:

#+ATTR_RST: :margin 4
#+BEGIN_QUOTE
Everything should be made as simple as possible,
but not any simpler -- Albert Einstein
#+END_QUOTE

#+ATTR_RST: :margin 8
#+BEGIN_QUOTE
Everything should be made as simple as possible,
but not any simpler -- Albert Einstein
#+END_QUOTE

reStructuredText Block Quotes:

Everything should be made as simple as possible,
but not any simpler -- Albert Einstein

    Everything should be made as simple as possible,
    but not any simpler -- Albert Einstein

Org:

#+ATTR_RST: :directive note
#+BEGIN_QUOTE
Everything should be made as simple as possible,
but not any simpler -- Albert Einstein
#+END_QUOTE

reStructuredText Directives:

.. note::

    Everything should be made as simple as possible,
    but not any simpler -- Albert Einstein

Org:

#+ATTR_RST: :directive sidebar :title sidebar title
#+BEGIN_QUOTE
Everything should be made as simple as possible,
but not any simpler -- Albert Einstein
#+END_QUOTE

reStructuredText Directives with title:

.. sidebar:: sidebar title

    Everything should be made as simple as possible,
    but not any simpler -- Albert Einstein

Center block

Center block will not affect.

Org:

#+BEGIN_CENTER
center block
#+END_CENTER

reStructuredText:

center block

Literal examples

example block

Org:

#+NAME: label
#+BEGIN_EXAMPLE
example
#+END_EXAMPLE

reStructuredText:

::
    :name: label

    example

src block

Org:

#+BEGIN_SRC lisp
(require 'ox-rst)
#+END_SRC

reStructuredText:

.. code-block:: lisp

    (require 'ox-rst)

Emphasis and monospace

Org:

*bold* /italic/ _underlined_ =code= ~verbatim~ +strike-through+

reStructuredText:

**bold** *italic* underlined ``code`` ``verbatim`` strike-through

Subscript and superscript

Org:

H_{2}O
E = mc^2

reStructuredText:

H\ :sub:`2`\ O
E = mc\ :sup:`2`\ 

LaTeX fragments

Org:

If $a^2=b$ and \( b=2 \), then the solution must be
either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \].

reStructuredText:

  If :math:`a^2=b` and :math:`b=2`, then the solution must be
either 

.. math::

    a=+\sqrt{2}

 or 

.. math::

    a=-\sqrt{2}

.

Horizontal rules

Org:

-----

reStructuredText:

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

Comment block

Org:

#+BEGIN_COMMENT
comment
#+END_COMMENT

reStructuredText:

..
    comment

Images and Tables

Images

Org:

#+ATTR_RST: :alt alternate text :align right
[[./image.jpg]]

reStructuredText:

.. image:: ./image.jpg
    :alt: alternate text
    :align: right

Org:

#+CAPTION: image caption
#+ATTR_RST: :alt alternate text :align center :scale 50%
[[./image.jpg]]

reStructuredText:

.. figure:: ./image.jpg
    :alt: alternate text
    :align: center
    :scale: 50%

    image caption

Tables

Org:

| TOP1 | TOP2 | TOP3 |
| 1    | 2    | 3    |
| AAAA | BBBB | CCCC |
| END1 | END2 | END3 |

reStructuredText:

.. table::

    +------+------+------+
    | TOP1 | TOP2 | TOP3 |
    +------+------+------+
    | 1    | 2    | 3    |
    +------+------+------+
    | AAAA | BBBB | CCCC |
    +------+------+------+
    | END1 | END2 | END3 |
    +------+------+------+

Org:

| TOP1 | TOP2 | TOP3 |
|------+------+------|
| 1    | 2    | 3    |
| AAAA | BBBB | CCCC |
| END1 | END2 | END3 |

reStructuredText:

.. table::

    +------+------+------+
    | TOP1 | TOP2 | TOP3 |
    +======+======+======+
    | 1    | 2    | 3    |
    +------+------+------+
    | AAAA | BBBB | CCCC |
    +------+------+------+
    | END1 | END2 | END3 |
    +------+------+------+

Org:

|------+------+------|
| TOP1 | TOP2 | TOP3 |
|------+------+------|
| 1    | 2    | 3    |
|------+------+------|
| AAAA | BBBB | CCCC |
|------+------+------|
| END1 | END2 | END3 |
|------+------+------|

reStructuredText:

.. table::

    +------+------+------+
    | TOP1 | TOP2 | TOP3 |
    +======+======+======+
    | 1    | 2    | 3    |
    +------+------+------+
    | AAAA | BBBB | CCCC |
    +------+------+------+
    | END1 | END2 | END3 |
    +------+------+------+

Org:

#+CAPTION: caption
#+NAME: label
| TOP1 | TOP2 | TOP3 |
|------+------+------|
| 1    | 2    | 3    |
| AAAA | BBBB | CCCC |
| END1 | END2 | END3 |

reStructuredText:

.. table:: caption
    :name: label

    +------+------+------+
    | TOP1 | TOP2 | TOP3 |
    +======+======+======+
    | 1    | 2    | 3    |
    +------+------+------+
    | AAAA | BBBB | CCCC |
    +------+------+------+
    | END1 | END2 | END3 |
    +------+------+------+

Hyperlinks

External hyperlinks

Org:

[[http://orgmode.org][Org Mode]]

[[http://orgmode.org]]

reStructuredText:

`Org Mode <http://orgmode.org/>`_

`http://orgmode.org`_

Internal links

Org:

Internal crossreferences, like [[example]]

<<example>>
This is an example crossreference target.

reStructuredText:

Internal crossreferences, like `example`_


.. _example:


This is an example crossreference target.

Export reStructuredText fragments

Org:

#+RST: .. class:: alert

reStructuredText:

.. class:: alert