Transformer Starlight en PDF : expérience et perspectives

Imaginez qu'on vous confie une tâche : créer un nouveau site Web de documentation en une semaine. Il doit être visuellement attrayant, rapide et facile à naviguer. Vous recevez une pile de fichiers *.docs, d'images et de captures d'écran, avec l'instruction de "faire le travail".

Il existe de nombreux excellents outils parmi lesquels choisir, tels que Docusaurus, Nextra, VitePress, Docus et d'autres. Auparavant, j'avais une grande expérience dans la création d'un site Web de documentation avec Starlight, c'était donc mon choix pour cette tâche. Cependant, j'ai découvert une fonctionnalité manquante : la possibilité de générer un PDF à partir de la documentation. Et c'était l'une des exigences. "Ça ressemble à un joli projet parallèle", ai-je pensé.

S'attaquer à la tâche

Au début, cela semblait simple : récupérer les pages, analyser le HTML, regrouper le contenu, et le tour est joué !

Les sites Web alimentés par Starlight ont un bouton Suivant pour naviguer dans la documentation. Comme le PDF est essentiellement un tableau de pages, il semblait logique de les analyser une par une, à l'aide de ce bouton Suivant. Étant donné que le site Web génère des pages statiques, j'ai rapidement écrit un script pour récupérer le code HTML, interroger les parties nécessaires et combiner le tout. Cependant, générer un PDF conservant les styles du site Web s'est avéré plus complexe. Après quelques réflexions, j'ai réalisé que Puppeteer était la meilleure solution.

Maintenant, le processus est devenu clair :

1. Identifiez la page de démarrage. Il s'agit de la première page avec un bouton Suivant.
2. Naviguez à travers les pages. Extrayez le titre et le contenu principal de chaque page et créez en même temps une table des matières.
3. Combinez le contenu. Ajoutez des sauts de page et des styles supplémentaires.
4. Préparez le HTML final. Réécrivez le de la page initiale avec le HTML résultant.
5. Charger les ressources. Faites défiler la page vers le bas pour charger toutes les images.
6. Générez le PDF. La méthode Page.pdf() de Puppeteer réussit.
7. Fait !

Voici comment fonctionne starlight-to-pdf. En suivant ce modèle, vous pouvez créer des outils similaires pour d'autres cadres de documentation dépourvus de fonctionnalité d'exportation PDF.

Prochaines étapes

Une fois les fonctionnalités de base prêtes, il était temps d'ajouter quelques extras. Vous trouverez ci-dessous les fonctionnalités les plus intéressantes et les plus stimulantes.

Ajout d'en-têtes et de pieds de page

C'est bien d'avoir un numéro de page et quelques informations supplémentaires dans l'en-tête ou le pied de page. La méthode Page.pdf() de Puppeteer accepte les options headerTemplate et footerTemplate. Ces options acceptent les chaînes HTML. Puppeteer injecte automatiquement des valeurs dans les éléments qui ont des classes utilitaires spécifiques :

• .date : date formatée ;
• .title :  de la page Web. valeur de la balise ;
• .url : URL de la page sur laquelle la fonction d'impression a été appelée ;
• .pageNumber : numéro de la page actuelle ;
• .totalPages : nombre total de pages dans le document.

Comme nous regroupons tout le contenu sur une seule page avant l'impression, le titre et l'url n'ont pas beaucoup de valeur pour nous : la valeur insérée restera toujours la même. Cependant, d’autres cours aident beaucoup. Voici un exemple de modèle de pied de page :

<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>...</div>' // replace with the HTML string from the example above
await page.pdf({
    displayHeaderFooter: true,
    footerTemplate: footerTemplateStr
})

Voici quelques constatations que vous devez garder à l’esprit :

• Le modèle doit être une structure HTML valide.
• Définissez la propriété CSS font-size car la valeur par défaut de Puppeteer est 0.
• Utilisez le