Reconstruire l'export PDF + DOCX : WeasyPrint, filtres Lua Pandoc et faire confiance au frontend

Ingénierie 6 mai 2026 · 11 min de lecture

Pour un éditeur de documents, « Exporter » ne peut signifier qu'une seule chose : ce que vous voyez est ce qui sort du fichier. Tout le reste donne une impression de dysfonctionnement, même lorsque le problème est minime — un titre centré à l'écran mais aligné à gauche dans le PDF, un paragraphe qui se coupe différemment parce que les métriques de police du serveur ne concordent pas avec celles du navigateur, un DOCX exporté dont le titre bleu est devenu noir parce que Word ne parle pas le CSS.

Au cours des deux dernières semaines, nous avons réécrit l'intégralité du pipeline d'export derrière AgentDoc – l'éditeur de documents nativement conçu pour l'IA (aussi : agent doc, agentdocs, docedit) – pour que le WYSIWYG soit réellement vrai. Deux formats, deux moteurs, une seule idée architecturale : le frontend est déjà la source de vérité pour la mise en page, donc le serveur devrait la suivre, pas la recalculer.

L'ancienne conception et pourquoi elle restait subtilement erronée

Avant la réécriture, l'export PDF et l'export DOCX fonctionnaient en envoyant le markdown brut du document au backend, où un moteur de rendu allait (a) le repaginer côté serveur, (b) appliquer un CSS qui était un sous-ensemble maintenu à la main du style.css de l'éditeur, et (c) transmettre le résultat à WeasyPrint ou à un générateur docx rapide. Trois modes de défaillance en découlaient :

La pagination divergeait. Le paginateur du navigateur mesurait chaque bloc dans un DOM réel avec les vraies polices chargées ; le serveur mesurait un DOM différent avec des polices subtilement différentes et des largeurs disponibles différentes. Des documents de dix pages ressortaient régulièrement en neuf ou onze, et la page où un titre apparaissait se décalait.
Divergence du CSS. Le CSS d'export était une copie de style.css avec des modifications appliquées de manière paresseuse. Les tableaux avaient des en-têtes centrés dans l'éditeur et alignés à gauche dans le PDF ; <blockquote> avait une bordure gauche à l'écran et pas dans l'export. Nous déboguions des sélecteurs individuels au lieu de l'architecture.
Le DOCX était une tout autre bête. L'ancien chemin rapide et bâclé intégrait l'en-tête/pied de page sous forme de texte en italique en haut et en bas du corps, supprimait les classes de couleur et de police, et produisait quelque chose dont les utilisateurs de Word parlaient poliment mais qu'ils n'utilisaient pas réellement.

La pagination côté serveur du contenu de l'éditeur est un problème de mise en cache déguisé en problème de mise en page. Le navigateur a déjà fait le travail ; envoyer le résultat vers le bas est moins coûteux que de le refaire.

Le changement architectural : le frontend fournit une html_map

L'éditeur sait déjà où chaque saut de page tombe. Son paginateur exécute la mise en page, parcourt le DOM et produit un tableau de fragments HTML – un par page – plus les métadonnées de mise en page actives (page_size, margin_mm). Tout ce dont nous avions besoin, c'était d'un moyen d'envoyer cela aux points de terminaison d'export.

Le nouveau contrat d'export : lorsque l'utilisateur clique sur « Exporter en PDF » ou « Exporter en DOCX », le frontend joint la carte de pagination (html_map) au corps de la requête. Le serveur la traite comme la mise en page faisant autorité et cesse d'essayer de calculer la sienne.

POST /api/doc/{id}/pdf
{
  "html_map": [
    "<div class='page-content'>…page 1 HTML…</div>",
    "<div class='page-content'>…page 2 HTML…</div>",
    …
  ],
  "header_html": "…",
  "footer_html": "…",
  "page_size": "A4",
  "margin_mm": 20
}

Le générateur de PDF enveloppe chaque entrée dans un bloc .page-content de taille fixe, force un saut de page strict entre elles via le CSS break-after: page, et laisse WeasyPrint effectuer la rastérisation proprement dite. L'en-tête et le pied de page passent par le mécanisme running() de WeasyPrint afin de se positionner dans les boîtes de marge haut-centre / bas-centre sur chaque page physique – y compris la rare deuxième page physique sur laquelle une entrée de carte surdimensionnée pourrait déborder.

Deux pipelines, un repli

Toutes les requêtes d'export ne proviennent pas du navigateur. Des agents externes appelant notre serveur MCP peuvent émettre un appel d'outil « télécharge ce document » avant qu'un humain n'ait jamais ouvert le document dans l'éditeur – ce qui signifie qu'il n'y a pas encore de html_map, parce qu'aucun navigateur n'a effectué le travail de mise en page.

Pour ce cas, le serveur se rabat sur la pagination native de WeasyPrint via les règles @page. Nous avions déjà un repli auparavant, mais il comportait le bug qui a déclenché la réécriture en premier lieu : une règle de découpage à hauteur fixe censée gérer le cas html_map se déclenchait aussi sur le chemin de repli, et tout contenu au-delà de la première page était silencieusement tronqué. Des enquêtes comme celle-là sont la raison pour laquelle nous maintenons désormais deux chemins de code distincts plutôt qu'une seule généralisation astucieuse.

DOCX : Pandoc + un reference.docx construit à la main

Le DOCX mérite un traitement particulier parce que Word ne parle pas du tout le CSS. L'approche naïve – HTML → une bibliothèque quelconque → .docx – jette à la poubelle chaque classe sur chaque span et vous donne un document qui contient le bon texte mais aucune mise en forme.

Nous utilisons Pandoc pour le corps, python-docx pour les éléments spécifiques à Word que Pandoc ne peut pas atteindre (en-tête de page, pied de page), et un reference.docx construit à la main comme modèle de style.

L'astuce du reference.docx

Le drapeau --reference-doc=… de Pandoc vous permet de fournir un document Word dont les styles définissent vos « Titre 1 », « Normal », « Titre », etc. Pandoc effectue le rendu du markdown, applique ces styles, et le résultat hérite de tout ce que vous avez mis dans la référence – polices, couleurs, hauteur de ligne, marges, indentation des listes.

Nous générons reference.docx à partir d'un petit script de build à usage unique (templates/build_reference_docx.py) qui émet la référence par défaut de Pandoc puis la corrige avec python-docx de sorte que :

Titre 1 / 2 / 3 / Titre utilisent Playfair Display, en gras, dans le bleu marine text-primary de notre éditeur (#111827) – exactement la même couleur que le titre a dans le navigateur.
Normal / Paragraphe de liste / Corps utilisent Inter 11pt en ardoise (#374151), avec une hauteur de ligne de 1.7 et une indentation de liste de 0,25" – ajustés sur l'éditeur.
Les styles En-tête / Pied de page sont en Inter 10pt avec la fine bordure inférieure que l'éditeur affiche via CSS, afin que le séparateur visuel survive au changement de format.
Le fontTable.xml est étendu avec une entrée <w:font> par police de caractères de l'éditeur, chacune portant un indice <w:altName> pointant vers la famille standard de Word la plus proche (Inter → Calibri, Playfair Display → Cambria, Roboto Mono → Consolas, etc.). Les utilisateurs de Word sans nos polices exactes installées voient la substitution alt au lieu de revenir à Times New Roman.

Classes en ligne : le filtre Lua

Le générateur docx de Pandoc supprime les attributs de style CSS sur les éléments Span. C'est très bien pour du markdown simple mais c'est un problème pour AgentDoc, où chaque style en ligne est encodé sous forme de classe décalée sur un span : [text]{.color-red}, [text]{.highlight-yellow}, [text]{.font-lora .size-xl}, etc.

La solution : un petit filtre Lua Pandoc (templates/inline_styles.lua) qui parcourt l'AST pendant la passe du générateur docx et traduit les classes en propriétés de run OOXML brutes :

function Span(el)
  for _, cls in ipairs(el.classes) do
    if cls:match("^color%-") then
      local hex = COLORS[cls:sub(7)]
      if hex then
        return pandoc.RawInline("openxml",
          '<w:rPr><w:color w:val="'..hex..'"/></w:rPr>'
        ), el.content
      end
    elseif cls:match("^highlight%-") then …
    elseif cls:match("^font%-")      then …
    elseif cls:match("^size%-")      then …
    end
  end
end

La couverture est exhaustive à dessein :

Couleurs : 17 couleurs nommées de l'éditeur mappées sur le hex réel utilisé par le CSS, pas sur les hex des mots-clés W3C. color-red est l'alizarine plus douce de l'éditeur #E74C3C, pas #FF0000 ; color-blue est #3498DB, pas #0000FF. Un titre bleu dans le navigateur s'affiche désormais comme le même bleu dans Word.
Surlignages : l'ensemble complet des surlignages nommés de Word (jaune / vert / cyan / magenta / bleu / rouge plus les variantes foncées/claires) ; tout ce qui se trouve en dehors de cet ensemble retombe sur le jaune plutôt que de disparaître silencieusement.
Polices : 12 entrées émettant <w:rFonts ascii="…" hAnsi="…" cs="…" eastAsia="…"/> pour chaque police de caractères de l'éditeur.
Tailles : 7 jetons (xs..3xl) émis sous forme de valeurs <w:sz w:val="halfPt"/>, dérivées en em par rapport à la ligne de base de corps de 13pt utilisée par reference.docx.
Décorations : decoration-bold / -italic / -strikethrough sont traduites en markdown standard avant Pandoc, de sorte que nous obtenons de vrais runs <w:b/>, <w:i/>, etc. au lieu d'OOXML brut.

Les combinaisons s'empilent. Un span comme [text]{.color-red .size-xl .font-lora} émet un seul run avec les trois propriétés définies dans un unique <w:rPr>.

En-tête et pied de page : la post-passe python-docx

Le générateur docx de Pandoc produit un corps mais ne remplit pas l'en-tête / le pied de page de section. Notre solution de contournement précédente – les intégrer sous forme de lignes d'introduction / de conclusion en italique – était une catastrophe ergonomique : tout utilisateur qui exportait une vraie lettre voyait le texte de son en-tête flotter au-dessus de l'adresse du destinataire.

Après l'exécution de Pandoc, une post-passe python-docx ouvre le docx résultant, parcourt section.header / section.footer, et écrit le markdown d'en-tête/pied de page via un petit analyseur en ligne. L'analyseur gère le gras (**…**), l'italique (*…*), et la même syntaxe de span décalée que le corps utilise (color-X, highlight-X, decoration-*) – mappés respectivement sur les couleurs de run, les surlignages et les propriétés gras/italique <w:rPr> de Word.

Le résultat se trouve dans l'en-tête de section Word réel, ce qui signifie qu'il apparaît sur chaque page et s'imprime correctement – y compris lors des repaginations que Word effectue lui-même lorsque le destinataire ouvre le document.

Cloisonnement des workflows : T+ obtient le nouvel export, T reste stable au bit près

L'export DOCX est, délibérément, une fonctionnalité disponible uniquement sur le Workflow T+. T reste stable au bit près parce que les benchmarks de granularité des outils ont été exécutés contre sa surface d'outils exacte, et nous voulons que ces fichiers CSV restent reproductibles. T+ est la voie de production mutable post-benchmark et reçoit les ajouts.

Cela est appliqué à deux endroits pour rendre les fuites impossibles :

agent/routers/chat.py définit T_PLUS_EXCLUSIVE_TOOLS = {"trigger_docx_download"} ; la branche de T exclut explicitement cet ensemble afin qu'un outil nouvellement enregistré ne puisse pas atterrir accidentellement dans le schéma gelé de T.
mcp_workflow_middleware.WORKFLOW_T_DENY liste aussi l'outil, de sorte que les agents externes (qui sont épinglés à la surface de T par conception) ne le voient pas non plus via le point de terminaison MCP.

Ce que nous n'avons explicitement pas fait

Deux choses sont restées non faites à dessein ; les deux sont des compromis qu'il vaut la peine d'expliciter :

L'intégration des polices. Une correction véritablement 1:1 intégrerait les véritables TTF Inter / Playfair Display / etc. dans chaque DOCX généré. Cela ajouterait aussi ~400 Ko par export, plus une revue juridique par police pour la redistribution. Nous nous appuyons à la place sur la substitution de police de Word + les indices altName dans notre fontTable étendue. La plupart des familles de l'éditeur sont des Google Fonts populaires que de nombreux utilisateurs d'Office 365 possèdent déjà.
Un pipeline pour les gouverner tous. Nous maintenons désormais deux chemins de code PDF distincts (html_map vs. repli) et un chemin DOCX séparé. Généraliser davantage permettrait au type de bug de découpage à hauteur fixe d'auparavant de réapparaître silencieusement. Deux chemins de code plus des tests d'intégration valent mieux qu'un seul astucieux.

Les tests d'intégration qui détectent réellement les régressions

Ce qui fait tenir cette réécriture, c'est un ensemble de scripts d'audit manuels qui introspectent la sortie rendue :

backend/tests/manual_pdf_audit.py    # uses pypdf to read text + font metadata
backend/tests/manual_docx_audit.py   # walks the OOXML and checks run properties
backend/tests/manual_format_parity.py # diffs editor classes against Word run props

Ce ne sont pas des tests unitaires ; ce sont des outils que nous exécutons après des changements non triviaux pour confirmer que le fichier exporté possède bien la couleur que nous attendons sur le titre que nous attendons. Nous avons ajouté poppler-utils et pypdf au Dockerfile du backend pour qu'ils fonctionnent aussi sur l'image de production, ce qui signifie que nous pouvons les exécuter contre de vrais documents utilisateur lors de l'enquête sur une réclamation.

Ce que nous avons appris et qui mérite d'être conservé

Trois leçons durables de cette réécriture :

Ne recalculez pas ce que le client a déjà calculé. Si le navigateur a paginé le document, envoyez la pagination vers le bas. Tout recalcul côté serveur divergera de manière subtile et vous passerez des semaines à courir après les divergences.
Utilisez le mécanisme de modèle propre au format au lieu de le combattre. --reference-doc=… de Pandoc est la bonne échappatoire pour le DOCX. Les règles @page de WeasyPrint sont la bonne échappatoire pour le PDF. Les bibliothèques HTML-vers-DOCX faites maison perdent toujours face à Pandoc + un document de référence sur toute sortie non triviale.
Deux chemins de code et un test qui détecte la différence valent mieux qu'un seul chemin de code auquel vous devez faire confiance. Le coût des chemins parallèles est faible ; le coût d'un bug de troncature silencieuse dans le repli est élevé.

Le prochain article de cette série porte sur l'architecture vocale en priorité – y compris des travaux récents de fiabilité sur la reprise de session Gemini Live qui méritent aussi un article à part entière. Si un détail particulier vous intéresse plus en profondeur, le widget de retour en bas à droite de chaque page de ce site arrive directement dans notre boîte de réception.

← Notes de version – avril 2026 Granularité des outils dans les agents LLM →