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

Comment block will disapper.

Org:

#+BEGIN_COMMENT
comment
#+END_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:

This is an <<example>> cross reference target.

Internal cross references, like [[example]]

reStructuredText:

This is an  _`example`  cross reference target.

Internal cross references, like `example`_

Org:

* headline

Internal cross references, [[*headline]]

reStructuredText:

headline
--------

Internal cross references, `headline`_

Org:

* headline
  :PROPERTIES:
  :CUSTOM_ID: customid
  :END:

Internal cross references, headline [[#customid]]

reStructuredText:

.. _customid:

headline
--------

Internal cross references, headline `customid`_

Org:

#+NAME: sampletable
| a | b | c |
| 1 | 2 | 3 |

Internal cross references, label [[sampletable]]

reStructuredText:

.. table::
  :name: sampletable

  +---+---+---+
  | a | b | c |
  +---+---+---+
  | 1 | 2 | 3 |
  +---+---+---+

Internal cross references, label `sampletable`_

Org:

#+NAME: samplefigure
[[./image.jpg]]

Internal cross references, label [[samplefigure]]

reStructuredText:

.. _samplefigure:

.. image:: ./image.jpg

Internal cross references, label `samplefigure`_

Footnote

Org:

* footnote sample

Org mode[fn:org] is for keeping notes, maintaining TODO lists, planning projects, and authoring documents with a fast and effective plain-text system.

reStructuredText[fn:rest] is plaintext that uses simple and intuitive constructs to indicate the structure of a document.

[fn:org] org-mode [[http://orgmode.org]]
[fn:rest] reStructuredText [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html]]

reStructuredText:

footnote sample
---------------

Org mode [2]_  is for keeping notes, maintaining TODO lists, planning projects, and authoring documents with a fast and effective plain-text system.

reStructuredText [1]_  is plaintext that uses simple and intuitive constructs to indicate the structure of a document.


.. [1] reStructuredText `http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html>`_

.. [2] org-mode `http://orgmode.org <http://orgmode.org>`_

Export reStructuredText fragments

Org:

#+RST: .. class:: alert

reStructuredText:

.. class:: alert