Confluence Server(Data Center)에서 긁어 온 페이지 HTML 을 Confluence Cloud 에디터에 붙여넣거나 REST API 로 올리려면 Server 전용 마크업을 걷어내고 Cloud storage format 으로 바꿔야 한다. Server 의 wiki-content HTML 에는 tablesorter·aria-*·data-* 같은 UI 잔여물, expand·drawio 매크로, Prism.js 코드 블록이 섞여 있어 그대로 붙이면 표가 깨지거나 매크로가 글자 그대로 찍힌다. 붙여넣기용 정리와 API 업로드용 변환 두 갈래로 정리한다.
브라우저에서 정리된 HTML 을 열어 전체 선택(Ctrl+A) → 복사 → 에디터에 붙여넣는 방식이다. 변환 시 지켜야 할 핵심은 다음과 같다.
표는 리스트(<ul>/<li>) 안에 중첩하지 말고 최상위 레벨에 독립 <table> 로 둔다. Confluence 에디터는 리스트 내부 테이블을 제대로 파싱하지 못하는 경우가 있다. <colgroup> 으로 열 너비를, rowspan/colspan 을 명시하고 배경색은 인라인 스타일로 지정하면 복붙 시 구조가 안정적으로 들어간다.
변환 불가한 요소는 대체 표기로 남긴다. drawio 다이어그램은 텍스트 설명으로, 첨부 PNG 스키마 이미지는 "(원본 페이지 참고)" 표기로 두고, Team Calendar 같은 전용 매크로는 붙여넣기 후 에디터에서 /calendar 로 다시 삽입한다.
REST API 로 페이지를 갱신하려면 body 를 Cloud storage format(ac:structured-macro 계열)으로 만들어야 한다. 정규식 기반 Python 스크립트로 Server HTML 을 변환한 뒤 REST API v1 으로 PUT 한다. 자격증명은 코드에 넣지 말고 config.ini 등 외부 파일에서 읽는다.
주요 변환 규칙:
expand 매크로 → ac:structured-macro ac:name="expand". 제목이 query·scala script 같은 코드성이면 code 매크로로 펼친다.<span class="prismjs">...<code class="language-*">) → code 매크로 + ac:plain-text-body CDATA. <span> 을 모두 걷어내고 &·<·>·"· 를 실제 문자로 복원한다.tf-inline-filter·floating-scrollbar·헤딩 복사 링크 버튼(css-*), 그리고 class="confluenceT[hd]"·data-*·role·aria-*·unselectable·rel="nofollow" 속성.table-wrap 래퍼·colgroup 제거, <table>/<th>/<td> 의 인라인 style 제거, headerButton 래퍼 제거.</div> 는 열림/닫힘 수를 세어 뒤에서부터 제거한다.REST API 는 현재 버전을 조회해 version.number + 1 로 PUT 한다.
import requests, json
def get_version(base_url, page_id, auth):
r = requests.get(f"{base_url}/rest/api/content/{page_id}?expand=version", auth=auth)
r.raise_for_status()
d = r.json()
return d["version"]["number"], d["title"]
def upload(base_url, page_id, auth, version, title, content):
payload = {
"version": {"number": version + 1},
"title": title,
"type": "page",
"body": {"storage": {"value": content, "representation": "storage"}},
}
r = requests.put(f"{base_url}/rest/api/content/{page_id}",
auth=auth,
headers={"Content-Type": "application/json"},
data=json.dumps(payload))
r.raise_for_status()
정규식으로 HTML 을 다루는 방식이라 원본 마크업 구조가 조금만 달라도 규칙이 빗나간다. 중첩 expand 는 안쪽부터 바깥쪽으로 반복 치환해야 하고, code 매크로 언어 태그는 class="language-<lang>" 에서 유추한다. Server → Cloud 이관 시 페이지 간 링크(.../confluence/x/... → .../wiki/x/...)는 URL 매핑표로 치환한다. 자격증명·내부 URL 은 커밋·로그에 남기지 않는다.