#+TITLE: ox-pandoc: an exporter for Org Mode using pandoc

=ox-pandoc= is an [[https://orgmode.org/manual/Exporting.html#Exporting][exporter]] for [[https://orgmode.org/][Org mode]] which converts Org-mode files to a wide variety of other formats using the [[https://pandoc.org/][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.

Github's Org support doesn't seem to be able to do ToCs

So use https://github.com/snosov1/toc-org

• Contents :TOC:QUOTE: #+BEGIN_QUOTE

• [[#installation][Installation]]
  • [[#requirements][Requirements]]
  • [[#installing-pandoc][Installing Pandoc]]
  • [[#installation-1][Installation]]
• [[#usage][Usage]]
  • [[#using-orgs-export-dispatch-menu][Using Org's export-dispatch menu]]
  • [[#running-the-commands-directly][Running the Commands directly]]
• [[#document-options][Document options]]
  • [[#passing-options-to-pandoc][Passing options to pandoc]]
  • [[#org-mode-export-settings][Org-Mode export settings]]
• [[#customisation][Customisation]]
  • [[#setting-default-pandoc-options][Setting default pandoc options]]
  • [[#hooks][Hooks]]
  • [[#delayed-loading-of-ox-pandoc][Delayed loading of ox-pandoc]]
  • [[#temporary-files][Temporary Files]]
• [[#feature-support][Feature Support]]
  • [[#source-code-blocks][Source Code Blocks]]
  • [[#citations-and-bibliographies-experimental][Citations and Bibliographies (Experimental)]]
  • [[#supported-formats][Supported Formats]]
  • [[#labelling-and-numbering-of-figures-tables-etc][Labelling and numbering of figures, tables etc.]]
• [[#deprecated-and-removed-features][Deprecated and Removed Features]]
  • [[#obsolete-in-file-options][Obsolete In-File Options]]
  • [[#numbering-of-figures-tables-and-equations][Numbering of figures, tables and equations]]
• [[#history-and-people][History and People]]
• [[#license][License]] #+END_QUOTE

• Installation ** Requirements 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 and Bibliographies (Experimental)][citations]] in newest versions of org-mode (9.5+) require a similarly recent version of Pandoc (2.17+).

** Installing Pandoc Installing Pandoc directly from [[https://pandoc.org/installing.html][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=.

** Installation You can install this tool with [[https://www.melpa.org][MELPA]]. For example,

#+BEGIN_SRC emacs-lisp (setq package-archives '(("gnu" . "http://elpa.gnu.org/packages/") ("melpa" . "http://melpa.milkbox.net/packages/"))) #+END_SRC

: M-x package-install ⏎ : ox-pandoc ⏎

• Usage ** Using Org's export-dispatch menu 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 [[*Supported Formats][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=.

** Running the Commands directly

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.

• Document options ** Passing options to pandoc The =pandoc= command supports a [[https://pandoc.org/MANUAL.html#options][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 [[#setting-default-pandoc-options][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: [email protected]}

** Org-Mode export settings Org Mode defines a considerable number of [[https://orgmode.org/manual/Export-Settings.html][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.

• Customisation ** Setting default pandoc options

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:

#+BEGIN_SRC emacs-lisp ;; 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)) #+END_SRC

** Hooks 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=.

** Delayed loading of ox-pandoc If you want delayed loading of `ox-pandoc' when =org-pandoc-menu-entry= is customized, please consider the following settings in your init file.

#+BEGIN_SRC emacs-lisp (with-eval-after-load 'ox (require 'ox-pandoc)) #+END_SRC

** Temporary Files =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.

• Feature Support ** Source Code Blocks =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 [[https://orgmode.org/manual/Working-with-Source-Code.html#Working-with-Source-Code][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.

#+BEGIN_EXAMPLE #+NAME: my--block #+BEGIN_SRC emacs-lisp :exports both :results value (+ 4 7) #+END_SRC #+END_EXAMPLE

** Citations and Bibliographies (Experimental) 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 [[https://pandoc.org/org.html#citations][number of options for processing citations]] in org documents. With version 9.5 (September 2021) Org Mode added [[https://orgmode.org/manual/Citation-handling.html][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 [[https://orgmode.org/manual/Citation-export-processors.html][exporter]] to choose depends on what final document format is targetted:

*** Exporting citations to LaTeX / PDF 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 [[https://orgmode.org/manual/Citation-export-processors.html][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.

*** Exporting citations to HTML, ODT, DocX etc 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.

*** Alternative: using Pandoc citation syntax An alternative to the above (also relevant for Org 9.4 and earlier) is to ensure that citations in text are transformed to [[https://pandoc.org/org.html#citations][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.

** Supported Formats

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 | 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 | 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 | pdf | no | yes |

** Labelling and numbering of figures, tables etc. Pandoc provides features for the automated numbering and referencing of figures, tables, equations and listings through the use of add-on filters such as [[https://github.com/tomduck/pandoc-xnos][pandoc-xnos]] and [[https://github.com/lierdakil/pandoc-crossref][pandoc-crossref]]. These filters can be installed and then enabled with =ox-pandoc= in the usual way, such as through a document header like: #+begin_src org #+pandoc_options: filter:pandoc-fignos #+end_src 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: #+begin_src org #+caption: A caption for the image #+name: fig:myimage_name #+label: fig:myimage_label [[file:myimage.png]] #+end_src

• Deprecated and Removed Features ** Obsolete In-File Options The following options were 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.

** Numbering of figures, tables and equations =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.

• History and People This package was inspired by [[https://github.com/robtillotson/org-pandoc][org-pandoc]], but was entirely re-written by [[http://github.com/kawabata][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 [[http://github.com/a-fent][a-fent]].

• License

  GPLv2.