Moonwalker1307/pdfpecker

Création et lecture de PDF avec pdfpecker

pdfpecker transforme du HTML et CSS (ou du Markdown) en PDF sans navigateur, et reconvertit les pages PDF en images pour que vous puissiez visualiser ce que vous avez créé. Travaillez dans cet ordre : écrire le HTML, convertir, regarder les pages, corriger, reconvertir.

Configuration

python3 -c "import pdfpecker" 2>/dev/null || python3 -m pip install --quiet pdfpecker

Le script d'aide est scripts/pdf.py dans le dossier de cette compétence (dans Claude Code : ${CLAUDE_SKILL_DIR}/scripts/pdf.py). Il encapsule le package afin que vous n'ayez pas besoin de Python personnalisé pour les tâches courantes :

python3 scripts/pdf.py html invoice.html invoice.pdf          # les images et CSS sont résolus à côté du fichier HTML
python3 scripts/pdf.py md notes.md notes.pdf --page-size Letter
python3 scripts/pdf.py preview invoice.pdf --dpi 80           # écrit invoice-page-1.png, ... et affiche les chemins
python3 scripts/pdf.py text report.pdf --pages 1-2
python3 scripts/pdf.py markdown report.pdf report.md          # n'importe quel PDF en Markdown, tableaux et listes conservés
python3 scripts/pdf.py info report.pdf                        # nombre de pages
python3 scripts/pdf.py merge all.pdf cover.pdf report.pdf

Exécutez python3 scripts/pdf.py <commande> --help pour chaque option. Depuis Python, les mêmes appels sont pdfpecker.html_to_pdf(html, base_dir=...), html_file_to_pdf(chemin, sortie), markdown_to_pdf(texte), pdf_to_images(pdf, dpi=80), pdf_to_text(pdf), pdf_to_markdown(pdf), pdf_page_count(pdf), merge_pdfs([...]) et pdf_to_pdfa(pdf, "sortie.pdf") (un PDF existant converti en PDF/A pour archivage).

Écrire le HTML

Partez d'un modèle quand il en existe un adapté : templates/invoice.html (facture d'une page avec un tableau de lignes) et templates/report.html (rapport multipage avec couverture, numéros de page, un tableau répétant son en-tête, et un graphique en SVG). Copiez-le à côté de votre sortie et éditez-le.

Placez la mise en page de la page en CSS, pas dans les options :

@page {
  size: A4;                      /* ou Letter, A5, "A4 landscape", 210mm 99mm */
  margin: 18mm 16mm 20mm;
  @bottom-center { content: "Page " counter(page) " sur " counter(pages); font: 9pt sans-serif; color: #666; }
}
@page :first { @bottom-center { content: none; } }
h2 { break-after: avoid; }        /* garder un titre avec ce qui suit */
tr, figure, .card { break-inside: avoid; }
.new-page { break-before: page; }
thead { display: table-header-group; }   /* répété sur chaque page (comportement par défaut de <thead>) */

Ce qu'il faut savoir (détails dans reference.md) :

• Pas de JavaScript. Les scripts ne s'exécutent pas. Dessinez les graphiques en SVG en ligne ou en CSS (barres en tant que <div> dimensionnés), et remplissez les données avant la conversion.
• Pas de réseau. Les images, feuilles de style et polices sont chargées depuis le dossier du fichier HTML (base_dir) ou des URI data:, jamais depuis des URL http(s). Téléchargez d'abord ce dont vous avez besoin, ou incorporez-le.
• Polices. Sans vos propres polices, le texte utilise Helvetica (sans-serif, Arial), Times (serif) et Courier (monospace), avec des polices de secours intégrées, qui couvrent le latin, le grec et le cyrillique. Les écritures chinoise, japonaise, coréenne, arabe, hébraïque, hindi, thaïe et autres apparaîtront comme ? sauf si vous fournissez une police qui les prend en charge : --font NotoSansSC-Regular.otf (ou --system-fonts pour utiliser les polices installées sur la machine). Utilisez @font-face avec un src relatif pour une police spécifique.
• Le CSS moderne fonctionne : flexbox, grille, tableaux, flottants, colonnes multiples, positionnement, transformations, dégradés, ombres, coins arrondis, object-fit, SVG, polices web, compteurs et variables CSS. Mettez en page comme vous le feriez pour l'aperçu avant impression de Chrome ; PdfPecker suit la mise en page de Chrome.
• Unités. Utilisez mm, pt ou px (96 px par pouce). La largeur du contenu A4 avec des marges de 16 mm est de 178 mm (environ 673 px).

Vérifier le résultat

Regardez toujours les pages avant de remettre un PDF : exécutez preview et visualisez les PNG. Vérifiez qu'il n'y a pas de texte coupé ou débordant de la page, un tableau ou titre mal coupé entre pages, une ligne isolée en bas d'une nouvelle page, des pages vides, des ? à la place des lettres (police manquante) et des images qui ne se sont pas chargées (mauvais chemin). text confirme le texte et l'ordre. Corrigez le HTML ou le CSS, reconvertissez, et vérifiez à nouveau.

Erreurs

Le script se termine avec le code 1 et affiche la raison. Depuis Python, chaque erreur est une pdfpecker.PdfPeckerError : PdfPeckerArgumentError pour une option incorrecte, PdfReadError pour un fichier qui n'est pas un PDF lisible, PdfPasswordError, PdfLimitError (trop de pages), PdfTimeoutError, et PdfFileError pour une police ou un fichier illisible.