[Marklas] Convertisseur bidirectionnel Markdown <-> Atlassian Document Format (ADF)

Confluence et Jira stockent les documents dans une structure JSON appelée ADF (Atlassian Document Format). Lorsqu’on lit et écrit des pages via l’API, il faut manipuler directement ce format, mais des fonctionnalités spécifiques à l’ADF comme les panneaux, les mentions ou le texte en couleur sont perdues lors de la conversion en Markdown.

Marklas résout ce problème en préservant les fonctionnalités propres à l’ADF sous forme d’annotations de commentaires HTML.

<!-- adf:panel {"panelType": "warning"} -->  
Cette API sera supprimée dans la v2.  
<!-- /adf:panel -->  

Les annotations ne sont pas rendues sur GitHub ou dans les éditeurs, donc elles n’affectent pas la lisibilité, et lors d’un nouveau parsing, la structure ADF d’origine est restaurée telle quelle.

ADF → Markdown (avec annotations) → ADF       ✅ Perte minimale  
Markdown classique → ADF                      ✅ Fonctionne  

from marklas import to_adf, to_md  
  
md = to_md(confluence_adf)       # Conversion en Markdown pour édition  
adf = to_adf(md)                 # Restauration en ADF  

Après avoir utilisé une bibliothèque de conversion commerciale existante et l’avoir trouvée peu pratique, je l’ai développée moi-même.

Python 3.13+, avec une seule dépendance externe : mistune.