Emacs Stack Exchange is a question and answer site for those using, extending or developing Emacs. It only takes a minute to sign up.
Sign up to join this community
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.
#+END_export
#+BEGIN_export markdown
This block contains *Markdown*.
#+END_export
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.)
#+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?
etc/ORG-NEWS, I now see.
Sep 7, 2016 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
#+BEGIN_SRC rst
Section Header
==============
Subsection Header
-----------------
#+END_SRC
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"
