CLI で Confluence のページを Markdown にエクスポートする

atlassian-cli はコミュニティによる独立したオープンソースプロジェクトです。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援のいずれも受けておらず、Atlassian が提供する公式 CLI（acli）でもありません。製品名は互換性を示す目的でのみ使用しています。

コマンドラインから Confluence を Markdown にエクスポートするには、atlassian-cli confluence page get <id> --format markdown を実行し、出力をファイルにリダイレクトします。markdown は組み込みの出力形式なので、プラグインもコピーと貼り付けも PDF からのテキスト整形も不要で、1 ページがそのままきれいな .md ファイルになります。この 1 つのコマンドをスペース全体に広げれば、Confluence のすべてのページを、Git にコミットできるバージョン管理可能なテキストとして持てます。

この記事はエクスポートの方向、つまり Confluence からコンテンツを取り出して、コードの隣に置く Markdown ファイルにする話です。逆方向（Markdown を書いて Confluence に公開する）については、姉妹記事の Markdown から Confluence へと、より広い Confluence での docs-as-code のワークフローをご覧ください。

Confluence を Markdown にエクスポートする 1 行コマンド

atlassian-cli のすべてのコマンドはグローバルな --format フラグを受け付け、markdown はその値のひとつです（ほかに table、json、csv、yaml、quiet があります）。Confluence のページであれば、ページ本文を Markdown として整形し、標準出力に表示します。

# Export a single page to a Markdown file
atlassian-cli confluence page get 12345 --format markdown > architecture.md

出力は普通の Markdown です。# の見出し、箇条書きと番号付きリスト、リンク、表、フェンス付きコードブロックが含まれます。プレーンテキストなので、任意のエディターで開き、IDE でプレビューし、別のツールへそのままパイプできます。Confluence 固有の要素を取り除く必要はありません。読んで差分を取れるファイルが欲しい場合に、組み込みの PDF や Word のエクスポートより Markdown を選ぶ理由がここにあります。

複数の Atlassian サイトを扱っている場合は --profile を付けて、正しいインスタンスに対してエクスポートを実行します。

# Export from a named profile
atlassian-cli confluence page get 12345 --format markdown --profile prod > architecture.md

ページ ID を調べる

page get に必要なのは数値のページ ID だけです。手元にない場合は、まずスペース内のページを一覧するか、タイトルで検索します。

# List pages in a space (id shows in the output)
atlassian-cli confluence page list --space DEV --limit 50

# Or search by title within a space
atlassian-cli confluence search in-space DEV "architecture"

次のステップをスクリプト化するつもりなら、機械可読な出力を選びます。JSON を指定すると各ページの id と title が得られ、jq で切り出せます。

# Get just the page ids in a space
atlassian-cli confluence page list --space DEV --format json | jq -r '.[].id'

スペース全体を Markdown にエクスポートする

1 ページはウォームアップです。「Confluence を Markdown にエクスポートしたい」という要望の実体は、たいてい「スペース全体をコミットできるファイルとして欲しい」です。page list --format json と、ページごとに page get --format markdown を呼ぶシェルループを組み合わせ、各ファイルにタイトル由来の名前を付けます。

#!/usr/bin/env bash
# Export every page in a Confluence space to individual Markdown files
set -euo pipefail

SPACE="DEV"
OUT="docs/confluence"
mkdir -p "$OUT"

atlassian-cli confluence page list --space "$SPACE" --format json \
  | jq -r '.[] | [.id, .title] | @tsv' \
  | while IFS=$'\t' read -r id title; do
      # Turn the page title into a filesystem-safe slug
      slug=$(echo "$title" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-//;s/-$//')
      echo "Exporting $id -> $OUT/$slug.md"
      atlassian-cli confluence page get "$id" --format markdown > "$OUT/$slug.md"
    done

一度実行すると、docs/confluence/ にページごとの Markdown ファイルが並びます。getting-started.md、architecture.md、runbook-oncall.md といった具合です。このループはバージョン管理の観点で冪等です。内容が変わっていないページを再エクスポートしても同じ Markdown が生成されるため、Confluence 側で実際に変更がない限り、2 回目の実行後も作業ツリーはきれいなままです。

エクスポート結果をバージョン管理する

スペースが Markdown としてフォルダーに置かれれば、あとはほかのソースディレクトリと同じように扱えます。コミットすれば、Confluence のある時点のスナップショットが Git の履歴に残ります。

# Snapshot the exported space in Git
git add docs/confluence
git commit -m "docs: snapshot Confluence space DEV as markdown"

Markdown エクスポートの価値が出るのはここです。PDF や Word のダウンロードは git diff にとって不透明ですが、Markdown ファイルは行単位で変化します。誰かがページを編集したあとにエクスポートし直せば、どの段落が動き、どのリンクが追加され、どのセクションが削除されたかが差分に表れます。レビュアーはその変更にプルリクエスト上でコメントできます。検索でき、blame でき、元に戻せるドキュメントの記録が手に入ります。これはあらゆる docs-as-code の実践の土台です。

チームが Confluence を Markdown として Git に取り込む実務上の理由は次のとおりです。

• 移行。Confluence をやめる場合や、スペースを静的サイトジェネレーターへ移す場合、コンテンツがすでに Markdown であれば作業はずっと楽になります。
• オフラインのアーカイブ。コミットしたスナップショットは、あとからスペースが削除・アーカイブされても残ります。
• レビューのワークフロー。ドキュメントの編集を、コードと同じプルリクエストのプロセスに乗せられます。
• 検索と grep。.md ファイルのフォルダーに対する grep は、Confluence の検索ボックスより速く正確です。

Confluence エクスポート方法の比較

Confluence には、コンテンツを取り出す方法がいくつかあります。これらは置き換え可能ではありません。人が読めて差分を取れるものが欲しいのか、完全な構造化バックアップが欲しいのかで、選ぶべきものが変わります。

docs-as-code のワークフローで欲しいのは 1 行目です。2 行目の JSON エクスポートは競合ではなく補完で、Markdown の本文が持たないメタデータまで忠実に残したいときに使います。

添付ファイルと完全なバックアップ

--format markdown の出力は、ページの本文をテキストにしたものです。バイナリの添付ファイルや埋め込み画像は Confluence 内で別に保存されているため、Markdown ファイルには埋め込まれません。テキストとあわせて必要な場合は、添付ファイル用のコマンドで取得します。

# List and download a page's attachments
atlassian-cli confluence attachment list 12345
atlassian-cli confluence attachment download --output ./diagram.png 11111

読めるテキストではなく、復元できる完全なスナップショットが目的であれば、Markdown と並べて構造化された一括エクスポートを実行します。フラットな Markdown 本文では落ちてしまうラベル、バージョン、メタデータまで取得できます。

# Full structured snapshot of a whole space
atlassian-cli confluence bulk export --cql "space = DEV" \
  --output confluence-DEV-backup.json \
  --format json

よくあるのは両方を保持するやり方です。人が読んで差分を見るための Markdown ファイルと、災害復旧のためのタイムスタンプ付き JSON エクスポートです。Confluence バックアップのランブックでは、これを保持期間付きのスケジュールジョブにまとめています。

自動化と双方向の同期

エクスポートのループは CI や cron ジョブによく合います。定期実行しておけば、Confluence の Git ミラーが 1 日以上ずれることはなくなり、コミット履歴が「誰がいつ何を変えたか」の監査ログにもなります。変更のないページはバイト単位で同じ Markdown を生成するため、スケジュール実行は実際に変更があったときだけコミットを作ります。

エクスポートは往復の片道です。docs-as-code を採用したチームは、やがて Git 上の Markdown を編集し、それを Confluence へ戻して、技術者以外の読者にも wiki のビューを提供したくなります。その逆方向のパイプライン（Markdown を Confluence のストレージ形式に変換し、ページを作成または更新する）は、Confluence Markdown 同期のランブックで解説しています。このランブックも、確認のためにページを取り出す際に同じ --format markdown フラグを使います。この 2 つを組み合わせれば、Git と Confluence のどちらを正とするかを選び、もう一方を自動で追随させられます。

ここで使った Confluence のサブコマンドとフラグの一覧はコマンドリファレンスを、ページ、スペース、検索、一括操作の概要は Confluence CLI ハブをご覧ください。

よくある質問

関連リソース