ox-pandoc

This is another exporter that translates Org-mode file to various other formats via Pandoc.

Description

You can convert Org-mode file to various formats with simple commands. Following table shows the supported fromats.

Requirements

You need Emacs 24.2, org-mode 8.2, and Pandoc 2.0 (or later versions). Pandoc-Citeproc 0.3 (or later) may also be needed if you use bibliography features.

Note that Org-mode equipped with Emacs 24.3 is version 7.9 and can not be used with this tool. It is recommended to install Pandoc via Cabal, or the installer directly downloaded from official web sites, as other package managers (such as Anaconda) sometimes install old versions of Pandoc.

Installation

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 ⏎

Usage

Running the Commands

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.

Similar commands are prepared for various formats.

Customizing User Option Variables

You can specify the default options for each document format and hooks.

org-pandoc-options

General Pandoc options.

org-pandoc-options-for-FORMAT

Format-specific options.

org-pandoc-after-processing-FORMAT-hook

Hook after processing FORMAT. This hook is only available to text-file FORMAT.

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. after-processing options can not be specified to epub, docx or pdf formats. For preprocessing hooks, use org-export-before-processing-hook.

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))

Document-Specific Options

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, quote entire option-value pair.

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:

# If you don't want author to be appeared, just leave it empty.
#+AUTHOR:
#+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: [email protected]}

Customizing Shortcuts

As pandoc supports many number of formats, initial org-export-dispatch shortcut menu does not show full of its supported formats. You can customize org-pandoc-menu-entry variable (and probably restart Emacs) to change its default menu entries.

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))

VS.

org-pandoc

This file is inspired by org-pandoc, but entirely re-written. This tool prepares various export commands for all formats supported by pandoc.

Note

Temporary Files

This file creates and removes “XXXX.tmpZZZZ.org” and “XXXX.tmpZZZZ.css” (if necessary) temprary files in working directory. (ZZZZ is random string.)

Obsolete In-File Options

Following options are supported in previous version of ox-pandoc. They are no longer supported.

EPUB_METADATA:

obsolete. Use epub-metadata in PANDOC_OPTIONS: instead.

EPUB_STYLESHEET:

obsolete. Use epub-stylesheet in PANDOC_OPTIONS: instead.

Citation

Currently, Pandoc citation key is expressed as @key, rather than {\cite key} . You may need some text converter if you want to use Pandoc citation styles in org document.

License

GPLv2.

Author

• kawabata