Over the past few days, I once again disappeared down the proverbial rabbit hole.
But let’s start from the beginning. On Saturday, I wrote a blog post to outline an automated and deterministic document workflow.1 To make it easier to follow, I also set up a Codeberg repository.2
The feedback was unexpectedly overwhelming and raised many valid points. The repository itself had been put together quickly rather than thoroughly, so I ended up revising it significantly and renaming it in the process. It is no longer just a demo. It now represents a complete, highly flexible, and at the same time very simple document workflow.
Basic logic of the workflow as a Mermaid diagram in the repo
What stands out in particular is the front matter and the use of extendable snippets or text blocks inside the Markdown documents, both line-based and inline through the preprocessor. On top of that, there is automatic generation of PDF forms in the postprocessor and a clean, well-structured layout.
All of this runs on a surprisingly small set of dependencies: Bash, git, pandoc, LaTeX, pdfcpu, and curl. To demonstrate dynamic snippets, I pull the latest Heise news into the Markdown during each build. In real use, this would more likely be asset or ticket lists from REST APIs. Your mileage may vary. The three other PDF documents in the repository are part of my production setup and are fairly robust.
That should be enough for now. I am back out of the rabbit hole.
Forks and pull requests are very welcome. The goal is to move away from static file collections in nested directory structures that only pretend to meet compliance requirements, and toward systems that actually support and enforce them.
With that,
Tomas Jakobs