Defaults files

The --defaults option may be used to specify a package of options, in the form of a YAML file.

Fields that are omitted will just have their regular default values. So a defaults file can be as simple as one line:

verbosity: INFO

In fields that expect a file path (or list of file paths), the following syntax may be used to interpolate environment variables:

csl:  ${HOME}/mycsldir/special.csl

${USERDATA} may also be used; this will always resolve to the user data directory that is current when the defaults file is parsed, regardless of the setting of the environment variable USERDATA.

${.} will resolve to the directory containing the defaults file itself. This allows you to refer to resources contained in that directory:

epub-cover-image: ${.}/cover.jpg
epub-metadata: ${.}/meta.xml
resource-path:
- .             # the working directory from which pandoc is run
- ${.}/images   # the images subdirectory of the directory
                # containing this defaults file

This environment variable interpolation syntax only works in fields that expect file paths.

Defaults files can be placed in the defaults subdirectory of the user data directory and used from any directory. For example, one could create a file specifying defaults for writing letters, save it as letter.yaml in the defaults subdirectory of the user data directory, and then invoke these defaults from any directory using pandoc --defaults letter or pandoc -dletter.

When multiple defaults are used, their contents will be combined.

Note that, where command-line arguments may be repeated (--metadata-file, --css, --include-in-header, --include-before-body, --include-after-body, --variable, --metadata, --syntax-definition), the values specified on the command line will combine with values specified in the defaults file, rather than replacing them.

The following tables show the mapping between the command line and defaults file entries.

command line	defaults file
foo.md	input-file: foo.md
foo.md bar.md	input-files: - foo.md - bar.md

The value of input-files may be left empty to indicate input from stdin, and it can be an empty sequence [] for no input.

General options

command line	defaults file
--from markdown+emoji	from: markdown+emoji reader: markdown+emoji
--to markdown+hard_line_breaks	to: markdown+hard_line_breaks writer: markdown+hard_line_breaks
--output foo.pdf	output-file: foo.pdf
--output -	output-file:
--data-dir dir	data-dir: dir
--defaults file	defaults: - file
--verbose	verbosity: INFO
--quiet	verbosity: ERROR
--fail-if-warnings	fail-if-warnings: true
--sandbox	sandbox: true
--log=FILE	log-file: FILE

Options specified in a defaults file itself always have priority over those in another file included with a defaults: entry.

verbosity can have the values ERROR, WARNING, or INFO.

Reader options

command line	defaults file
--shift-heading-level-by -1	shift-heading-level-by: -1
--indented-code-classes python	indented-code-classes: - python
--default-image-extension ".jpg"	default-image-extension: '.jpg'
--file-scope	file-scope: true
--citeproc \ --lua-filter count-words.lua \ --filter special.lua	filters: - citeproc - count-words.lua - type: json path: special.lua
--metadata key=value \ --metadata key2	metadata: key: value key2: true
--metadata-file meta.yaml	metadata-files: - meta.yaml metadata-file: meta.yaml
--preserve-tabs	preserve-tabs: true
--tab-stop 8	tab-stop: 8
--track-changes accept	track-changes: accept
--extract-media dir	extract-media: dir
--abbreviations abbrevs.txt	abbreviations: abbrevs.txt
--trace	trace: true

Metadata values specified in a defaults file are parsed as literal string text, not Markdown.

Filters will be assumed to be Lua filters if they have the .lua extension, and JSON filters otherwise. But the filter type can also be specified explicitly, as shown. Filters are run in the order specified. To include the built-in citeproc filter, use either citeproc or {type: citeproc}.

General writer options

command line	defaults file
--standalone	standalone: true
--template letter	template: letter
--variable key=val \ --variable key2	variables: key: val key2: true
--eol nl	eol: nl
--dpi 300	dpi: 300
--wrap 60	wrap: 60
--columns 72	columns: 72
--table-of-contents	table-of-contents: true
--toc	toc: true
--toc-depth 3	toc-depth: 3
--strip-comments	strip-comments: true
--no-highlight	highlight-style: null
--highlight-style kate	highlight-style: kate
--syntax-definition mylang.xml	syntax-definitions: - mylang.xml syntax-definition: mylang.xml
--include-in-header inc.tex	include-in-header: - inc.tex
--include-before-body inc.tex	include-before-body: - inc.tex
--include-after-body inc.tex	include-after-body: - inc.tex
--resource-path .:foo	resource-path: ['.','foo']
--request-header foo:bar	request-headers: - ["User-Agent", "Mozilla/5.0"]
--no-check-certificate	no-check-certificate: true

Options affecting specific writers

command line	defaults file
--self-contained	self-contained: true
--link-images	link-images: true
--html-q-tags	html-q-tags: true
--ascii	ascii: true
--reference-links	reference-links: true
--reference-location block	reference-location: block
--figure-caption-position=above	figure-caption-position: above
--table-caption-position=below	table-caption-position: below
--markdown-headings atx	markdown-headings: atx
--list-tables	list-tables: true
--top-level-division chapter	top-level-division: chapter
--number-sections	number-sections: true
--number-offset=1,4	number-offset: \[1,4\]
--listings	listings: true
--list-of-figures	list-of-figures: true
--lof	lof: true
--list-of-tables	list-of-tables: true
--lot	lot: true
--incremental	incremental: true
--slide-level 2	slide-level: 2
--section-divs	section-divs: true
--email-obfuscation references	email-obfuscation: references
--id-prefix ch1	identifier-prefix: ch1
--title-prefix MySite	title-prefix: MySite
--css styles/screen.css \ --css styles/special.css	css: - styles/screen.css - styles/special.css
--reference-doc my.docx	reference-doc: my.docx
--epub-cover-image cover.jpg	epub-cover-image: cover.jpg
--epub-title-page=false	epub-title-page: false
--epub-metadata meta.xml	epub-metadata: meta.xml
--epub-embed-font special.otf \ --epub-embed-font headline.otf	epub-fonts: - special.otf - headline.otf
--split-level 2	split-level: 2
--chunk-template="%i.html"	chunk-template: "%i.html"
--epub-subdirectory=""	epub-subdirectory: ''
--ipynb-output best	ipynb-output: best
--pdf-engine xelatex	pdf-engine: xelatex
--pdf-engine-opt=--shell-escape	pdf-engine-opts: - '-shell-escape' pdf-engine-opt: '-shell-escape'

Citation rendering

command line	defaults file
--citeproc	citeproc: true
--bibliography logic.bib	bibliography: logic.bib
--csl ieee.csl	csl: ieee.csl
--citation-abbreviations ab.json	citation-abbreviations: ab.json
--natbib	cite-method: natbib
--biblatex	cite-method: biblatex

cite-method can be citeproc, natbib, or biblatex. This only affects LaTeX output. If you want to use citeproc to format citations, you should also set ‘citeproc: true’.

If you need control over when the citeproc processing is done relative to other filters, you should instead use citeproc in the list of filters (see Reader options).

Math rendering in HTML

command line	defaults file
--mathjax	html-math-method: method: mathjax
--mathml	html-math-method: method: mathml
--webtex	html-math-method: method: webtex
--katex	html-math-method: method: katex
--gladtex	html-math-method: method: gladtex

In addition to the values listed above, method can have the value plain.

If the command line option accepts a URL argument, an url: field can be added to html-math-method:.

Options for wrapper scripts

command line	defaults file
--dump-args	dump-args: true
--ignore-args	ignore-args: true