Ox-Rst¶

Ox-Rst exports your Org documents to reStructuredText. Ox-Rst relies on the Org-mode 9.0 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: mailaddress@example.com
#+DATE: 2019/08/13 00:00
#+OPTIONS: author:t date:t email:t

reStructuredText:

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

    :Author: Author
    :Contact: mailaddress@example.com
    :Date: 2019/08/13 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

Special blocks¶

Org:

#+BEGIN_caution
This is the second line of the first paragraph.
#+END_caution

reStructuredText:

.. caution::

    This is the second line of the first paragraph.

Org:

#+ATTR_RST: :title This is a note admonition.
#+BEGIN_note
This is the second line of the first paragraph.
#+END_note

reStructuredText:

.. note:: This is a note admonition.

    This is the second line of the first paragraph.

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_ =verbatim= ~code~ +strike-through+

reStructuredText:

**bold** *italic* underlined ``verbatim`` ``code`` 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:

See also @@rst::meth:`mypackage.mymodule.MyClass.mymethod()`@@.

#+RST: .. class:: alert

#+BEGIN_EXPORT rst
.. class:: alert
#+END_EXPORT

reStructuredText:

See also :meth:`mypackage.mymodule.MyClass.mymethod()`.

.. class:: alert

.. class:: alert

Org book

Ox-Rst¶

Configuration¶

reStructuredText export¶

reStructuredText commands¶

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

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

Title, Author, E-Mail and Date¶

Headings¶

Table of contents¶

Lists¶

Special Characters¶

Paragraphs¶

Verse block¶

Quote block¶

Special blocks¶

Center block¶

Literal examples¶

example block¶

src block¶

Emphasis and monospace¶

Subscript and superscript¶

LaTeX fragments¶

Horizontal rules¶

Comment block¶

Images and Tables¶

Images¶

Tables¶

Hyperlinks¶

External hyperlinks¶

Internal links¶

Footnote¶

Export reStructuredText fragments¶

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

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