markdown-confluence CLIでMarkdownをConfluenceに同期する運用

開発に関連する決定事項(ADRなど)をGitリポジトリ内のdocsディレクトリにMarkdownで記載して管理するスタイルをとってきた。

ただ、非開発者でも経緯などを把握できた方がいいことを考えると、リポジトリに置いておくだけでは不十分だと考えて、代替ソリューションを探していてたどり着いたのが@markdown-confluence/cliだ。

検討していた/実施してみた代替手段

AstroなどでS3に配置・公開

フロントエンドがメイン領域の自身が運用する分にはなんの問題もないが、フロントエンド経験が乏しいとメンテナンスが継続できないと判断してやめた。

上記に関連するが、継続的にバージョンを上げていくなどメンテナンスする意識がないとすぐに陳腐化する。

最初からConfluenceに書く

手元のリポジトリでサクッと見ることができなくなる
コンテキストがリポジトリとConfluenceに分散するので移動が煩わしく感じる
単純にConfluenceのエディタが好きになれない

@markdown-confluence/cliで同期する

基本的な記法を網羅している
画像などもアップロードできる
フォルダ構造を維持したままアップロードできる
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管理された信頼できるソースを維持できる。両者のニーズを満たす良い選択肢だ。