markdown-confluence CLI로 Markdown을 Confluence에 동기화하는 운영

개발 관련 의사결정, 예를 들어 ADR 같은 문서는 Git 저장소의 docs 디렉터리에 Markdown으로 적어 관리해 왔다.

하지만 비개발자도 경위와 문맥을 파악해야 한다고 생각하면, 저장소 안에만 두는 것으로는 부족하다. 대안 솔루션을 찾다가 도달한 것이 @markdown-confluence/cli였다.

검토했거나 실제로 시도해 본 대안

Astro 같은 도구로 S3에 배포해서 공개하기

프런트엔드가 주 영역인 나에게는 큰 문제가 없지만, 프런트엔드 경험이 적은 사람이 이걸 계속 유지보수하기는 어렵다고 판단해 포기했다.

이와 관련해서, 버전 업과 유지보수를 계속할 사람이 없으면 이런 방식은 금방 낡아진다.

처음부터 Confluence에 직접 작성하기

로컬 저장소에서 문서를 빠르게 확인할 수 없게 된다
저장소와 Confluence 사이로 문맥이 흩어져 이동이 번거롭다
단순히 Confluence 에디터를 별로 좋아하지 않는다

`@markdown-confluence/cli`로 동기화하기

기본적인 Markdown 문법을 폭넓게 지원한다
이미지도 업로드할 수 있다
폴더 구조를 유지한 채 업로드할 수 있다
Obsidian용 플러그인도 있는 것 같아서 Obsidian 사용자에게도 잘 맞아 보인다

필요한 것

동기화 대상이 될 폴더 페이지 ID
- 여기서 지정한 페이지 아래로 Markdown이 동기화된다
ATLASSIAN_API_TOKEN
자신의 Confluence 베이스 URL, 예를 들면 https://example.atlassian.net

디렉터리 구조

.obsidian 디렉터리가 있으면 배포에서 제외되지만, 점으로 시작하는 다른 디렉터리나 Markdown 파일은 그대로 배포되므로 주의해야 한다.

.
└── root/
    ├── docs/
    │   ├── .hidden-dir
    │   ├── foo.md
    │   └── bar/
    │       └── baz.md
    ├── src
    ├── .markdown-confluence.json
    ├── package.json
    └── README.md

설정

설정은 .markdown-confluence.json에서 관리한다.

{
  "confluenceBaseUrl": "https://example.atlassian.net",
  "confluenceParentId": "12345678",
  "atlassianUserName": "username@example.com",
  "folderToPublish": "path/to/folder",
  "firstHeadingPageTitle": true
}

confluenceBaseUrl: 배포 대상 Confluence의 베이스 URL
confluenceParentId: 배포 대상 Confluence의 부모 페이지 ID
atlassianUserName: Atlassian 계정 사용자 이름
folderToPublish: 배포할 폴더 경로, 기본값은 .(루트)
firstHeadingPageTitle: # Heading1을 페이지 제목으로 쓸지 여부

배포 / 업로드

export ATLASSIAN_API_TOKEN=""

npx @markdown-confluence/cli

작성 방식과 공개 동작

초안 / 비공개

---
connie-publish: false
---

# this is draft

이미 공개된 파일을 삭제하면 어떻게 될까?

자동으로 삭제되지는 않으므로, Confluence 쪽에서 직접 수동으로 삭제해야 한다.

WikiLink를 어떻게 표현할까

[[markdown 파일명]] 형식으로 적으면 링크로 변환된다. 확장자는 붙이지 않는다.

Obsidian을 쓰고 있다면 대부분 자연스럽게 사용할 수 있다.

# title

- [[markdown-filename]]
- [[markdown-filename|Alias]]
- [[markdown-filename#Heading]]

링크

정리

@markdown-confluence/cli를 쓰면 Git 저장소의 Markdown 문서를 Confluence에 동기화하면서도, 개발자는 계속 익숙한 에디터에서 Markdown을 편집할 수 있다.

비개발자는 Confluence에서 읽을 수 있고, 개발자는 Git으로 관리되는 신뢰할 수 있는 원본을 유지할 수 있다. 양쪽 요구를 모두 만족시키는 좋은 절충안이다.