Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/msnoigrs/ox-rst
reStructuredText Back-End for Org-Mode Export Engine
https://github.com/msnoigrs/ox-rst
emacs emacs-lisp org-mode restructuredtext
Last synced: 3 months ago
JSON representation
reStructuredText Back-End for Org-Mode Export Engine
- Host: GitHub
- URL: https://github.com/msnoigrs/ox-rst
- Owner: msnoigrs
- Created: 2013-11-04T14:25:11.000Z (about 11 years ago)
- Default Branch: master
- Last Pushed: 2020-08-15T15:11:51.000Z (over 4 years ago)
- Last Synced: 2024-08-10T11:02:20.629Z (6 months ago)
- Topics: emacs, emacs-lisp, org-mode, restructuredtext
- Language: Emacs Lisp
- Homepage:
- Size: 135 KB
- Stars: 116
- Watchers: 8
- Forks: 18
- Open Issues: 18
-
Metadata Files:
- Readme: README.org
Awesome Lists containing this project
README
#+TITLE: reStructuredText Back-End for Org Export Engine
#+AUTHOR: Masanao Igarashi
#+EMAIL: [email protected]
#+DATE: 2019/08/13 00:00
#+DESCRIPTION:
#+KEYWORDS:
#+LANGUAGE: en
#+OPTIONS: H:4 num:nil toc:t ::t |:t ^:t -:t f:t *:t <:t
#+OPTIONS: tex:t todo:t pri:nil tags:t texht:nil
#+OPTIONS: author:t creator:nil email:nil date:t
* 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
#+BEGIN_SRC lisp
(require 'ox-rst)
#+END_SRC
* 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:
#+BEGIN_EXAMPLE
,#+TITLE: This is the title of the document
,#+AUTHOR: Author
,#+EMAIL: [email protected]
,#+DATE: 2019/08/13 00:00
,#+OPTIONS: author:t date:t email:t
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
=================================
This is the title of the document
=================================
:Author: Author
:Contact: [email protected]
:Date: 2019/08/13 00:00
#+END_SRC
** Headings
Org:
#+BEGIN_EXAMPLE
,* Heading 1
contents 1
,** Heading 1-1
contents 1-1
,*** Heading 1-1-3
contents 1-1-3
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
Heading 1
---------
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 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_SRC
** Special Characters
Org:
#+BEGIN_EXAMPLE
special characters * asterisk \ backspace
.. reStructuredText comment line
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
special characters \* asterisk \\ backspace
\.. reStructuredText comment line
#+END_SRC
** Paragraphs
*note* Org line breaks =\\= will be ignored.
*** Verse block
Org:
#+BEGIN_EXAMPLE
,#+BEGIN_VERSE
Great clouds overhead
Tiny black birds rise and fall
Snow covers Emacs
-- AlexSchroeder
,#+END_VERSE
#+END_EXAMPLE
reStructuredText Line Blocks:
#+BEGIN_SRC rst
| Great clouds overhead
| Tiny black birds rise and fall
| Snow covers Emacs
|
| -- AlexSchroeder
#+END_SRC
*** Quote block
Org:
#+BEGIN_EXAMPLE
,#+BEGIN_QUOTE
Everything should be made as simple as possible,
but not any simpler -- Albert Einstein
,#+END_QUOTE
#+END_EXAMPLE
reStructuredText Literal Blocks:
#+BEGIN_SRC rst
::
Everything should be made as simple as possible,
but not any simpler -- Albert Einstein
#+END_SRC
Org:
#+BEGIN_EXAMPLE
,#+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
#+END_EXAMPLE
reStructuredText Block Quotes:
#+BEGIN_SRC rst
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
#+END_SRC
Org:
#+BEGIN_EXAMPLE
,#+ATTR_RST: :directive note
,#+BEGIN_QUOTE
Everything should be made as simple as possible,
but not any simpler -- Albert Einstein
,#+END_QUOTE
#+END_EXAMPLE
reStructuredText Directives:
#+BEGIN_SRC rst
.. note::
Everything should be made as simple as possible,
but not any simpler -- Albert Einstein
#+END_SRC
Org:
#+BEGIN_EXAMPLE
,#+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
#+END_EXAMPLE
reStructuredText Directives with title:
#+BEGIN_SRC rst
.. sidebar:: sidebar title
Everything should be made as simple as possible,
but not any simpler -- Albert Einstein
#+END_SRC
*** Special blocks
Org:
#+BEGIN_EXAMPLE
,#+BEGIN_caution
This is the second line of the first paragraph.
,#+END_caution
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
.. caution::
This is the second line of the first paragraph.
#+END_SRC
Org:
#+BEGIN_EXAMPLE
,#+ATTR_RST: :title This is a note admonition.
,#+BEGIN_note
This is the second line of the first paragraph.
,#+END_note
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
.. note:: This is a note admonition.
This is the second line of the first paragraph.
#+END_SRC
*** Center block
Center block will not affect.
Org:
#+BEGIN_EXAMPLE
,#+BEGIN_CENTER
center block
,#+END_CENTER
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
center block
#+END_SRC
** Literal examples
*** example block
Org:
#+BEGIN_EXAMPLE
,#+NAME: label
,#+BEGIN_EXAMPLE
example
,#+END EXAMPLE
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
::
:name: label
example
#+END_SRC
*** src block
Org:
#+BEGIN_EXAMPLE
,#+BEGIN_SRC lisp
(require 'ox-rst)
,#+END_SRC
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
.. code-block:: lisp
(require 'ox-rst)
#+END_SRC
** Emphasis and monospace
Org:
#+BEGIN_EXAMPLE
,*bold* /italic/ _underlined_ =verbatim= ~code~ +strike-through+
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
,**bold** *italic* underlined ``verbatim`` ``code`` strike-through
#+END_SRC
** Subscript and superscript
Org:
#+BEGIN_EXAMPLE
H_{2}O
E = mc^2
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
H\ :sub:`2`\ O
E = mc\ :sup:`2`\
#+END_SRC
** LaTeX fragments
Org:
#+BEGIN_EXAMPLE
If $a^2=b$ and \( b=2 \), then the solution must be
either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \].
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
If :math:`a^2=b` and :math:`b=2`, then the solution must be
either
.. math::
a=+\sqrt{2}
or
.. math::
a=-\sqrt{2}
.
#+END_SRC
** Horizontal rules
Org:
#+BEGIN_EXAMPLE
-----
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
------------
#+END_SRC
** Comment block
Comment block will disapper.
Org:
#+BEGIN_EXAMPLE
,#+BEGIN_COMMENT
comment
,#+END_COMMENT
#+END_EXAMPLE
** Images and Tables
*** Images
Org:
#+BEGIN_EXAMPLE
,#+ATTR_RST: :alt alternate text :align right
[[./image.jpg]]
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
.. image:: ./image.jpg
:alt: alternate text
:align: right
#+END_SRC
Org:
#+BEGIN_EXAMPLE
,#+CAPTION: image caption
,#+ATTR_RST: :alt alternate text :align center :scale 50%
[[./image.jpg]]
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
.. figure:: ./image.jpg
:alt: alternate text
:align: center
:scale: 50%
image caption
#+END_SRC
*** Tables
Org:
#+BEGIN_EXAMPLE
| TOP1 | TOP2 | TOP3 |
| 1 | 2 | 3 |
| AAAA | BBBB | CCCC |
| END1 | END2 | END3 |
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
.. table::
+------+------+------+
| TOP1 | TOP2 | TOP3 |
+------+------+------+
| 1 | 2 | 3 |
+------+------+------+
| AAAA | BBBB | CCCC |
+------+------+------+
| END1 | END2 | END3 |
+------+------+------+
#+END_SRC
Org:
#+BEGIN_EXAMPLE
| TOP1 | TOP2 | TOP3 |
|------+------+------|
| 1 | 2 | 3 |
| AAAA | BBBB | CCCC |
| END1 | END2 | END3 |
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
.. table::
+------+------+------+
| TOP1 | TOP2 | TOP3 |
+======+======+======+
| 1 | 2 | 3 |
+------+------+------+
| AAAA | BBBB | CCCC |
+------+------+------+
| END1 | END2 | END3 |
+------+------+------+
#+END_SRC
Org:
#+BEGIN_EXAMPLE
|------+------+------|
| TOP1 | TOP2 | TOP3 |
|------+------+------|
| 1 | 2 | 3 |
|------+------+------|
| AAAA | BBBB | CCCC |
|------+------+------|
| END1 | END2 | END3 |
|------+------+------|
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
.. table::
+------+------+------+
| TOP1 | TOP2 | TOP3 |
+======+======+======+
| 1 | 2 | 3 |
+------+------+------+
| AAAA | BBBB | CCCC |
+------+------+------+
| END1 | END2 | END3 |
+------+------+------+
#+END_SRC
Org:
#+BEGIN_EXAMPLE
,#+CAPTION: caption
,#+NAME: label
| TOP1 | TOP2 | TOP3 |
|------+------+------|
| 1 | 2 | 3 |
| AAAA | BBBB | CCCC |
| END1 | END2 | END3 |
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
.. table:: caption
:name: label
+------+------+------+
| TOP1 | TOP2 | TOP3 |
+======+======+======+
| 1 | 2 | 3 |
+------+------+------+
| AAAA | BBBB | CCCC |
+------+------+------+
| END1 | END2 | END3 |
+------+------+------+
#+END_SRC
** Hyperlinks
*** External hyperlinks
Org:
#+BEGIN_EXAMPLE
[[http://orgmode.org][Org Mode]]
[[http://orgmode.org]]
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
`Org Mode `_
`http://orgmode.org`_
#+END_SRC
*** Internal links
Org:
#+BEGIN_EXAMPLE
This is an <> cross reference target.
Internal cross references, like [[example]]
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
This is an _`example` cross reference target.
Internal cross references, like `example`_
#+END_SRC
Org:
#+BEGIN_EXAMPLE
,* headline
Internal cross references, [[*headline]]
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
headline
--------
Internal cross references, `headline`_
#+END_SRC
Org:
#+BEGIN_EXAMPLE
,* headline
:PROPERTIES:
:CUSTOM_ID: customid
:END:
Internal cross references, headline [[#customid]]
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
.. _customid:
headline
--------
Internal cross references, headline `customid`_
#+END_SRC
Org:
#+BEGIN_EXAMPLE
,#+NAME: sampletable
| a | b | c |
| 1 | 2 | 3 |
Internal cross references, label [[sampletable]]
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
.. table::
:name: sampletable
+---+---+---+
| a | b | c |
+---+---+---+
| 1 | 2 | 3 |
+---+---+---+
Internal cross references, label `sampletable`_
#+END_SRC
Org:
#+BEGIN_EXAMPLE
,#+NAME: samplefigure
[[./image.jpg]]
Internal cross references, label [[samplefigure]]
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
.. _samplefigure:
.. image:: ./image.jpg
Internal cross references, label `samplefigure`_
#+END_SRC
** Footnote
Org:
#+BEGIN_EXAMPLE
,* 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]]
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
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 `_
.. [2] org-mode `http://orgmode.org `_
#+END_SRC
** Export reStructuredText fragments
Org:
#+BEGIN_EXAMPLE
See also @@rst::meth:`mypackage.mymodule.MyClass.mymethod()`@@.
#+RST: .. class:: alert
,#+BEGIN_EXPORT rst
.. class:: alert
,#+END_EXPORT
#+END_EXAMPLE
reStructuredText:
#+BEGIN_SRC rst
See also :meth:`mypackage.mymodule.MyClass.mymethod()`.
.. class:: alert
.. class:: alert
#+END_SRC