ox-pandoc is an
exporter for
Org mode which converts Org-mode files to a
wide variety of other formats using the pandoc
tool. Pandoc can produce PDFs, HTML, presentations, markdown files,
office documents and e-pub publications as well as a number of other
more specialised formats.
You need Emacs 24.4, org-mode 8.2, and Pandoc 2.0 (or later versions). A recent version of Pandoc is recommended.
Note that the support for citations in newest versions of org-mode (9.5+) require a similarly recent version of Pandoc (2.17+).
Installing Pandoc directly from the official website is recommended. The versions of Pandoc provided by package managers and distributions is often quite out-of-date and may be missing features or formats added to it.
By default, ox-pandoc will check on starting up whether there is a
suitable pandoc executable available. When none is found, or the version
is too old, a warning will be emitted. This warning can be suppressed
by setting customisation option org-pandoc-check-version to nil.
You can install this tool with MELPA. For example,
(setq package-archives
'(("gnu" . "http://elpa.gnu.org/packages/")
("melpa" . "http://melpa.milkbox.net/packages/")))M-x package-install ⏎ ox-pandoc ⏎
As always in Org, C-c C-e brings up the export dispatch menu for
the current org-mode file. ox-pandoc lives under the p key. By
default, options are offered to convert the org-file to a number of
commonly used and generic formats, such as LaTeX, PDF, HTML, markdown
and word-processor files.
Pandoc and ox-pandoc support a very large number of output formats.
To avoid cluttering Org’s export menu, most formats are not shown by
default. For example, most application-specific formats, markdown
dialects and slides are not included. You can customize the
org-pandoc-menu-entry variable (and probably restart Emacs) to
change the menu entries to include those you commonly use. A full
list of exporting commands and suggested shortcuts can be found in
ox-pandoc.el.
The exporters can be called directly via M-x. For example, to convert
org-mode file to ‘html5’ format, you may run the following commands:
org-pandoc-export-as-html5- Exports to the HTML5 text as a buffer.
org-pandoc-export-to-html5- Exports to the HTML5 text file.
org-pandoc-export-to-html5-and-open- Exports and open HTML5 file.
All of the formats supported by ox-pandoc have corresponding commands
named in this way. org-pandoc-export-as-[FORMAT] exports to a buffer
and org-pandoc-export-to-[FORMAT] exports to a file. Note that some
formats (e.g. PDF) can only be exported to a file, not to a buffer.
The opening of exported files in the XXX-and-open variants is handled
by org-open-file. Which applications are used for different file types
can be customised in Org Mode by the org-file-apps variable.
The pandoc command supports a
large number of options
which can be used to control how the document is processed and how the
output should appear. In ox-pandoc these options can be specified for
individual documents or set as
defaults for specific formats.
The following document-specific options can be specified. Value nil
overrides preceding option setting. Value t means only specify
option, but not its value. Options are delimited by space.
#+PANDOC_OPTIONS: can be specified multiple times. If you want to
specify the option value which include space character, the entire
option-value pair must be quoted (see example below).
PANDOC_OPTIONS:- Add command line options to the Pandoc process.
PANDOC_METADATA:- Metadata for Pandoc.
PANDOC_EXTENSIONS:- Extensions for specific Pandoc output.
PANDOC_VARIABLES:- Variables for Pandoc.
EPUB_RIGHTS:- copyright info to be embedded to EPUB metadata.
EPUB_CHAPTER_LEVEL:- same as ‘epub-chapter-level’ pandoc-option.
EPUB_STYLESHEET:- same as ‘epub-stylesheet’ pandoc-option.
EPUB_COVER:- same as ‘epub-cover-image’ pandoc-option.
EPUB_FONT:- same as ‘epub-embed-font’ pandoc-option. Only one font can be specified in each line. Multiple fonts can be specified by repeatedly use this option.
EPUB_META:- put contents into a temporary file and specify that file to ‘epub-metadata’ option.
EPUB_CSS:- put contents into a temporary file and specify that file to ‘epub-stylesheet’ option.
BIBLIOGRAPHY:- same as ‘bibliography’ pandoc-option. Only one bibliography can be specified in each line. Multiple bibliographies can be specified by repeatedly use this option.
Following is an example:
#+PANDOC_OPTIONS: standalone:t pdf-engine:pdflatex
## When option value includes whitespace, entire name:value pair must be quoted.
#+PANDOC_OPTIONS: "epub-cover-image:/home/a/test file.png" standalone:nil
#+PANDOC_OPTIONS: number-sections:nil
#+PANDOC_OPTIONS: template:mytemplate.tex
#+BIBLIOGRAPHY: sample.bib
# Specifying Multiple values to single options by using colon-sparated lists.
#+PANDOC_OPTIONS: filter:pandoc-zotxt:pandoc-citeproc
#+PANDOC_OPTIONS: csl:IEEE.csl
#+PANDOC_EXTENSIONS: markdown-typography latex+auto_identifiers
#+PANDOC_VARIABLES: documentclass:IEEEtran
#+PANDOC_VARIABLES: classoption:10pt,conference
#+PANDOC_METADATA: page-progression-direction:ltr
#+latex_header: \author{\IEEEauthorblockN{John Smith}
#+latex_header: \IEEEauthorblockA{FooBar Institute\\
#+latex_header: Email: john.smith@foo.bar}
Org Mode defines a considerable number of Export settings. These control which parts of the org document are exported and how this is done. For example, they can be used to set whether a table of contents is created and whether title and author should be inserted into the output document.
Pandoc should understand and follow these directives. HOWEVER pandoc only operates on the file it is given and does not know about settings from Emacs such as customisations. If, for example, you wish not to have a Table of Contents, there must be a line #+OPTIONS: toc:nil in the file itself; any global setting of org-export-with-toc will not be respected.
Note that Org Mode will by default try to deduce the author’s full name (using user-full-name) when exporting, even if it is not given in the org document. To suppress this, add #+OPTIONS: author: nil in the document’s header.
You can specify the default options passed to pandoc and used on its command-line for each document format.
org-pandoc-options- General Pandoc options.
org-pandoc-options-for-FORMAT- Format-specific options.
org-pandoc-epub-rights- EPUB Copyright Statement.
Options should be specified by an alist. List of valid options are
defined in org-pandoc-valid-options. Only long-name options can be
used. For example, metadata must be given as the option name, even
though Pandoc accepts a short-form version of the argument (“-M”).
Multiple values can be specified to options defined in
org-pandoc-colon-separated-options. They should be defined in
colon-separated list.
Values of options defined in org-pandoc-file-options will be
expanded to full path if they begin with ~ (tilde) character.
You can also specify output format extension with
org-pandoc-format-extensions variable.
For example:
;; default options for all output formats
(setq org-pandoc-options '((standalone . t)))
;; cancel above settings only for 'docx' format
(setq org-pandoc-options-for-docx '((standalone . nil)))
;; special settings for beamer-pdf and latex-pdf exporters
(setq org-pandoc-options-for-beamer-pdf '((pdf-engine . "xelatex")))
(setq org-pandoc-options-for-latex-pdf '((pdf-engine . "pdflatex")))
;; special extensions for markdown_github output
(setq org-pandoc-format-extensions '(markdown_github+pipe_tables+raw_html))Hooks are also provided to be called when pandoc has completed processing.
org-pandoc-after-processing-FORMAT-hook- Hook called after processing
FORMAT.
These hooks are only available for text-file FORMAT.
after-processing options can not be specified to epub, docx or
pdf formats.
For preprocessing hooks, use org-export-before-processing-hook.
If you want delayed loading of `ox-pandoc’ when
org-pandoc-menu-entry is customized, please consider the following
settings in your init file.
(with-eval-after-load 'ox
(require 'ox-pandoc))ox-pandoc works by first using Org-mode’s own conversion functions to
export a temporary version of the org file in org format and then
calling pandoc with the appropriate switches on this file. This
process creates temporary files in the working directory called
“XXXX.tmpZZZZ.org” and “XXXX.tmpZZZZ.css” (if necessary). (ZZZZ is a
random string)
Under normal operation the temporary files are deleted automatically
when `pandoc` has finished processing them. If you use recentf, you
may find these files clutter your recent files list. M-x
recentf-cleanup should remove them.
ox-pandoc supports the export of code blocks, including code blocks
for specific output formats (e.g. LaTeX, HTML). Code wrapped in
#+BEGIN_EXPORT [format] will be passed to pandoc as-is. Pandoc knows how
to handle these blocks correctly and will include them in the final
output if they match the target format. The same applies for short
format-specific snippets using Org’s @@format: syntax.
Blocks and snippets intended only for the pandoc backend can be
specified using #+BEGIN_EXPORT pandoc and @@pandoc:. The inner
content of these blocks and snippets will be passed to pandoc. This may
be useful for adding extra information for output formats only supported
by pandoc, not by Org’s own native converters.
ox-pandoc also supports the evaluation of embedded code blocks wrapped
with BEGIN_SRC [language]. The various options described by the
Org-mode
manual for working with source code should be supported: source code,
results, both or neither can included in the final document and outputs
can be specified for particular output formats (e.g. HTML).
IMPORTANT: if you wish to include evaluated SRC blocks and their
results in documents to be processed by pandoc, each block should be
given a unique name. For example.
#+NAME: my--block (+ 4 7)
Citations can be inserted into Org documents and then, when the document is exported and linked to a bibliography file, the citations are formatted correctly (e.g. in footnotes, numbered or author-year style) and a formatted bibliography added to the output document. Pandoc has long had a number of options for processing citations in org documents. With version 9.5 (September 2021) Org Mode added official syntax and support for citations.
ox-pandoc aims fully to support citation handling and export in Org Mode 9.5+ and pandoc. This is complicated by the many potential formats and by there being overlapping but not 100% compatible tools involved. Citation support should be seen as experimental and I encourage you to report unexpected results, please including sample documents.
In all cases, you can indicate what bibliography file is the source for citations in a document with a header #+BIBLIOGRAPHY: my-references.bib. Bibliographies can potentially be in .bib, .yaml or .json format. A #+CITE_EXPORT: header indicates how citations in the document are processed before being handed to pandoc. Which exporter to choose depends on what final document format is targetted:
If the document is going to be transformed to TeX and then compiled by a LaTeX processor to make (for example) a PDF, you should probably choose either the biblatex or natbib processor. Additional arguments to the header can specify the citation and bibliography format wanted from biblatex or natbib - see the Org Manual.
In this case, cite: commands are replaced with the appropriate LaTeX commands. Pandoc should ignore these and pass them through to the LaTeX compiler.
For other formats, the best approach at the moment is to use the csl Org-Mode cite processor; this requires that the citeproc-el Emacs package be installed. A .csl (Citation Style Language) file can be specified to determine how citations and bibligraphy are to be formatted.
In this case, citations and bibliography are resolved and formatted before they are passed to Pandoc, which should simply pass on the formatting to the final output document.
An alternative to the above (also relevant for Org 9.4 and earlier) is to ensure that citations in text are transformed to one of the formats that Pandoc recognises in org documents. You should then set #+PANDOC_OPTIONS: citeproc:t in the document header.
In this case, citations are instead processed by pandoc using CSL. This may be a good solution if you are using one of the alternative citation systems for Org, such as org-ref. A goal in ox-pandoc is to offer an alternative citation export processor that outputs Pandoc-specific citation syntax, but this is still in planning.
You can convert an Org-mode file to various formats with simple commands. The following table shows the supported formats:
| format | extension | buffer | file |
|---|---|---|---|
| asciidoc | txt | yes | yes |
| beamer | tex | yes | yes |
| beamer-pdf | no | yes | |
| commonmark | md | yes | yes |
| context | tex | yes | yes |
| docbook | xml | yes | yes |
| docx | no | yes | |
| dzslides | html | yes | yes |
| epub2 | epub | no | yes |
| epub3 | epub | no | yes |
| fb2 | fb2 | yes | yes |
| gfm | md | yes | yes |
| html4 | html | yes | yes |
| html5 | html | yes | yes |
| icml | yes | yes | |
| jira | md | yes | yes |
| json | yes | yes | |
| latex | tex | yes | yes |
| latex-pdf | no | yes | |
| man | yes | yes | |
| markdown | md | yes | yes |
| markdown_github | md | yes | yes |
| markdown_mmd | md | yes | yes |
| markdown_phpextra | md | yes | yes |
| markdown_strict | md | yes | yes |
| mediawiki | yes | yes | |
| native | hs | yes | yes |
| odt | no | yes | |
| opendocument | xml | yes | yes |
| opml | yes | yes | |
| org | yes | yes | |
| plain | txt | yes | yes |
| pptx | no | yes | |
| revealjs | html | yes | yes |
| rst | yes | yes | |
| rtf | yes | yes | |
| s5 | html | yes | yes |
| slideous | html | yes | yes |
| slidy | html | yes | yes |
| texinfo | texi | yes | yes |
| textile | yes | yes | |
| typst | typst | yes | yes |
| typst-pdf | no | yes |
Pandoc provides features for the automated numbering and referencing of
figures, tables, equations and listings through the use of add-on
filters such as pandoc-xnos and pandoc-crossref. These filters can be
installed and then enabled with ox-pandoc in the usual way, such as
through a document header like:
#+pandoc_options: filter:pandoc-fignos
These pandoc filters rely on labelling of individual figures in your org
document with a #+label: attribute. This attribute is deprecated in
current Org Mode, but can still be used with ox-pandoc to tag figures
etc. that should be automatically numbered and included in lists:
#+caption: A caption for the image
#+name: fig:myimage_name
#+label: fig:myimage_label
[[file:myimage.png]]
The following options were supported in previous version of ox-pandoc.
They are no longer supported.
EPUB_METADATA:- obsolete. Use
epub-metadatainPANDOC_OPTIONS:instead. EPUB_STYLESHEET:- obsolete. Use
epub-stylesheetinPANDOC_OPTIONS:instead.
ox-pandoc was originally developed for pandoc version 1. Subsequent
versions of pandoc (2.0 in 2017, 3.0 in 2023) and Org mode have improved
support for automatic numbering of figures, tables and equations.
The non-customisable and non-optional numbering of figures, tables and
the like has been removed from ox-pandoc. This is to avoid conflicts
with automatic labelling and numbering of these document elements in
pandoc and optional filters.
This is an incompatible change that alters output from existing
documents. If you require the old behaviour you may pin your ox-pandoc
version to one that included numbering of figures. The last tagged
version of ox-pandoc with numbering is v2.0, from January 2023. No
fixes or features will be ported to this version.
This package was inspired by org-pandoc, but was entirely re-written by kawabata who is the original author of ox-pandoc. The code was released as a emacs package via MELPA.
In 2021, the package was updated to address small feature requests, apply patches and fix a number of bugs, most of which had arisen through changes in pandoc itself. The package is currently maintained by a-fent.
GPLv2.