# Show GN: [Marklas] Markdown <-> Atlassian Document Format(ADF) 양방향 변환기

> Clean Markdown view of GeekNews topic #27281. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=27281](https://news.hada.io/topic?id=27281)
- GeekNews Markdown: [https://news.hada.io/topic/27281.md](https://news.hada.io/topic/27281.md)
- Type: show
- Author: [byexist](https://news.hada.io/@byexist)
- Published: 2026-03-07T15:00:07+09:00
- Updated: 2026-03-07T15:00:07+09:00
- Original source: [github.com/byExist](https://github.com/byExist/marklas)
- Points: 11
- Comments: 0

## Summary

**Marklas**는 Confluence·Jira의 **ADF 문서를 Markdown으로 손실 없이 변환**하기 위한 Python 도구입니다. ADF 전용 요소를 HTML 주석 형태의 어노테이션으로 보존해, 일반 Markdown 편집 환경에서도 원본 구조를 그대로 복원할 수 있습니다. 외부 의존성은 *mistune* 하나로, 간결한 코드베이스에서 ADF ↔ Markdown 양방향 변환을 지원합니다.

## Topic Body

Confluence와 Jira는 문서를 ADF(Atlassian Document Format)라는 JSON 구조로 저장합니다. API로 페이지를 읽고 쓸 때 이 포맷을 직접 다뤄야 하는데, 패널·멘션·컬러텍스트 같은 ADF 전용 기능은 Markdown으로 변환하면 손실됩니다.  
  
Marklas는 ADF 전용 기능을 HTML 주석 어노테이션으로 보존해서 이 문제를 해결합니다.  
  
```markdown  
&lt;!-- adf:panel {"panelType": "warning"} --&gt;  
이 API는 v2에서 제거될 예정입니다.  
&lt;!-- /adf:panel --&gt;  
```  
  
어노테이션은 GitHub이나 에디터에서 렌더링되지 않아 가독성에 영향이 없고, 다시 파싱하면 원본 ADF 구조가 그대로 복원됩니다.  
  
```  
ADF → Markdown(어노테이션 포함) → ADF       ✅ 손실 최소화  
일반 Markdown → ADF                      ✅ 동작  
```  
  
```python  
from marklas import to_adf, to_md  
  
md = to_md(confluence_adf)       # Markdown으로 변환하여 편집  
adf = to_adf(md)                 # 다시 ADF로 복원  
```  
  
기존 상용 변환 라이브러리를 사용하다 불편함을 느껴서 직접 만들었습니다.  
  
Python 3.13+, 외부 의존성은 mistune 하나입니다.

## Comments



_No public comments on this page._