Hinweis zu den @page-Regeln bei der PDF-Generierung mit Puppeteer

Bestimmte @page-Eigenschaften werden aufgrund von Weiterentwicklungen bei Browser-Rendering-Standards möglicherweise anders dargestellt. Das kann Anpassungen an deinem bestehenden CSS erfordern, um die Kompatibilität mit modernen Browsern sicherzustellen. Prüfe für die besten Ergebnisse und die größte Kompatibilität beim PDF-Export die folgende Anleitung zu unterstützten Eigenschaften und Best Practices.

Nicht unterstützte @page-Eigenschaften und Alternativen

1. @page :first

• Problem: Die Pseudoklasse :first zum Ansprechen der ersten Seite wird in Puppeteer nicht unterstützt.
• Lösung: Verwende stattdessen body:first-of-type, um den Inhalt der ersten Seite anzusprechen.

Ersetze:

1
@page :first {
2
    /* your css here */
3
}

Mit:

1
@media print {
2
    body:first-of-type {
3
        /* your css here */
4
    }
5
}

2. Hintergrundbilder in @page

• Problem: Direkt auf die @page-Regel angewendete Hintergrundbilder werden nicht dargestellt.
• Lösung: Wende Hintergrundbilder auf body oder einen bestimmten Container mit position: fixed an.

Ersetze:

1
@page {
2
    background-image: url('https://your-confluence-instance.atlassian.net/wiki/download/attachments/SPACE_ID/background.png');
3
    background-size: cover;
4
    background-repeat: no-repeat;
5
}

Mit:

1
@media print {
2
    body {
3
        background-image: url('https://your-confluence-instance.atlassian.net/wiki/download/attachments/SPACE_ID/background.png');
4
        background-size: cover;
5
        background-repeat: no-repeat;
6
    }
7
}

Warum diese Änderungen nötig sind

Puppeteer nutzt die Rendering-Engine von Chromium, die moderne, bildschirmbasierte CSS-Standards gegenüber älteren oder druckspezifischen CSS-Regeln wie @page bevorzugt. Mit @media print und modernem CSS stellst du eine konsistente PDF-Darstellung über Browser und Puppeteer hinweg sicher.

Zusammenfassung der Ersetzungen

Bilder und Schriftarten in deinem eigenen CSS verwenden

Wenn du in deinem eigenen CSS für Confluence-Exporte Bilder oder Schriftarten verwenden möchtest, gehe wie folgt vor, damit sie erreichbar sind:

1. Lade deine Datei hoch:
   • Gehe zu einer Confluence-Seite in deinem Bereich. Erstelle für eine bessere Organisation am besten eine eigene Seite, z. B. mit dem Namen „Assets”.
   • Lade deine Bild- oder Schriftdateien auf diese Seite hoch.
2. Rufe den Link zur Datei ab:
   • Klicke nach dem Hochladen auf das Menü Weitere Aktionen (drei Punkte) auf der Seite.
   • Wähle Anhänge aus dem Dropdown-Menü aus.
   • Suche deine hochgeladene Datei in der Anhangsliste.
   • Klicke mit der rechten Maustaste auf den Dateinamen und wähle Link-Adresse kopieren aus.
3. Verwende den Link in deinem CSS:

   • Füge den kopierten Link an der Stelle in deiner CSS-Datei ein, an der ein Bild oder eine Schriftart benötigt wird. Zum Beispiel:

     1
     @font-face {
     2
         font-family: 'CustomFont';
     3
         src: url('https://your-confluence-instance.atlassian.net/wiki/download/attachments/SPACE_ID/filename.ttf');
     4
     }
     5
     body, h1, h2, h3, h4, h5, h6, p, a, li, span, div {
     6
         font-family: 'CustomFont' !important;
     7
     }
     8
     body {
     9
         background-image: url('https://your-confluence-instance.atlassian.net/wiki/download/attachments/SPACE_ID/background.png');
     10
     }

Hinweis: Achte darauf, dass die Seite mit den Assets für die vorgesehenen Nutzer deiner Confluence-Inhalte zugänglich ist. Berechtigungen auf der Asset-Seite wirken sich auf die Sichtbarkeit aus.

Einschränkungen bei der Formatierung des Inhaltsverzeichnisses

Beachte, dass es beim Übergang zu PDF v2 aktuell Einschränkungen bei der Formatierung des Inhaltsverzeichnisses (Table of Contents, TOC) gibt. Andere CSS-Eigenschaften, die zuvor verfügbar waren, funktionieren in PDF v2 vorerst nicht wie erwartet.

Aktuell unterstützte TOC-Eigenschaften:

• margin: Gesamter Außenabstand
• margin-top: Außenabstand oben
• margin-bottom: Außenabstand unten
• margin-left: Außenabstand links
• margin-right: Außenabstand rechts
• size: Seitengröße
• display: Prüft, ob das Inhaltsverzeichnis deaktiviert werden soll (none)

Wenn du die folgenden Eigenschaften für das Inhaltsverzeichnis anpassen möchtest, verwende dafür den folgenden Selektor.

1
div.toc-macro {
2
    display: none;
3
    /* weitere unterstützte Eigenschaften ... */
4
}

Eigenes HTML kann dem Inhaltsverzeichnis derzeit nicht hinzugefügt werden.

Nummerierung deiner Überschriften per CSS

Wenn du deinen Überschriften bei Confluence-Exporten eine automatische Nummerierung hinzufügen möchtest, verwende folgendes CSS:

1
body { counter-reset: heading1_counter; }
2
h1 {
3
    counter-reset: heading2_counter;
4
}
5
h2 {
6
    counter-reset: heading3_counter;
7
}
8
h3 {
9
    counter-reset: heading4_counter;
10
}
11
h4 {
12
    counter-reset: heading5_counter;
13
}
14
h1:before {
15
    counter-increment: heading1_counter;
16
    content: counter(heading1_counter) ". ";
17
}
18
h2:before {
19
    counter-increment: heading2_counter;
20
    content: counter(heading1_counter) "." counter(heading2_counter) ". ";
21
}
22
h3:before {
23
    counter-increment: heading3_counter;
24
    content: counter(heading1_counter) "." counter(heading2_counter) "." counter(heading3_counter) ". ";
25
}
26
h4:before {
27
    counter-increment: heading4_counter;
28
    content: counter(heading1_counter) "." counter(heading2_counter) "." counter(heading3_counter) "." counter(heading4_counter) ". ";
29
}
30
h5:before {
31
    counter-increment: heading5_counter;
32
    content: counter(heading1_counter) "." counter(heading2_counter) "." counter(heading3_counter) "." counter(heading4_counter) "." counter(heading5_counter) ". ";
33
}

So werden deine Überschriften automatisch hierarchisch nummeriert (z. B. 1., 1.1., 1.1.1.) — für eine bessere Struktur und Lesbarkeit.

Probleme mit der Schriftgröße von Links beheben

Wenn Hyperlinks in der falschen Größe dargestellt werden, kannst du das per CSS mit Schriftinformationen beheben.

1
h1 {
2
  font-size: 40px !important;
3
}
4
h2 {
5
  font-size: 38px !important;
6
}
7
h3 {
8
  font-size: 30px !important;
9
}
10
h4 {
11
  font-size: 25px !important;
12
}
13
h5 {
14
  font-size: 21px !important;
15
}
16
h6 {
17
  font-size: 17px !important;
18
}
19
code,
20
blockquote {
21
  font-size: 20px !important;
22
}
23
ol li::marker {
24
  font-size: 20px;
25
}
26
*:not(pre) > p {
27
  font-size: 140% !important;
28
}
29
a {
30
  font-size: inherit !important;
31
}

Nicht unterstützte CSS-Funktionen beim PDF-Export

Bei Verwendung des neuen PDF-Export-Systems (PDF v2) werden bestimmte erweiterte CSS-Funktionen aufgrund von Einschränkungen moderner Browser nicht mehr unterstützt. Insbesondere CSS-Eigenschaften wie target-counter() und leader(), die zuvor zur verbesserten Formatierung von PDFs genutzt wurden (z. B. um Seitenzahlen in einem Inhaltsverzeichnis hinzuzufügen), werden von aktueller Browsertechnologie nicht unterstützt.

Was bedeutet das für deine Inhalte?

Wenn dein eigenes CSS Regeln wie die folgende enthält:

1
div.toc a::after {
2
    content: leader('.') target-counter(attr(href), page);
3
}

funktionieren diese Regeln im neuen PDF-Export-System nicht. Dadurch fehlen Funktionen wie die automatische Seitennummerierung im Inhaltsverzeichnis oder gepunktete Linien zwischen Überschriften und Seitenzahlen im exportierten PDF.