reStructuredText Back-End for Org Export Engine
- Ox-Rst
- Configuration
- reStructuredText export
- reStructuredText commands
- Title, Author, E-Mail and Date
- Headings
- Table of contents
- Lists
- Special Characters
- Paragraphs
- Literal examples
- Emphasis and monospace
- Subscript and superscript
- LaTeX fragments
- Horizontal rules
- Comment block
- Images and Tables
- Hyperlinks
- Footnote
- Export reStructuredText fragments
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: mailaddress@example.com #+DATE: 2013/12/31 00:00 #+OPTIONS: author:t date:t email:t
reStructuredText:
This is the title of the document
=================================
:Author: Author
:Contact: mailaddress@example.com
:Date: 2013/12/31 00:00Headings
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-3Table 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 lineParagraphs
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
|
| -- AlexSchroederQuote 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 EinsteinOrg:
#+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 EinsteinOrg:
#+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 EinsteinOrg:
#+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 EinsteinCenter block
Center block will not affect.
Org:
#+BEGIN_CENTER center block #+END_CENTER
reStructuredText:
center blockLiteral examples
example block
Org:
#+NAME: label #+BEGIN_EXAMPLE example #+END EXAMPLE
reStructuredText:
::
:name: label
examplesrc 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-throughSubscript 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:
..
commentImages and Tables
Images
Org:
#+ATTR_RST: :alt alternate text :align right [[./image.jpg]]
reStructuredText:
.. image:: ./image.jpg
:alt: alternate text
:align: rightOrg:
#+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 captionTables
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