Skip to content

System Setup

Operating System

I use Arch Linux for this tutorial. While I haven’t tested these instructions on other operating systems, they should work with the right setup. Using docker can help ensure consistent results across different systems.

On Windows, you might consider installing the Windows Subsystem for Linux (WSL) and running the necessary tools there.

Here are some specifics of my system:

$ uname -srvmo
Linux 6.7.3-arch1-2 #1 SMP PREEMPT_DYNAMIC Fri, 02 Feb 2024 17:03:55 +0000 x86_64 GNU/Linux

Command Line

We’ll use the command line to generate PDF files. No need to navigate through graphical interfaces — don’t worry, it’s straightforward once you get the hang of it.

Editor

To write plain text files, you’ll need a text editor. I use Neovim, but any editor you're comfortable with will work.

Pandoc and LaTeX

To convert plain text files into PDFs, you'll need both Pandoc and a LaTeX distribution. Pandoc is the primary tool we'll use, and it relies on LaTeX for rendering.

I recommend using a Docker container with all the necessary software pre-installed. This approach simplifies setup and ensures consistency. You’ll need to install Docker if it’s not already on your machine. You can find installation instructions in the guide Install Docker Engine.

Since the official Pandoc LaTeX images may not include all the tools required for the advanced features in this tutorial, I’ve created a custom Docker image based on the official one.

Alias to run the docker image

To make using the Docker image more convenient, add the following alias to your bashrc file:

alias pandock='docker run --rm -it --user $(id -u):$(id -g) -v .:/data schuam/dac:v1.0.0'

Since the docker image uses the pandoc command as its entrypoint, you can just add all command line parameters that you would normally add to the pandoc command to the pandock alias.

For non-Linux systems or users who use a different shell (not bash), setting up an alias might be different. If you haven’t set up an alias, remember to use the full docker run command instead of pandock.

Software Versions

If you're using the custom Docker image, you should have the same software versions as I do. To verify, start the container with a different entry point:

$ docker run --rm -it --entrypoint /bin/sh schuam/dac:v1.0.0
/data #

Inside the container, check the versions of pandoc and pdflatex with these commands:

/data # pandoc --version
pandoc 3.1.1
Features: +server +lua
Scripting engine: Lua 5.4
User data directory: /root/.local/share/pandoc
Copyright (C) 2006-2023 John MacFarlane. Web:  https://pandoc.org
This is free software; see the source for copying conditions. There is no
warranty, not even for merchantability or fitness for a particular purpose.

/data # pdflatex --version
pdfTeX 3.141592653-2.6-1.40.24 (TeX Live 2022)
kpathsea version 6.3.4
Copyright 2022 Han The Thanh (pdfTeX) et al.
There is NO warranty.  Redistribution of this software is
covered by the terms of both the pdfTeX copyright and
the Lesser GNU General Public License.
For more information about these matters, see the file
named COPYING and the pdfTeX source.
Primary author of pdfTeX: Han The Thanh (pdfTeX) et al.
Compiled with libpng 1.6.37; using libpng 1.6.37
Compiled with zlib 1.2.11; using zlib 1.2.11
Compiled with xpdf version 4.03

/data # pandoc-crossref --version
pandoc-crossref v0.3.15.1 git commit 6bc8fa67a4e1ada4787fa0ccd720a19e8e3c818e (HEAD) built with Pandoc v3.1.1, pandoc-types v1.23 and GHC 9.0.1

Setup Without Docker

If you prefer not to use Docker, you can install Pandoc and LaTeX manually. Follow the instructions on the Installing Pandoc page for your operating system.

After installing Pandoc and LaTeX, you'll need two additional components:

  1. The pandoc-crossref filter. It's important to install a version that fits your installed Pandoc version. The installation guide explains that. For Pandoc's version 3.1.1, I installed version v0.3.15.2 of the pandoc-crossref filter
  2. The LaTeX package lastpage.

On Linux, you can install these with the following commands:

wget -O- \
    "https://github.com/lierdakil/pandoc-crossref/releases/download/v0.3.15.2/pandoc-crossref-Linux.tar.xz" \
    | tar xJ -C /usr/bin/ pandoc-crossref
tlmgr install lastpage

Now that you have everything set up, let’s move on to generating a well-formatted document.