Starlight in PDF umwandeln: Erfahrungen und Erkenntnisse

Stellen Sie sich vor, Sie erhalten eine Aufgabe: Erstellen Sie in einer Woche eine neue Dokumentationswebsite. Es sollte optisch ansprechend, schnell und einfach zu navigieren sein. Sie erhalten einen Stapel *.docs-Dateien, Bilder und Screenshots mit der Anweisung, „erledigen“.

Es stehen viele hervorragende Tools zur Auswahl, wie zum Beispiel Docusaurus, Nextra, VitePress, Docus und andere. Zuvor hatte ich großartige Erfahrungen beim Erstellen einer Dokumentationswebsite mit Starlight gemacht, daher war es meine Wahl für diese Aufgabe. Allerdings habe ich eine fehlende Funktion entdeckt: die Möglichkeit, aus der Dokumentation ein PDF zu generieren. Und es war eine der Anforderungen. „Klingt nach einem netten Nebenprojekt“, dachte ich mir.

Die Aufgabe angehen

Zuerst schien es einfach: Seiten abrufen, HTML analysieren, Inhalte gruppieren und voilà!

Starlight-basierte Websites verfügen über eine Schaltfläche „Weiter“, um durch die Dokumentation zu navigieren. Da es sich bei PDF im Wesentlichen um eine Reihe von Seiten handelt, schien es logisch, diese mit der Schaltfläche „Weiter“ einzeln zu analysieren. Da die Website statische Seiten generiert, habe ich schnell ein Skript geschrieben, um den HTML-Code abzurufen, die erforderlichen Teile abzufragen und alles zusammenzufügen. Allerdings erwies sich die Erstellung einer PDF-Datei, die den Stil der Website beibehielt, als komplexer. Nach einigem Brainstorming wurde mir klar, dass Puppeteer die beste Lösung war.

Jetzt wurde der Prozess klar:

1. Identifizieren Sie die Startseite. Dies ist die erste Seite mit der Schaltfläche „Weiter“.
2. Navigieren Sie durch die Seiten. Extrahieren Sie die Überschrift und den Hauptinhalt von jeder Seite und erstellen Sie gleichzeitig ein Inhaltsverzeichnis.
3. Kombinieren Sie den Inhalt. Fügen Sie Seitenumbrüche und zusätzliche Stile hinzu.
4. Bereiten Sie den endgültigen HTML-Code vor. Schreiben Sie den neu. der Startseite mit dem resultierenden HTML.
5. Ressourcen laden. Scrollen Sie auf der Seite nach unten, um alle Bilder zu laden.
6. Generieren Sie das PDF.Die Methode Page.pdf() von Puppeteer bringt es auf den Punkt.
Fertig!

So funktioniert Starlight-to-PDF. Nach diesem Muster können Sie ähnliche Tools für andere Dokumentations-Frameworks erstellen, denen die PDF-Exportfunktion fehlt.

Nächste Schritte

Sobald die Grundfunktionalität fertig war, war es an der Zeit, einige Extras hinzuzufügen. Nachfolgend finden Sie die interessantesten und anspruchsvollsten Funktionen.

Kopf- und Fußzeilen hinzufügen

Es ist schön, eine Seitenzahl und einige zusätzliche Informationen in der Kopf- oder Fußzeile zu haben. Die Page.pdf()-Methode von Puppeteer akzeptiert headerTemplate- und footerTemplate-Optionen. Diese Optionen akzeptieren HTML-Strings. Puppeteer fügt automatisch Werte in die Elemente ein, die bestimmte Dienstprogrammklassen haben:

• .date: formatiertes Datum;
• .title:
• .url: URL der Seite, auf der die Druckfunktion aufgerufen wurde;
• .pageNumber: aktuelle Seitenzahl;
• .totalPages: Gesamtzahl der Seiten im Dokument.

Da wir den gesamten Inhalt vor dem Drucken auf einer Seite zusammenfassen, haben Titel und URL für uns keinen großen Wert: Der eingefügte Wert bleibt immer derselbe. Andere Kurse helfen jedoch sehr. Hier ist ein Beispiel für eine Fußzeilenvorlage:

<style>
  .footer-container {
    --color: #000;

    display: flex;
    align-items: center;
    justify-content: space-between;
    border-block-start: 1px solid var(--color);
    color: var(--color);
    font-size: 10px;
    font-family: Arial, Helvetica, sans-serif;
    margin-inline: 1.5cm 1cm;
    padding-block: 0.25cm 0.5cm;
    width: 100%;
  }
</style>

<div>



<p>To use this, do not forget to set the displayHeaderFooter property to true:<br>
</p>

<pre class="brush:php;toolbar:false">import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://someUrl');

const footerTemplateStr = '<style>...<style><div>...</style>