Scroll PDF Exporter Vorlagen
Für die Dokumentation sowohl intern als auch für Kunden benutzen wir Confluence von Atlassian. Da der enthaltene PDF-Export recht limitiert ist verwenden wir hierzu den Scroll PDF Exporter, welcher deutlich mehr Freiheiten bietet. In diesem Blogeintrag möchte ich einige Kniffe mit Ihnen teilen, die ich bei der Erstellung eines einheitlichen Template gelernt habe.
Herangehensweise
Der Exporter erstellt vor dem Export ein zusammenhängendes HTML Dokument der zu exportierenden Seiten und erstellt daraus dann das PDF. Somit können Anpassungen am Styling einfach über CSS Anweisungen formatiert werden - vorausgesetzt man findet die richtigen Klassennamen und Selektoren. Ein guter Einstieg ist das HelpCenter der Herausgeber K15t. Dort sind viele der Punkte, welche ich hier aufzeigen will, beschrieben. Ein zweiter Einstieg sind die Standard-Styles des Exporters. Um die Styles Ihrer Version zu bekommen müssen Sie folgende Schritte durchführen:
- Öffnen Sie der Atlassian Marktplatz https://marketplace.atlassian.com/plugins/com.k15t.scroll.scroll-pdf/cloud/overview
- Wechsen Sie auf die Seite „Versions“ und wählen sie „See all xy versions“
- Suchen Sie ihre Versionsnummer und laden sie die .obr Datei herunter
- Ändern Sie die Dateiendung zu .zip und entpacken Sie das Archiv
- In diesem finden sie eine .jar Datei. Ändern Sie auch hier die Endung zu .zip und entpacken Sie diese
- Die Standard-CSS-Dateien finden Sie nun im entpackten Archiv unter com > k15t > scroll > pdf > template > css
Quelle: https://help.k15t.com/scroll-pdf-exporter/default-css-styles-75367839.html
Im folgenden möchte ich einige - für uns - hilfreiche Anweisungen aufzeigen.
Seitenumbrüche
Bei uns werden Seiten oft zur Strukturierung benutzt und enthalten keinen direkten Inhalt (nur Unterseiten). Der Exporter fügt aber standardmäßig vor jede Seitenüberschrift einen Zeilenumbruch ein, was zu unschönen Leerseiten führt. Um dies zu unterbinden muss in der Bereichsvorlage unter Formatierung die Klasse section-1 angesprochen werden:
div.section-1 {
page-break-before: auto;
}
Um die Zugehörigkeit der Überschrift klar zu machen mussten wir noch die Abstände davor und danach festlegen:
div.section-1 {
margin-top: 0px;
margin-bottom: 0px;
}
div.section-1 h1 {
margin-top: .7em;
margin-bottom: 0px;
}
Ein weiterer Punkt ist die Verhinderung von Seitenumbrüchen zwischen Bildern und ihren Legenden. Dies erreichen wir mit folgender Anweisung:
.scroll-figure {
page-break-inside: avoid;
}
Zu guter Letzt wollen wir noch, wenn möglich, verhindern, dass innerhalb einer Tabellenzeile umgebrochen wird:
table tr {
page-break-inside: avoid;
}
Breite Tabellen
Tabellen können schnell sehr breit werden. Um diese in der PDF-Ausgabe noch lesbar zu halten können wir an ein paar stellen etwas Platz sparen. Zum einen können wir die Innenabstände der Tabelle verringern:
able thead tr td,
table tbody tr td {
padding-top: 0px !important;
padding-bottom: 0px !important;
padding-left: 3px !important;
padding-right: 3px !important;
}
Wenn man Listen in Tabellen verwendet kann man zusätzlich deren Einzug etwas verkleinern:
div.tablewrap > table ol, div.tablewrap > table ul,
div.tablewrap > table ol, div.tablewrap > table ol {
padding-left: 1.5em;
margin: 0px;
}
Wenn diese Einsparungen noch nicht ausreichen kann man sich zudem überlegen, das Dokument im Querformat zu exportieren. Dafür ergänzt man einfach:
@page {
size: A4 landscape;
}
Beachten Sie hier, dass unter umständen Bereiche mit fester Höhne neu definiert werden müssen. Bei uns war dies auf der Titelseite nötig. Diese muss gezielt angesprochen werden und einige div-Container neu definiert werden. Um die gesamte erste Seite anzusprechen kann der Selektor @page first verwendet werden.
Quelle: https://help.k15t.com/scroll-pdf-exporter/how-can-i-deal-with-wide-tables-75367879.html
Bekannte Probleme
Ein bekanntes Problem ist, dass Warnungen, Panels und Codeblocks ggf. über mehrere Seiten brechen. Um dies zu verhindern muss man vor dem Element manuell einen Seitenumbruch einfügen. Dafür kann ein PageBreak-Makro wie auf der folgenden Seite beschrieben eingesetzt werden: https://help.k15t.com/scroll-pdf-exporter/adding-pagebreaks-75367848.html
Quelle: https://k15t.jira.com/browse/EXP-528
Fazit
Ich habe hier nur die Anpassungen aufgezeigt, welche möglichst universell einsetzbar sind. Wenn man den Aufbau erst einmal etwas kennt kann man die Vorlagen gezielt auf seine Anforderungen anpassen. Ich hoffe, dass dies den ein oder anderen zum Experimentieren anregt.