git.iko.soy/typeable/pandoc
on 2.14 help sign in
typeable/pandoc/doc/org.md
379 lines 13 kB history raw
1---
2title: Org-mode features and differences
3author: Albert Krewinkel
4---
6Pandoc's handling of org files is similar to that of Emacs
7org-mode. This document aims to highlight the cases where this is
8not possible or just not the case yet.
10Export options
11==============
13The following export keywords are supported:
15- AUTHOR: comma-separated list of author(s); fully supported.
17- CREATOR: output generator; passed as plain-text metadata entry
18 `creator`, but not used by any default templates.
20- DATE: creation or publication date; well supported by pandoc.
22- EMAIL: author email address; passed as plain-text metadata
23 field `email`, but not used by any default templates.
25- LANGUAGE: document language; included as plain-text metadata
26 field `lang`. The value should be a [BCP47 language tag].
28- SELECT_TAGS: tags which select a tree for export.
30- EXCLUDE\_TAGS: tags which prevent a subtree from being
31 exported. Fully supported.
33- TITLE: document title; fully supported.
35- EXPORT\_FILE\_NAME: target filename; *unsupported*, the output
36 defaults to stdout unless a target has to be given as a command
37 line option.
39::: {.alert .alert-info}
40Pandoc tries to be compatible with org-mode when exporting an org document. If
41you find some behavior confusing, please do refer to org-mode
42[Export-Settings](https://orgmode.org/manual/Export-Settings.html)
43documentation. For example, a common confusion
44([#3214](https://github.com/jgm/pandoc/issues/3214 "Problem with headers lower
45then 3 in org-mode reader"), [#5169](https://github.com/jgm/pandoc/issues/5169
46"org mode headings past level three converted to numbered outline list"),
47[#6145](https://github.com/jgm/pandoc/issues/6145 "Headers 4 levels deep render
48differently"), [#7236](https://github.com/jgm/pandoc/issues/7236 "In Org mode,
49Header with level > 3 are not recognized as headers")) is treatment of headers
50with level > 3 differently because org-mode sets `org-export-headline-levels`
51(configurable with `#+OPTIONS: H:3`) to 3 by default.
52:::
54[BCP47 language tag]: https://tools.ietf.org/html/bcp47
56Format-specific options
57-----------------------
59Emacs Org-mode supports additional export options which work for
60specific export formats. Some of these options' behavior differs
61in Org-mode depending on the output format, while pandoc is
62format-agnostic when parsing; differences are noted where they
63occur.
65- DESCRIPTION: the document's description; pandoc parses this
66 option as text with markup into the `description` metadata
67 field. The field is not used in default templates.
69 Pandoc follows the LaTeX exporter in that it allows markup in
70 the description. In contrast, the Org-mode HTML exporter treats
71 the description as plain text.
73- LATEX\_HEADER and LATEX_HEADER_EXTRA: arbitrary lines to add to
74 the document's preamble. Contrary to Org-mode, these lines are
75 not inserted before the hyperref settings, but close to the end
76 of the preamble.
78 The contents of this option are stored as a list of raw LaTeX
79 lines in the `header-includes` metadata field.
81- LATEX\_CLASS: the LaTeX document class; like Org-mode, pandoc
82 uses `article` as the default class.
84 The contents of this option are stored as plain text in the
85 `documentclass` metadata field.
87- LATEX\_CLASS\_OPTIONS: Options for the LaTeX document class;
88 fully supported.
90 The contents of this option are stored as plain text in the
91 `classoption` metadata field.
93- SUBTITLE: the document's subtitle; fully supported.
95 The content of this option is stored as inlines in the
96 `subtitle` metadata field.
98- HTML\_HEAD and HTML\_HEAD\_EXTRA: arbitrary lines to add to the
99 HTML document's head; fully supported.
101 The contents of these options are stored as a list of raw HTML
102 lines in the `header-includes` metadata field.
104Pandoc-specific options
105-----------------------
107Pandoc recognizes some export options not used by Emacs Org.
109- NOCITE: this field adds the listed citations to the
110 bibliography, without the need to mention them to the text. The
111 special value `@*` causes all available references to be added
112 the bibliography.
114- HEADER-INCLUDES: like HTML_HEAD and, LATEX_HEADER, but treats
115 the option's value as normal text with markup.
117- INSTITUTE: Affiliation of the author; the value is read as text
118 with markup and is stored in the `institute` metadata field. The
119 field is included by default on the title slide of beamer
120 presentations.
122Other options
123-------------
125Any export option or directive not listed above has no effect when
126parsing with pandoc. However, the information is retained as a
127*raw block*. It can be accessed through a
128[filter](https://pandoc.org/filters.html) and will be included in
129org output.
131### Directives as metadata
133As an example, we will restore an old behavior of pandoc versions
134prior to 2.10. Unknown keywords were treated as variable
135definitions, and were added the document's metadata. Typing
136`#+key: value` in the org-file used to have the same effect as
137running pandoc with the `--metadata key=value` option.
139Since pandoc 2.10, each unhandled line starting with `#+` is kept
140internally as a raw block with format `org`. This block can be
141inspected and processed by a filter. Below is a [Lua
142filter](https://pandoc.org/lua-filters.html) which converts these
143unhandled lines into metadata key-value pairs.
145``` lua
146-- intermediate store for variables and their values
147local variables = {}
149--- Function called for each raw block element.
150function RawBlock (raw)
151 -- Don't do anything unless the block contains *org* markup.
152 if raw.format ~= 'org' then return nil end
154 -- extract variable name and value
155 local name, value = raw.text:match '#%+(%w+):%s*(.+)$'
156 if name and value then
157 variables[name] = value
158 end
159end
161-- Add the extracted variables to the document's metadata.
162function Meta (meta)
163 for name, value in pairs(variables) do
164 meta[name] = value
165 end
166 return meta
167end
168```
170Citations
171=========
173Emacs org-mode lacks an official citation syntax, leading to
174multiple syntaxes coexisting. Pandoc recognizes four different
175syntaxes for citations.
177Citation support for org-mode is enabled by default. Support can
178be toggled off by disabling the `citation` extension; e.g.
179`pandoc --from=org-citations`.
181Berkeley-style citations
182------------------------
184The semi-official Org-mode citation syntax was designed by Richard
185Lawrence with additions by contributors on the [emacs-orgmode
186mailing list]. It is based on John MacFarlane's pandoc Markdown
187syntax. It's dubbed Berkeley syntax due the place of activity of
188its creators, both philosophers at UC Berkeley.
190### Simple in-text citation
192This is the simplest form of citation. It consists of the citation
193ID prefixed by '@'.
195Example:
197 @WatsonCrick1953 showed that DNA forms a double-helix.
199### In-text citation list
201Citations presented in the text unparenthesized are called
202*in-text citations*. The syntax for these citations is
204 [cite: PREFIX; INDIVIDUAL-REFERENCE; ... INDIVIDUAL-REFERENCE; SUFFIX]
206where the initial PREFIX and final SUFFIX are optional. At least
207one INDIVIDUAL-REFERENCE must be present. The colon and
208semicolons here are literal and indicate the end of the TAG and
209the end of a PREFIX or INDIVIDUAL-REFERENCE respectively.
211An INDIVIDUAL-REFERENCE has the format:
213 PREFIX KEY SUFFIX
215The KEY is obligatory, and the prefix and suffix are optional.
217A PREFIX or SUFFIX is arbitrary text (except `;`, `]`, and
218citation keys).
220Example:
222 [cite: See; @Mandelkern1981; and @Watson1953]
224### Parenthetical citation
226Citations surrounded by parentheses. The syntax is identical to
227in-text citations, except for the additional parentheses enclosing
228the initial `cite` tag.
230 [(cite): See; @Mandelkern1981; and @Watson1953]
232[emacs-orgmode mailing list]: https://lists.gnu.org/archive/html/emacs-orgmode/2015-02/msg00932.html
234org-ref citations
235-----------------
237The [org-ref] package by [John Kitchen] is in wide use to handle
238citations and has excellent tooling support in Emacs. Its
239citation syntax is geared towards users in the natural sciences
240but still very flexible regardless.
242 cite:doe_john_2000
243 citep:doe_jane_1989
244 [[citep:Dominik201408][See page 20 of::, for example]]
247Pandoc-Markdown-like syntax
248---------------------------
250Historically, Markdown-style citations syntax was the first that
251was added to pandoc's org reader. It is close to Markdown's
252citation syntax.
254Citations go inside square brackets and are separated by
255semicolons. Each citation must have a key, composed of '@' plus
256the citation identifier from the database, and may optionally
257have a prefix, a locator, and a suffix. The citation key must
258begin with a letter, digit, or `_`, and may contain
259alphanumerics, `_`, and internal punctuation characters
260(`:.#$%&-+?<>~/`). Here are some examples:
262### Simple citation
264The simplest method to insert a citation is to write the citation
265ID prefixed by '@'.
268Example:
270 [prefix @citekey suffix]
271 [see @doe2000 pp. 23-42]
272 [@doe2000 p. 5; to a lesser extend @doe2005]
275LaTeX-Syntax
276------------
278Use normal latex citation commands like `\cite{x}` or
279`\citet{y}`.
281[org-ref]: https://github.com/jkitchin/org-ref
282[John Kitchen]: https://kitchingroup.cheme.cmu.edu/
284Tables
285======
287Pandoc supports normal org tables (sometimes called "pipe tables")
288and grid tables (tables created by [table.el]).
290Column widths
291-------------
293Org mode tables don't allow line-breaks within cells, and lines
294which contain text can get very long. This often leads to tables
295which run off the page when exporting, especially when exporting
296to PDF via LaTeX. Overlong lines in the source text are this is
297usually hidden by setting a [column width], but the default Emacs
298exporters ignore that setting. Pandoc deviates from Emacs's
299behavior and uses this information to resize the table columns
300when exporting.
302Limitations
303-----------
305There is no support yet for cells spanning multiple columns or
306rows. The table.el grid tables allows rowspans and colspans and so
307does pandoc's internal structure since 2.10, but the parser has
308not been updated yet.
310[table.el]: http://table.sourceforge.net/
311[column width]: https://orgmode.org/manual/Column-Width-and-Alignment.html
313Emphasis rules
314==============
316Org-mode uses complex rules to decide whether a string
317represents emphasized text. In Emacs, this can be customized via
318the variable `org-emphasis-regexp-components`. A variable like
319this doesn't fit well with pandoc's model. Instead, it is
320possible to use special lines to change these values:
322 #+pandoc-emphasis-pre: "-\t ('\"{"
323 #+pandoc-emphasis-post: "-\t\n .,:!?;'\")}["
325The above describes the default values of these variables. The
326arguments must be valid (Haskell) strings. If interpretation of
327the argument as string fails, the default is restored.
329Changing emphasis rules only affect the part of the document
330following the special lines. They must be some of the first
331lines to alter parsing behavior for the whole document. It is
332also possible to change the values temporarily for selected
333sections only. The string `test` in the following snippet will
334be read as emphasized text, while the rest of the document will
335be parsed using default emphasis rules:
337 #+pandoc-emphasis-pre: "["
338 #+pandoc-emphasis-post: "]"
339 [/test/]
340 #+pandoc-emphasis-pre:
341 #+pandoc-emphasis-post:
343`smart` extension
344=================
346Org-mode allows to insert certain characters via special character
347sequences. For example, instead of typing the Unicode /HORIZONTAL
348ELLISPIS/ character `…` by hand, one can instead type tree dots
349`...`. En dashes and em dashes can be written as `--` and `---`
350respectively. Furthermore, quotation marks (`"`) and
351apostrophe-quotes (`'`) can be treated in a "smart" way,
352potentially replacing them with proper, language specific unicode
353quotation characters.
355Like in Markdown, these behaviors can be turned on all-at-once by
356enabling the `smart` extension. However, disabling `smart` (the
357default) will *not* necessarily disable smart quotes and special
358strings. Instead, it will just result in the default Org mode
359behavior.
361The special string feature can be turned off via the `#+OPTIONS:
362-:nil` [export setting]. There are currently no command line flags
363which control these features. As a workaround, one can use process
364substitution, a feature supported by most shells. It allows to
365provide the options line on the command line:
367 pandoc -f org <(printf "#+OPTIONS: -:nil\n") …
369[export setting]: https://orgmode.org/manual/Export-Settings.html
371Currently unsupported features
372==============================
374Library of babel
375----------------
377The library of babel translates between various programming
378languages. This is out-of-scope for pandoc. Use Emacs to run
379code, then feed the resulting org file to pandoc.