5 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.

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.