Ox-Rst
Ox-Rst exports your [[http://orgmode.org][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:
: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:
contents 1
Heading 1-1
contents 1-1
Heading 1-1-3
^^^^^^^^^^^^^
contents 1-1-3
#+END_SRC
** Table of contents
Org:
#+BEGIN_EXAMPLE
,#+OPTIONS: toc:t
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
.. contents::
#+END_SRC
** Lists
Org:
#+BEGIN_EXAMPLE
,** 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.
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
Lord of the RingsThe attack of the Rohirrim
Eowyn's fight with the witch king
this was already my favorite scene in the book
I really like Miranda Otto.
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 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 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]]
reStructuredText:
Org Mode <http://orgmode.org/>_
http://orgmode.org_
*** Internal links
Org:
This is an <
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:
Internal cross references, headline_
Org:
,* headline :PROPERTIES: :CUSTOM_ID: customid :END:
Internal cross references, headline [[#customid]]
reStructuredText:
.. _customid:
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:
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()@@.
,#+BEGIN_EXPORT rst .. class:: alert ,#+END_EXPORT
reStructuredText:
See also :meth:mypackage.mymodule.MyClass.mymethod().
.. class:: alert
.. class:: alert