Jira の説明を整形する: Markdown から ADF へ

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

Jira の Markdown、手短な答え

説明フィールドに Jira の Markdown を入力し、# の見出しや - bullet のリストが表示されることを期待すると、残念な結果になります。Jira Cloud は説明もコメントも Markdown としては保存しないからです。v3 REST API 上では、Jira はすべてのリッチテキストを ADF（Atlassian Document Format）、つまり型付きノードの JSON ツリーとして表現します。素の Markdown を貼り付けると、ハッシュ記号やアスタリスクがそのまま文中に残ります。

atlassian-cli はその差を埋めます。jira issue create の --description や、コメントの --body に Markdown を渡すと、CLI は CommonMark パーサーで Markdown を解析し、Jira に届く前に ADF へ変換します。見出し、太字、斜体、リンク、箇条書きと番号付きリスト、インラインコード、フェンス付きコードブロックは、いずれも表示される課題にそのまま残ります。書くのは Markdown、Jira が見るのはネイティブな書式です。

ADF とは何か、なぜ Jira が素の Markdown を受け付けないのか

ADF は、Jira Cloud と Confluence Cloud が v3 REST API で使う JSON ベースのリッチテキスト形式です。ドキュメントは、type が "doc"、version が 1、そして型付きブロックノードの content 配列を持つオブジェクトです。インラインテキストはそれらのブロックの中に置かれ、マークで装飾されます。太字の単語1つは strong マークを持つ text ノードになり、リンクは link マークと href 属性を持つ text ノードになります。

次に示すのは、2行の Markdown の説明がコンパイルされた ADF です。先に書く Markdown、続いて Jira が実際に保存する JSON を示します。

# Markdown you write
## Deploy checklist
- Reserve a **static IP**
- Enable Cloud NAT

# ADF that atlassian-cli sends to Jira
{
  "type": "doc",
  "version": 1,
  "content": [
    { "type": "heading", "attrs": { "level": 2 },
      "content": [{ "type": "text", "text": "Deploy checklist" }] },
    { "type": "bulletList", "content": [
      { "type": "listItem", "content": [
        { "type": "paragraph", "content": [
          { "type": "text", "text": "Reserve a " },
          { "type": "text", "text": "static IP",
            "marks": [{ "type": "strong" }] }
        ] } ] },
      { "type": "listItem", "content": [
        { "type": "paragraph", "content": [
          { "type": "text", "text": "Enable Cloud NAT" }
        ] } ] }
    ] }
  ]
}

課題ごとにこの JSON を手で書くのは、まさに CLI が肩代わりすべき作業です。Jira が Markdown を「受け付けない」のは、厳格さそのものを目的にしているからではありません。API が話す言語が ADF であり、手書きの ADF は冗長で間違えやすいというだけです（ノードには厳密な入れ子のルールがあります）。Markdown から ADF への変換をプログラムに任せるのが確実な方法です。

Markdown で整形済みの説明を書く

jira issue create の --description フラグは Markdown をそのまま受け付けます。1文を超える内容なら、本文を .md ファイルに置き、その中身をフラグへ展開してください。改行の扱いはエディターに任せられます。

# Author the description in a real markdown file, then create the issue
atlassian-cli jira issue create \
  --project DEV \
  --issue-type Task \
  --summary "Ship the auth service" \
  --description "$(cat spec.md)"

構造を持つ説明を手早くインラインで書くには、bash の ANSI-C クォート（$'...'）を使い、\n を実際の改行にします。通常のダブルクォート文字列では \n は展開されないため、複数行の Markdown を渡すには $'...' かファイルを使うのが正解です。

# Inline multi-line markdown with $'...' so \n is a newline
atlassian-cli jira issue create \
  --project DEV \
  --issue-type Bug \
  --summary "Login 500s under load" \
  --description $'## Steps to reproduce\n1. Hit /login 200x\n2. Watch the 500s\n\n**Impact:** blocks release'

同じフラグは jira issue update にもあるため、Web UI に触れずに後から説明を書き換えられます。

# Replace an existing description with new markdown
atlassian-cli jira issue update DEV-123 \
  --description "$(cat updated-spec.md)"

Markdown 記法を含まないプレーンテキストもそのまま使え、単一の段落として扱われます。値が Markdown に「見えるかどうか」を気にする必要はありません。この後方互換の挙動により、プレーンな文字列を渡していたスクリプトは変更なしで動き続けます。

クォートに関する細かい点が2つ、時間を節約してくれます。1つめは、通常のダブルクォート文字列の中のバッククォートは bash でコマンド置換を引き起こすため、`--dry-run` のようなインラインコードは、バッククォートがそのまま残る $'...' かファイルの中に置くのが安全だという点です。2つめは、テンプレートから説明を組み立てる場合、改行を手でエスケープするのではなく、まず Markdown ファイルを生成して "$(cat file.md)" で渡すという点です。カスタムフィールドは同じコマンドの中で --field 'customfield_10010={"value":"Internal"}' により設定できるため、1回の create 呼び出しで整形済みの本文と構造化されたメタデータをまとめて送れます。

どの Markdown がどの ADF ノードに対応するか

コンバーターは CommonMark に従い、各構文を対応する ADF の要素へマッピングします。この表は現時点で対応している範囲をまとめたものです。

フェンス付きコードブロックは言語ヒントを保持するため、```rust は language 属性を持つ codeBlock になり、Jira が適切なハイライトを適用します。1以外の数字で始まる番号付きリストは order 属性を持つため、3. third は3から始まる表示になります。

Markdown で Jira のコメントを整形する

コメントも同じ Markdown から ADF への経路を通ります。jira issue comments add の --body フラグは Markdown を受け付けるため、デプロイのメモ、レビューのチェックリストなど、構造があると読みやすい内容に向いています。

# Add a formatted comment
atlassian-cli jira issue comments add DEV-123 \
  --body $'**Deploying now.**\n\n- Ran migrations\n- Cleared cache\n\nLogs: [dashboard](https://logs.example.com)'

# Edit an existing comment by its id
atlassian-cli jira issue comments update 10500 \
  --body "$(cat postmortem.md)"

# List comments, showing the full body instead of a preview
atlassian-cli jira issue comments list DEV-123 --full

説明とコメントは同じコンバーターで処理されるため、一度覚えた書式のルールがどこでも通用します。コメント専用の記法を別に覚える必要はありません。

課題を Markdown として読み戻す

変換は双方向に動きます。--format markdown を付けて課題を読み出すと、CLI は保存されている ADF をたどって Markdown に戻します。主要フィールドの要約表に続いて ## Description セクションが出力されます。課題の内容をファイル、ドキュメントページ、プルリクエストの本文へパイプするのに最適です。

# Render an issue as markdown
atlassian-cli jira issue get DEV-123 --format markdown

# Save the rendered issue for a PR description or a doc
atlassian-cli jira issue get DEV-123 --format markdown > ticket.md

markdown は、他のグローバルな出力形式と並ぶ選択肢です。table（既定）、json、csv、yaml、quiet があります。生の ADF ツリーを確認したり変換したりしたいときは json を、どこかに貼り付けられる人間向けの形式が欲しいときは markdown を使ってください。

往復変換は、説明が意図どおりに表示されたかを確かめるいちばん手早い方法でもあります。create や update のあとに --format markdown で課題を読み戻して構造を目視するか、json 形式を jq にパイプして Jira が保存した ADF ノードそのものを確認してください。書き込み時と読み出し時で同じ変換ロジックが動くため、返ってくる内容は渡した内容をそのまま反映します。

コンバーターが処理してくれる構造ルール

ADF は Markdown よりも入れ子に厳格です。「すべてを段落で包む」ような素朴な変換では、Jira が受け付けない、あるいは表示が崩れるドキュメントができてしまいます。atlassian-cli は扱いにくいケースを引き受けるため、Markdown が完璧である必要はありません。

• リスト項目や引用の中の見出しは ADF として不正なため、削除されるのではなく通常の段落に格下げされます。
• 入れ子の引用や、リスト項目の中の引用は平坦化され、内容は親に付け直されるため、失われるものはありません。
• 他の強調と組み合わさったインラインコードは正規化されます。ADF で code マークと共存できるのは link だけなので、斜体になったインラインコードはコードを保ち、衝突するマークを落とします。
• 空の入力でも妥当なドキュメント（空の段落1つ）が生成され、リスト項目には ADF が要求する少なくとも1つのブロック子要素が必ず与えられます。

結果として、書くのはふつうの Markdown で、ツールが Jira に一度で受け入れられる ADF を生成します。ADF のスキーマを暗記したり、API からの 400 応答をデバッグしたりする必要はありません。

Atlassian 公式の acli との違い

atlassian-cli は MIT ライセンスの、コミュニティによる独立したオープンソースプロジェクトです。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援、保守のいずれも受けていません。Atlassian が提供する公式 CLI（acli）でもありません。ベンダーによる一次サポートが必要であれば公式の acli を使ってください。Jira、Confluence、Bitbucket、Jira Service Management をカバーし、ここで説明した Markdown から ADF への変換を Jira コマンドに組み込んだ単一の無料 Rust バイナリが欲しい場合は atlassian-cli を選んでください。

Jira のコマンドとフラグの全一覧はコマンドリファレンスを、作業別のガイドは Jira CLI ハブをご覧ください。API 全般での自動化に取り組んでいる場合は、コマンドラインからの Jira API と Jira のタスク管理の記事が、本記事の続きにあたります。

よくある質問

関連リソース