Transforming markdown documentation to PDF

I like to write all kind of documentation in Markdown. This is however not the preferred way how some clients want to have their documentation written in: they prefer a single, big document.

For a current project, we use a nice project called Eisvogel which is a pandoc LaTeX template. Pandoc will merge all markdown files together and generate a PDF based on the eisvogel template. A simple make target generates everything:

docs:
	pandoc -s \
	$(DOCS_DIR)/introduction.md \
	$(DOCS_DIR)/system-design.md \
	$(DOCS_DIR)/installation-and-configuration.md \
	-o $(DOCS_DIR)/docs.md

	docker run --rm \
		--platform linux/amd64 \
		-v $(DOCS_DIR)/:/data \
		-w /data \
		rstropek/pandoc-latex \
		-f markdown \
		--template /data/eisvogel.tex \
		-t latex \
		-o documentation.pdf \
		--metadata-file=docs.yaml \
		docs.md

A configuration yaml file can be used to configure some behaviour:

title: Project X, Technical Documentation
date: \today
subtitle: |
  The following document provides the documentation of Project X.  
author:
  - John
keywords: [foo, bar]
papersize: a4
links-as-notes: true
toc: true
toc-depth: 2
toc-own-page: true
lang: en
titlepage: true
numbersections: true
footnotes-pretty: true

The resulting PDF file looks really good and also has syntax highlighting: