Markdown を Confluence のページに変換する

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

2 つのステップ

Markdown を Confluence のページに変換するには、2 つの異なる作業を行います。まず Markdown を Confluence のストレージ形式（Confluence の XHTML ベースのマークアップ）に変換し、次にそのマークアップをページとして公開します。Confluence は生の Markdown を保存しないため、規模が大きくなっても使える「Markdown をインポート」ボタンのようなものは存在しません。代わりに pandoc のようなツールで一度変換し、その結果を API に渡します。

atlassian-cli は 2 番目のステップを担います。confluence page create と confluence page update は、変換済みの HTML ファイルを指す --body を受け取るため、ページの公開はスクリプト 1 行で済みます。コンバーターと CLI をつなげば、Git リポジトリ内の Markdown ファイルが、ソースが変わるたびに再生成できる Confluence のページになります。

Atlassian 自身の CLI との違い: atlassian-cli はコミュニティによる独立したオープンソースプロジェクトです。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援、保守のいずれも受けておらず、Atlassian が提供する公式 CLI（acli）でもありません。ベンダーによる公式サポートが必要な場合は acli を使ってください。Jira、Confluence、Bitbucket、Jira Service Management を横断し、どこでも同じフラグで扱える無料の単一 Rust バイナリが欲しい場合は atlassian-cli を使ってください。

Confluence のストレージ形式とは

変換を始める前に、何に変換するのかを知っておくと役立ちます。Confluence のストレージ形式は、Confluence がページの内容をディスク上と REST API 経由で保持するために使う XHTML ベースのマークアップです。大部分は普通の HTML に見えます。段落は <p>、見出しは <h1> から <h6>、リストは <ul> と <ol>、表は <table> です。これらのタグは Markdown コンバーターの出力とほぼそのまま対応するので、このパイプラインが成立します。

素の HTML ではない部分が、Confluence 独自の機能です。シンタックスハイライト付きのコードブロック、情報パネルや警告パネル、ページの取り込み、目次、ステータスラベルなどです。これらは ac: と ri: の名前空間を使ったマクロとして表現されます。たとえばコードブロックは、単なる <pre> タグではなく構造化マクロです。

<!-- Confluence storage format: a code macro -->
<ac:structured-macro ac:name="code">
  <ac:parameter ac:name="language">bash</ac:parameter>
  <ac:plain-text-body><![CDATA[cargo build --release]]></ac:plain-text-body>
</ac:structured-macro>

これを手で書くことはめったにありません。重要なのは、「Markdown を Confluence のページに変換する」とは、このストレージ形式の XHTML を作ることだという点です。コンバーターの出力がこれに近いほど、あとの手直しは少なくなります。

Markdown をストレージ形式に変換する

もっとも信頼できるオープンソースの Markdown コンバーターは pandoc です。html 出力を指定すると、Confluence のストレージ形式がそのまま受け付けるマークアップを生成します。見出し、段落、フェンス付きコード、リンク、画像、そしてほとんどの表がきれいに変換されます。

# Convert a single markdown file to Confluence-ready HTML
pandoc -f markdown -t html release-notes.md > release-notes.html

変換のステップはこれだけです。最初の一歩としては、この出力のまま公開しても十分です。Confluence 上での読みやすさを高める任意の調整が 2 つあります。<h1> に上マージンを付ける小さな修正と、インラインの <code> にクラスを付けて Confluence のスタイルを適用することです。

# Convert with light cleanup for Confluence storage format
pandoc -f markdown -t html release-notes.md \
  | sed 's/<h1>/<h1 style="margin-top: 20px;">/g' \
  | sed 's/<code>/<code class="code-inline">/g' \
  > release-notes.html

以降の処理では、release-notes.html をページ本文として扱います。ドキュメントのディレクトリ全体に対して、走査・変換・公開のループをまとめて組みたい場合は、Confluence Markdown 同期のランブックが、この変換をドライラン対応と自動ラベル付けを備えたすぐ使えるスクリプトにまとめています。

CLI からページを公開する

ストレージ形式の HTML ができたら、公開はコマンド 1 つです。--body フラグはファイルパスを受け取るので、変換したファイルをそのまま渡します。

# Create a new Confluence page from the converted markdown
atlassian-cli confluence page create \
  --space DOCS \
  --title "Release Notes 1.0" \
  --body release-notes.html

短い一回限りのメモであれば、ファイルを使わずに --body へ直接ストレージ形式を渡せます。

# Inline body for a short page
atlassian-cli confluence page create \
  --space DOCS \
  --title "Deploy Log" \
  --body "<p>Shipped the <strong>1.0</strong> release.</p>"

新しいページを既存の親ページの下に置くには、親ページの ID を --parent に指定します。適切な位置に置けるよう、まずスペース内のページを一覧して ID を確認します。

atlassian-cli confluence page list --space DOCS --limit 25
atlassian-cli confluence page create \
  --space DOCS \
  --title "Architecture Overview" \
  --parent 3302031761 \
  --body architecture.html

重複を作らずにその場で更新する

page create を 2 回実行すると、ページが 2 つできます。コミットのたびに再生成されるドキュメントで必要なのはアップサートです。初回はページを作成し、それ以降の実行では本文を上書きします。コツは、タイトルからページ ID を調べ、その ID を指定して更新することです。

# Find the page id by title with a CQL search
PAGE_ID=$(atlassian-cli confluence search cql \
  "space = DOCS AND title = \"Release Notes 1.0\"" \
  --format json | jq -r '.results[0].content.id // empty')

# Update in place if it exists, otherwise create it
if [ -n "$PAGE_ID" ]; then
  atlassian-cli confluence page update "$PAGE_ID" \
    --title "Release Notes 1.0" \
    --body release-notes.html
else
  atlassian-cli confluence page create \
    --space DOCS \
    --title "Release Notes 1.0" \
    --body release-notes.html
fi

ID を指定した更新は、重複を作らずに本文を上書きし、ページバージョンを 1 つ上げます。pandoc は入力が変わらなければ同じストレージ形式を出力するため、同じソースファイルで再実行しても実質的に何も変わりません。タイトルも本文も同じで、バージョンがきれいに 1 つ上がるだけです。この冪等性があるからこそ、パイプラインを CI に組み込んだまま任せておけます。

同期したページにラベルを付けておくと、あとから探したり監査したりしやすくなります。

atlassian-cli confluence page add-label "$PAGE_ID" auto-synced

コードブロック、表、マクロ

ほとんどの Markdown はきれいに変換されますが、広く展開する前に確認しておきたい構文が 3 つあります。Markdown を Confluence のページに変換したときに、よくあるケースがどう振る舞うかは次のとおりです。

実務上の原則はこうです。Markdown をある程度標準的に保てば、変換で困ることはありません。シンタックスハイライト付きコードのように Confluence 独自の描画に依存するページでは、pandoc の <pre> 出力を code マクロへ後処理するか、素の整形済みブロックで妥協することになります。スペース全体にパイプラインを流す前に、代表的なページを必ずプレビューしてください。相対パスで参照しているローカル画像は明示的に扱う価値があります。confluence attachment upload でアップロードしておけば、公開したページのリンクが切れずに済みます。

Markdown へ戻す往復変換

変換は双方向に機能します。これは、誰かが Confluence の Web エディターでページを編集し、その変更を Git に戻したいときに効いてきます。すべてのコマンドが --format フラグを受け付け、markdown は対応する出力形式なので、コマンド 1 つでページを Markdown として取り出せます。

# Export a Confluence page back to a markdown file
atlassian-cli confluence page get 12345 --format markdown > release-notes.md

これでループが閉じます。読者向けには Markdown を Confluence へ公開し、バージョン管理を正とするために書き戻す、という形です。スペース全体のエクスポートや出力の整形を含む逆方向の詳しい手順は、Confluence を Markdown にエクスポートをご覧ください。手作業ではなくマージのたびに自動で走らせたい場合は、Confluence での docs-as-code のガイドが CI への組み込みを解説しています。

よくある質問

関連リソース