pandoc/extra repository overview

⁠Pandoc extra images

These images contain pandoc⁠, the universal document converter and a curated selection of components:

• Templates: Eisvogel⁠
• Beamer Themes: Eisvogel⁠, beamer-metropolis⁠
• Pandoc filters: pandoc-latex-environment⁠ + Lua filters⁠, pandoc-include⁠
• Open Source Fonts: Font Awesome, Source Code Pro, Source Sans Pro
• PDF engines: Tectonic⁠

⁠Quick Reference

• Where to get help: pandoc-discuss mailing list⁠

• Where to report issues: https://github.com/pandoc/dockerfiles/issues⁠

• Source repository: pandoc/dockerfiles⁠ on Github

• Maintained by: Albert Krewinkel⁠, Caleb Maclennan⁠, and Damien Clochard⁠.

⁠Supported tags

• edge
• 3.10.0.0, 3.10.0, 3.10, 3, latest
• 3.9.0.2, 3.9.0, 3.9
• 3.9.0.0
• 3.8.3, 3.8
• 3.7.0.2, 3.7.0, 3.7

The tags listed in a bullet point all refer to the same image. Numerical tags are rolling, meaning that a version tag always points to the newest image with the given version prefix. A prefix-version like a.b. is an easy way to specify a range of acceptable versions. Use a full, four part version like a.b.c.d to fix the image to a specific version.

The latest tag refers to the most recently released version; there may be a minor lag between the time a pandoc version is released and a new image is released.

A recent development version is provided under the edge tag.

All tags can be suffixed with a stack identifier.

⁠A note on pandoc versioning

Pandoc is not only an executable but also a Haskell library, which is why it is versioned using the Haskell Package Versioning Policy⁠. Even minor versions can sometimes introduce new behavior if the API does not change, but this is a rare occasion.

⁠Supported stacks

All tags can be suffixed with a stack-identifier, e.g., latest-ubuntu. This allows to chose a specific operation system. Available stacks are

• alpine: Alpine⁠ Linux.
• debian: Debian⁠ Linux.
• ubuntu: Ubuntu⁠ Linux.

The default for pandoc/extra is alpine.

⁠Run the pandoc Docker container

A common use of the image looks like this (linebreaks for readability):

docker run --rm \
       --volume "$(pwd):/data" \
       --user $(id -u):$(id -g) \
       pandoc/extra README.md -o outfile.epub

This will convert the file README.md in the current working directory into outfile.epub. Note that Docker options go before the image name, here pandoc/extra, while pandoc options come after it.

The --volume flag maps some local directory (lefthand side of the colons) to a directory in the container (righthand side), so that you have your source files available for pandoc to convert. $(pwd) is quoted to protect against spaces in filenames.

Ownership of the output file is determined by the user executing pandoc in the container. This will generally be a user different from the local user. It is hence a good idea to specify for docker the user and group IDs to use via the --user flag.

For frequent command line use, we suggest the following shell alias:

alias pandock=\
'docker run --rm -v "$(pwd):/data" -u $(id -u):$(id -g) pandoc/extra'

⁠Other images

The following pandoc images are available:

• pandoc/minimal⁠: small images with the pandoc executable.
• pandoc/core⁠: based on minimal images and includes additional programs that are commonly used during conversions.
• pandoc/latex⁠: suitable for conversions to PDF via LaTeX⁠.
• pandoc/extra⁠: large images based on the pandoc/latex, with more helpers, the Tectonic engine, and the Eisvogel template⁠
• pandoc/typst⁠: includes the Typst⁠ typesetting system.