How can one include ReStructuredText or markdown snippets in org document, so that when org file is exported in corresponding format, those snippets are part of text?

Can that be done with org-mode built-in exporters? Or with pandoc?

Rationale: rst format supports grid tables (unlike org), so i want to take and use them in my document. 2-step export (first to rst or markdown, then to html or docx or odt) will get me document i need.


In theory, you should be able to define backend-specific snippets with @@markdown:**markdown snippet**@@ or, starting with org-mode 9, exports blocks (#+BEGIN_export markdown#+END_export markdown). However, it seems that not all backends support this, I could only get this working with HTML and LaTeX.

To give a simple example:

This document was exported as @@html:<strong>html</strong>@@
@@rst:**rst**@@ @@markdown:`markdown`@@

#+BEGIN_export rst
This should only show up in reStructuredText.

#+BEGIN_export markdown
This block contains *Markdown*.

In the case at hand, you may get better results using Pandoc. Only a limited subset of org-features is supported by pandoc, but export snippets and export blocks should work. Simply invoke pandoc as pandoc -f org -t rst -o target-file.rst your-org-input-file.org. The result for the above example would be

This document was exported as **rst**

This should only show up in reStructuredText.

.. raw:: markdown

   This block should only show up in Markdown.

Note that inline snippets are dropped if they are not supported by the target format. The Markdown-block is kept as RST allows to define raw blocks the same way org-mode does. One would have to use a pandoc-filter to remove that block if it's not wanted.

(Disclaimer: I'm a pandoc contributor and hence biased, so take that recommendation with a grain of salt.)

  • For sake of clarity: if #+BEGIN_EXPORT directive with markdown or ReST is encountered by pandoc, it carries its contents to destination (if destination is of the same format) faithfully, is that right? If possible, could you add minimal example with pandoc invocation? – Srv19 Sep 7 '16 at 11:41
  • Org-mode 9? This is the first I am hearing of it (and I am staying current with the git repo, more or less). Do you have a link where I can learn more? – Harald Hanche-Olsen Sep 7 '16 at 12:31
  • @HaraldHanche-Olsen This news file was the best I could find atm. – tarleb Sep 7 '16 at 15:03
  • Ah, thanks. Also available in the source code as etc/ORG-NEWS, I now see. – Harald Hanche-Olsen Sep 7 '16 at 20:13

install corresponding major-mode. The language tag used after #+BEGIN_SRC is the major mode name with sub-string "-mode" removed.

For rst-mode, the language tag should be rst (sub-string "-mode" stripped), so the complete code in org mode should be

Section Header

Subsection Header

If your purpose is render markdown or rst into html and you want to manage the source code of documents in org-mode, you'd better convert rst/markdown to org format at first, then use #+SETUPFILE to include the converted org.

#+SETUPFILE: "shared/rst-converted.org"
  • How installing a mode (which, for restructured text is built-in) would help during export? Could you explain a bit further about using block you mentioned? – Srv19 Sep 7 '16 at 9:43
  • What i want from rst at the moment are its tables. It seems that converting rst to org will not work in their regard (well, they will be converted - but they will lose multi-line cell contents) – Srv19 Sep 8 '16 at 10:51
  • don't know much about rst able. but looks similar to org-mode.embed the table in rst code snippet so you conversion tool wont convert rst table. then in org-mode, manually tweak the table. – chen bin Sep 9 '16 at 0:24

Your Answer

