마크다운을 Confluence 위키 마크업으로 변환하는 방법
Markdown으로 글을 쓰지만 Atlassian Confluence를 사용하는 팀과 협업하고 있다면, 형식 차이 때문에 곤란했던 적이 있을 것입니다. Confluence Data Center와 Server는 Markdown과 전혀 다른 자체 위키 마크업 문법을 사용합니다.
문서를 일일이 다시 쓰는 일은 번거롭고 실수하기도 쉽습니다. md-to.com은 Markdown을 Confluence 위키 마크업으로 실시간 변환해 주는 무료 브라우저 기반 변환기를 제공합니다.
이 글에서는 도구가 지원하는 문법, 사용 방법, 그리고 주의할 점을 차례로 살펴봅니다.
어떤 문법을 지원하나요?
변환기는 다음 Markdown 요소를 처리하여 그에 대응하는 Confluence 문법으로 바꿔 줍니다.
텍스트 서식
| Markdown | Confluence 출력 |
|---|---|
**bold** | *bold* |
*italic* | _italic_ |
~~strikethrough~~ | -strikethrough- |
`inline code` | {{inline code}} |
제목
Markdown의 #부터 ######까지는 Confluence의 h1.부터 h6.에 대응합니다.
## Section Title변환 결과:
h2. Section Title링크와 이미지
[Google](https://google.com)은[Google|https://google.com]으로 변환됩니다.는!https://example.com/img.png|alt=alt text!로 변환됩니다.
코드 블록
펜스 코드 블록은 Confluence의 {code} 매크로로 변환되며, 언어 식별자는 그대로 유지됩니다.
```javascript
function greet(name) {
return "Hello, " + name;
}
```변환 결과:
{code:language=javascript}
function greet(name) {
return "Hello, " + name;
}
{code}언어 태그가 없는 코드 블록은 :language= 속성이 생략됩니다.
표
Markdown 표는 헤더 셀에 ||, 데이터 셀에 |를 사용하는 형식으로 변환됩니다.
| Name | Age |
|------|-----|
| Alice | 30 |변환 결과:
||Name||Age||
|Alice|30|셀 안에 들어 있는 파이프 문자는 자동으로 이스케이프됩니다.
목록
- 순서 없는 목록은
*를 사용하며, 중첩 항목은**, 더 깊은 중첩은***와 같이 늘려 갑니다. - 순서 있는 목록은
#를 사용하며, 중첩 항목은##를 사용합니다. - 작업 목록도 변환됩니다.
- [x]는(/)(완료),- [ ]는(x)(미완료)가 됩니다.
인용문
인용문은 {quote}...{quote}로 감싸집니다. Confluence는 중첩 인용을 지원하지 않으므로, 중첩된 인용문은 하나의 {quote} 블록으로 평탄화됩니다.
수평선
Markdown의 ---는 Confluence에서 ----가 됩니다.
사용 방법
- md-to.com/ko/markdown-to-confluence의 왼쪽 편집기에 Markdown을 붙여넣습니다.
- 오른쪽에서 결과를 확인합니다. 입력하는 동안 실시간으로 갱신됩니다.
- 출력 패널 위의 버튼으로 Confluence 위키 마크업을 복사하거나 다운로드합니다.
편집기는 입력창과 출력창의 스크롤을 동기화하므로, 긴 문서도 보던 위치를 놓치지 않고 검토할 수 있습니다.
동작 원리
이 변환기는 Markdown 파서인 markdown-it을 기반으로 만들어졌습니다. markdown-it은 토큰 스트림(추상 구문 트리)을 만들어 냅니다. 취약한 정규식 치환 대신, 도구가 이 토큰 트리를 순회하면서 각 노드를 그에 맞는 Confluence 마크업으로 렌더링합니다.
이 방식에는 다음과 같은 장점이 있습니다.
- 중첩 구조(목록 안의 목록, 목록 항목 안의 코드 블록)를 올바르게 처리합니다.
- 링크, 이미지, 표 셀 안의 특수 문자를 필요한 경우 이스케이프합니다.
- 출력이 markdown-it의 입력 해석 방식과 일관되게 유지되어 예외적인 상황에서 생기는 뜻밖의 문제를 줄여 줍니다.
모든 처리는 브라우저에서 로컬로 이루어지며 어떤 데이터도 서버로 전송되지 않습니다.
호환성과 한계
대상 환경: 출력은 Confluence Data Center / Server 또는 Confluence Cloud의 레거시 마크업 삽입 방식에 맞게 설계되어 있습니다. Confluence Cloud의 새 편집기는 위키 마크업을 직접 받지 않습니다.
알려진 한계:
- 중첩 인용문은 평탄화됩니다. Confluence 위키 마크업은 중첩
{quote}를 지원하지 않습니다. - Markdown 안의 원시 HTML은 무시됩니다(파서에서 HTML이 비활성화되어 있습니다).
- 각주, 정의 목록 같은 markdown-it의 고급 플러그인은 활성화되어 있지 않습니다.
마무리
Markdown 콘텐츠를 Confluence Data Center나 Server로 옮겨야 한다면, 이 변환기가 제목, 서식, 코드 블록, 표, 목록 등의 문법 변환을 대신 처리해 줍니다.
md-to.com/ko/markdown-to-confluence에서 직접 사용해 보세요.
참고 자료: