dalibo/pandocker repository overview

⁠pandocker

A simple docker image for pandoc with filters⁠, templates⁠, fonts⁠ and additional tools⁠.

⁠Install / Upgrade

Download the image with:

docker pull dalibo/pandocker:stable

Whenever a new stable version is released, launch that command again to refresh your image.

⁠How To

Run dalibo/pandocker with regular pandoc args. Mount your files at /pandoc.

$ docker run --rm -u `id -u`:`id -g` -v `pwd`:/pandoc dalibo/pandocker README.md -o README.pdf

Notes about the docker options:

• The -v ... option will mount the current folder as the /pandoc directory inside the container. If SELinux is enabled on your system, you might need to add the --privileged tag to force access to the mouting points. For more details, read the documentation about docker runtime privileges⁠.

• The --rm option destroys the container once the document is produced. This is not mandatory but it's a good practice.

• The -u option ensures that the output files will belong to you. Again this is not necessary but it's useful.

$ alias pandoc="docker run --rm -u `id -u`:`id -g` -v `pwd`:/pandoc dalibo/pandocker:stable"
$ pandoc README.md -o README.epub

Alternatively, you can use a pipe like this:

$ cat foo.md | docker run --rm -i dalibo/pandocker -t pdf > foo.pdf

This method will not work if the source document contains images or includes...

⁠Templates

We're shipping a selection of latex templates inside the image so that you can produce nice PDF documents without installing anything.

So far, we provide the 3 templates below:

• eisvogel⁠ is designed for lecture notes and exercises with a focus on computer science. It works with pdflatex and xelatex.
• easy templates⁠ is a collection of HTML templates

You can use them simply by adding --template=xxx to your compilation lines:

$ docker run [...] --pdf-engine=xelatex --template=eisvogel foo.md -o foo.pdf

Each template has specific variables that you can use to adapt the document. Please go the project page of each template for more details.

⁠Filters

This docker image embeds a number of usefull pandoc filters. You can simply enable them by adding the option --filter xxx where xxx is the name of one of the following filters below:

• [panda] : Multi-purpose Lua filter
• pandoc-citeproc⁠ : manage bibliographies and citations
• pandoc-codeblock-include⁠ : insert an external file into a codeblock
• pandoc-cover⁠ : Add a PDF cover based on an SVG template
• pandoc-include⁠ : insert external markdown files into the main document
• pandoc-latex-admonition⁠ : adding admonitions on specific DIVs
• pandoc-latex-barcode⁠ : insert barcodes and QRcodes in documents
• pandoc-latex-color⁠ : Add colors to your PDF documents !
• pandoc-latex-environment⁠ : adding LaTeX environments on specific DIVs
• pandoc-latex-fontsize⁠ : Change size of a specific section of the document
• pandoc-latex-margin⁠ : Resize the margins of your PDF documents
• pandoc-latex-newpage⁠ : Convert horizontal rule to new page in LaTeX
• pandoc-mustache⁠ : basic variables substitution
• pandoc-crossref⁠ : support for cross-referencing sections, figures, and more
• pandoc-run-postgres⁠ : Execute SQL queries inside a markdown document
• pandoc-jinja⁠ : Render pandoc metadata inside the document itself

NOTE: By default when using the pandoc-include⁠ filter, the path to target files is relative to the /pandoc mountpoint. For instance, the !include [foo/bar.md] statement will look for a /pandoc/foo/bar.md file. You can use the docker arg --workdir="some/place/elsewhere" to specify another location. The same principle applies to the pandoc-codeblock-include⁠ and pandoc-mustache⁠ filters.

⁠Fonts

The pandocker image includes the following open-source fonts:

• Deja Vu: https://dejavu-fonts.github.io/⁠
• Lato: https://fonts.google.com/specimen/Lato⁠
• Liberation: https://github.com/liberationfonts/liberation-fonts⁠
• Fontawesome: https://fontawesome.com/⁠

The full variant includes

• Noto: https://www.google.com/get/noto/⁠

⁠Supported Tags : Branch + Variant + Parent

The image is available in multiple versions named as follows:

branch[-parent[-variant]]

• The branch can be latest (default) or stable (for production) or the release name (20.02)
• The parent is the base image we are using. Currently only ubuntu is supported
• The variant is either extra (330MB) or full (810 MB)

The supported tags are :

• latest, latest-ubuntu, latest-ubuntu-extra (default)
• latest-ubuntu-full
• stable, stable-ubuntu, stable-ubuntu-extra
• stable-ubuntu-full

Other tags are not supported and should be used with care.

⁠Build it

Use make or docker build .

⁠Additional tools

The docker image embeds additional software related to editing and publishing:

• dia⁠ a simple tool to design diagrams
• poppler-utils⁠ a collection of tools built to manage PDF and extract content
• rsync⁠ for deployment

These tools can be called by modifying the entrypoint of the image. For instance, you can convert a dia source file into an SVG image like this:

$ docker run [..] --entrypoint dia dalibo/pandocker foo.dia -e foo.svg