[Marklas] Bộ chuyển đổi hai chiều Markdown <-> Atlassian Document Format (ADF)

Confluence và Jira lưu tài liệu dưới dạng cấu trúc JSON gọi là ADF (Atlassian Document Format). Khi đọc và ghi trang qua API, bạn phải xử lý trực tiếp định dạng này, nhưng các tính năng riêng của ADF như panel, mention hay văn bản có màu sẽ bị mất khi chuyển sang Markdown.

Marklas giải quyết vấn đề này bằng cách bảo toàn các tính năng riêng của ADF bằng annotation trong chú thích HTML.

<!-- adf:panel {"panelType": "warning"} -->  
API này sẽ bị loại bỏ ở v2.  
<!-- /adf:panel -->  

Các annotation này không được render trên GitHub hay trong editor nên không ảnh hưởng đến khả năng đọc, và khi parse lại thì cấu trúc ADF gốc được khôi phục nguyên vẹn.

ADF → Markdown(có annotation) → ADF       ✅ Giảm thiểu mất mát  
Markdown thông thường → ADF               ✅ Hoạt động  

from marklas import to_adf, to_md  
  
md = to_md(confluence_adf)       # Chuyển sang Markdown để chỉnh sửa  
adf = to_adf(md)                 # Khôi phục lại thành ADF  

Tác giả đã tự làm công cụ này sau khi dùng các thư viện chuyển đổi thương mại hiện có và thấy bất tiện.

Python 3.13+, phụ thuộc bên ngoài chỉ có mistune.