Wir nutzen BookStack bei NETWAYS inzwischen an zwei Stellen. Einmal als Handbook für interne Regeln, Abläufe und Grundsätze. Und einmal als Docs-System für technische und organisatorische Dokumentation – mal rein intern, mal auch für Kund:innen oder Audits.
Im Browser funktioniert das wunderbar. Man sieht die Struktur, findet Inhalte über die Suche, nutzt Tags und hangelt sich durch Shelves, Books und Pages. Sobald Dokumente aber als PDF bei Kund:innen, Audits oder in TISAX– und ISO-27001-Kontexten landen, braucht es etwas mehr Kontext. Für normale Notizen ist das egal. Für Richtlinien, Standards, Betriebsdokumentation oder Nachweise rund um TISAX und ISO 27001 eher nicht, dafür braucht man PDFs, die man auch verschicken will. Genau dafür haben wir bookstack-to-pdf gebaut.
Warum ein eigener Export?
BookStack kann PDF. Das ist gut und für viele Fälle vollkommen ausreichend. Unser Problem war ein anderes: Wir wollten PDFs, die man auch außerhalb von BookStack guten Gewissens verwenden kann.
Also mit Cover, Logo, Metadaten, Inhaltsverzeichnis, Headern, Footern und vor allem mit Tags. Gerade die Tags sind bei uns nicht nur Deko. Darüber bilden wir Status, Bereiche, Schutzklassen oder andere Eigenschaften ab. In einem Audit ist es eben ein Unterschied, ob ein Dokument einfach nur existiert oder ob auch klar ist, ob es ein Entwurf, eine gültige Richtlinie oder einem bestimmten Bereich zugeordnet ist.
Und genau da wird es spannend: BookStack unterstützt Tags natürlich sehr gut. Sie sind sichtbar, klickbar, durchsuchbar und auch über die API verfügbar. Im Standard-PDF-Export landen sie aber nicht automatisch so im Dokument, wie wir sie brauchen. Genauer gesagt: im exportierten HTML gibt es nicht zuverlässig einen verwertbaren Tag-Block, aus dem ein externer PDF-Renderer einfach Status und Werte ziehen kann.
bookstack-to-pdf löst das pragmatisch. Über ein kleines Export-Template-Override werden die BookStack-Tags einmal sauber ins HTML geschrieben. Der Renderer liest sie dort aus, stellt sie auf dem Cover als kompakte Labels dar und entfernt den Block anschließend wieder aus dem eigentlichen Inhalt. Damit stehen die Tags im PDF dort, wo sie hingehören: sichtbar, aber nicht störend.
Was macht bookstack-to-pdf?
bookstack-to-pdf ist ein kleines Kommando für den externen PDF-Export von BookStack. BookStack erzeugt HTML, übergibt es an das Kommando, und am Ende kommt ein PDF zurück.
Der Renderer kümmert sich aktuell um:
- Cover mit Logo, Titel, Metadaten und Tags
- Inhaltsverzeichnis aus den Überschriften
- Header und Footer
- Firmeninformationen aus YAML
- lokale Logos, Hintergründe und Fonts
- Übernahme von BookStack-Metadaten
- Rendering über WeasyPrint
BookStack bleibt also der Ort, an dem geschrieben wird. bookstack-to-pdf kümmert sich nur darum, dass der Export am Ende ordentlich aussieht.
Installation in Kurzform
Die Details stehen im README, aber im Kern ist es schnell erledigt:
sudo apt install libpango-1.0-0 libpangoft2-1.0-0
git clone https://github.com/NETWAYS/bookstack-to-pdf /opt/bookstack-to-pdf
cd /opt/bookstack-to-pdf
python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install .
cp config.example.yaml config.yaml
$EDITOR config.yamlDanach BookStack auf das externe Kommando zeigen lassen:
EXPORT_PDF_COMMAND="/opt/bookstack-to-pdf/.venv/bin/bookstack-to-pdf --config /opt/bookstack-to-pdf/config.yaml {input_html_path} {output_pdf_path}"
EXPORT_PDF_COMMAND_TIMEOUT=60Wichtig sind absolute Pfade und Leserechte für den User, unter dem BookStack läuft, häufig also www-data. Wer Tags im PDF haben will, sollte außerdem das im README beschriebene Export-Template-Override setzen. Sonst kann der Renderer nur das ausgeben, was BookStack ihm auch mitgibt.
Warum gleich ein eigenes „Projekt“?
Weil es ein kleines Problem ist, das im Alltag nervt. Und weil ich vermute, dass wir damit nicht alleine sind. BookStack ist für uns die ideale Basis für pragmatische Dokumentation. Schlank genug, dass Menschen es gerne nutzen. Strukturiert genug, dass man damit auch ernsthafte Unternehmensdokumentation und ISMS-Themen abbilden kann. Und offen genug, dass man solche Dinge sauber ergänzen kann, ohne gleich das ganze System zu verbiegen.
Vor bookstack-to-pdf hatten wir schon eine eigene Lösung mit WKHTML2PDF. Diese hat zwar mehr oder weniger zum Ziel geführt, aber wirklich vorzeigbar war sie nicht. Jetzt haben wir uns einfach etwas mehr Arbeit gemacht und wenn Ihr BookStack nutzt und PDFs mehr sein sollen als ein schneller Export, schaut es Euch gerne an.
0 Kommentare