Another org-mode exporter via pandoc.
Emacs Lisp
Switch branches/tags
Nothing to show
Clone or download
Latest commit aa37dc7 May 10, 2018
Permalink
Failed to load latest commit information.
README.org update for Pandoc 2.2 May 10, 2018
ox-pandoc.el update for Pandoc 2.2 May 10, 2018

README.org

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.

formatextensionbufferfile
asciidoctxtyesyes
beamertexyesyes
beamer-pdfpdfnoyes
commonmarkmdyesyes
contexttexyesyes
docbookxmlyesyes
docxnoyes
dzslideshtmlyesyes
epub2epubnoyes
epub3epubnoyes
fb2fb2yesyes
gfmmdyesyes
html4htmlyesyes
html5htmlyesyes
icmlyesyes
jsonyesyes
latextexyesyes
latex-pdfpdfnoyes
manyesyes
markdownmdyesyes
markdown_githubmdyesyes
markdown_mmdmdyesyes
markdown_phpextramdyesyes
markdown_strictmdyesyes
mediawikiyesyes
nativehsyesyes
odtnoyes
opendocumentxmlyesyes
opmlyesyes
orgyesyes
plaintxtyesyes
pptxnoyes
revealjshtmlyesyes
rstyesyes
rtfyesyes
s5htmlyesyes
slideoushtmlyesyes
slidyhtmlyesyes
texinfotexiyesyes
textileyesyes

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: john.smith@foo.bar}

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