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:
