[Marklas] ตัวแปลง Markdown <-> Atlassian Document Format (ADF) แบบสองทาง

Confluence และ Jira จัดเก็บเอกสารในโครงสร้าง JSON ที่เรียกว่า ADF (Atlassian Document Format) เมื่อต้องอ่านและเขียนเพจผ่าน API จึงต้องจัดการกับฟอร์แมตนี้โดยตรง แต่ฟีเจอร์เฉพาะของ ADF เช่น panel, mention และ colored text จะสูญหายเมื่อแปลงเป็น Markdown

Marklas แก้ปัญหานี้ด้วยการคงฟีเจอร์เฉพาะของ ADF ไว้ในรูปแบบ annotation ของคอมเมนต์ HTML

<!-- adf:panel {"panelType": "warning"} -->  
API นี้มีกำหนดจะถูกลบออกใน v2  
<!-- /adf:panel -->  

annotation จะไม่ถูกเรนเดอร์บน GitHub หรือในเอดิเตอร์ จึงไม่กระทบต่อความอ่านง่าย และเมื่อพาร์สกลับก็จะกู้คืนโครงสร้าง ADF เดิมได้ครบถ้วน

ADF → Markdown(พร้อม annotation) → ADF       ✅ การสูญหายน้อยที่สุด  
Markdown ทั่วไป → ADF                         ✅ ใช้งานได้  

from marklas import to_adf, to_md  
  
md = to_md(confluence_adf)       # แปลงเป็น Markdown เพื่อแก้ไข  
adf = to_adf(md)                 # กู้คืนกลับเป็น ADF  

เดิมทีผู้พัฒนารู้สึกติดขัดกับการใช้ไลบรารีแปลงเชิงพาณิชย์ที่มีอยู่ จึงสร้างตัวนี้ขึ้นมาเอง

รองรับ Python 3.13+ และมี dependency ภายนอกเพียง mistune ตัวเดียว