mark cli 를 이용하여 Confluence 에 md 파일 import 하기

개발 작업을 하다보면 md 파일을 다룰 때가 많다. 최근엔 AI를 자주 활용하다 보니 API 문서 등을 AI를 이용해 생성하게 되는데 이 때 md 파일을 만들어지는 데 이것을 바로 Confluence 에 import 하는 것은 자체 기능을 이용해서는 불가능하다. doc 등으로 변환해서 진행해야 하는데, 그건 번거로운 일이라 피하고 싶다.

md 파일을 바로 import 할 수.. 라고 해야할지 아니면 업로드라고 해야할지.. 굳이 따지만 Confluence 를 이용해 md 파일의 컨텐츠를 바로 Confluence 에 등록하는 것이라 하면 될 것 같다.

mark cli : https://github.com/kovetskiy/mark

mark cli 설치는 brew 를 이용하면 쉽게 설치할 수 있다.

brew install mark

설치가 끝났다면 이제 Confluence 에서 API 토큰을 생성해야 한다. 토큰은 아래 주소로 접속해서 생성할 수 있다.

https://id.atlassian.com/manage-profile/security/api-tokens

토큰을 생성했다면 ~/.confg/mark.toml 파일에 아래와 같이 설정한다.

username = "your-email"
password = "password-or-api-key-for-confluence-cloud"
# If you are using Confluence Cloud add the /wiki suffix to base_url
base-url = "http://confluence.local"
title-from-h1 = true
drop-h1 = true

password 부분에 생성한 API 토큰을 적어주면 된다. 기본적으로 해당 mark 명령 실행 때 위의 설정 파일을 이용하게 되는데, 특정 버전의 문제인지 설정 파일을 찾지 못하는 오류 또는 버그가 있는 듯 하다. -c ~/.config/mark.toml 처럼 설정 파일을 직접 지정해 주면 된다.

md 파일 최 상단에 아래와 같은 형식으로 Confluence 페이지가 생성될 tree 구조를 지정해줄 수 있다.

<!-- Space: <space key> -->
<!-- Parent: <parent 1> -->
<!-- Parent: <parent 2> -->
<!-- Title: <title> -->

<page contents>

Parent 항목은 여러 개 사용할 수 있고 tree 구조에 맞게 지정해 주면 된다. 설정이 모두 끝났다면 mark 명령을 통해 Confluence 에 페이지를 생성하면 된다.

mark -f API.md -c ~/.config/mark.toml --dry-run

--dry-run 은 실제 등록은 하지않고 정상 작동하는지 테스트해볼 때 사용하는 것이다. 이상이 없다면 해당 옵션을 빼고 실행하면 페이지가 설정된 위치에 생성된다.