mastering-confluence

Confluence 管理スキル

種別：プロジェクト | バージョン：2.2.0

Confluence のドキュメントを管理します。ページの Markdown へのダウンロード、画像付きでのアップロード、形式間の変換、図の統合、CQL による検索を行えます。

目次

• 重要な制約
• クイックスタート
• 主な機能
• チェックリスト
• リファレンスドキュメント
• スクリプト

重要な制約

ページのアップロードに MCP を使用しないでください。サイズ制限が適用されます（最大約 10～20KB）。

# Use REST API scripts instead:
python3 scripts/upload_confluence_v2.py document.md --id PAGE_ID

MCP ツールはページの読み取りには問題ありませんが、大きなコンテンツのアップロードには失敗します。

クイックスタート

Markdown を Confluence にアップロードする

# Update existing page
python3 scripts/upload_confluence_v2.py document.md --id 780369923

# Create new page
python3 scripts/upload_confluence_v2.py document.md --space DEV --parent-id 123456

# Preview first (recommended)
python3 scripts/upload_confluence_v2.py document.md --id 780369923 --dry-run

Confluence から Markdown にダウンロードする

# Single page
python3 scripts/download_confluence.py 123456789

# With child pages
python3 scripts/download_confluence.py --download-children 123456789

# Multiple pages
python3 scripts/download_confluence.py 123456 456789 789012

Markdown を Wiki Markup に変換する

python3 scripts/convert_markdown_to_wiki.py input.md output.wiki

Confluence を検索する（MCP 経由）

mcp__atlassian__confluence_search({
  query: 'space = "DEV" AND text ~ "API" AND created >= startOfYear()'
})

主な機能

機能	ツール／スクリプト	リファレンス
画像付きのページをアップロード	upload_confluence_v2.py	アップロードガイド
ページを Markdown にダウンロード	download_confluence.py	ダウンロードガイド
Markdown ↔ Wiki を変換	convert_markdown_to_wiki.py	変換ガイド
ページを検索（CQL）	MCP confluence_search	CQL リファレンス
Wiki Markup の構文	-	Wiki Markup ガイド
Mermaid 図をレンダリング	render_mermaid.py	画像の扱い
Git と Confluence の同期	mark CLI	mark ツールガイド
トラブルシューティング	-	トラブルシューティングガイド

チェックリスト

アップロードチェックリスト

コピーして進捗を記録してください。

Upload Progress:
- [ ] Diagrams converted to PNG/SVG (if Mermaid/PlantUML present)
- [ ] All images use markdown syntax: ![alt](path)
- [ ] No raw Confluence XML in markdown
- [ ] All image files verified to exist
- [ ] Dry-run tested: `--dry-run`
- [ ] Upload executed with v2 script (not MCP)
- [ ] Page URL verified accessible

ダウンロードチェックリスト

Download Progress:
- [ ] Page ID obtained from Confluence URL
- [ ] Credentials configured in .env file
- [ ] Output directory specified
- [ ] --download-children flag set (if hierarchy needed)
- [ ] Download completed successfully
- [ ] Attachments downloaded to {Page}_attachments/
- [ ] Frontmatter contains correct metadata

画像の扱い

標準的なワークフロー：

1. 図を変換する（Mermaid／PlantUML の場合）：

   # Mermaid
   mmdc -i diagram.mmd -o diagram.png -b transparent
   
   # PlantUML
   plantuml diagram.puml -tpng
   

2. Markdown で参照する（必ず Markdown 構文を使用）：

   ![Architecture Diagram](./diagrams/architecture.png)
   

3. アップロードする（スクリプトが添付ファイルを処理します）：

   python3 scripts/upload_confluence_v2.py document.md --id PAGE_ID
   

よくある間違い：

• 生の XML を使用する：<ac:image>... — HTML エスケープされ、テキストとして表示されます
• アップロードに MCP を使用する — サイズ制限により失敗します
• 図の変換を忘れる — コードブロックはレンダリングされません

リファレンスドキュメント

ドキュメント	目的
upload_guide.md	アップロードの完全なワークフロー
download_guide.md	ダウンロードの完全なワークフロー
wiki_markup_guide.md	Wiki Markup 構文リファレンス
conversion_guide.md	Markdown ↔ Wiki Markup の変換規則
image_handling_best_practices.md	図と画像
troubleshooting_guide.md	よくあるエラーと解決方法
mark_tool_guide.md	Git と Confluence の同期
confluence_storage_format.md	API のストレージ形式
cql_reference.md	CQL クエリ構文
atlassian_mcp_tools.md	MCP ツールのリファレンス

スクリプト

スクリプト	目的
upload_confluence_v2.py	画像付きで Markdown をアップロード（サイズ制限なし）
download_confluence.py	添付ファイルとともにページを Markdown にダウンロード
convert_markdown_to_wiki.py	Markdown を Wiki Markup に変換
render_mermaid.py	Mermaid 図を PNG／SVG にレンダリング
generate_mark_metadata.py	mark CLI のメタデータヘッダーを生成
confluence_auth.py	認証ユーティリティを共有

依存関係

pip install atlassian-python-api md2cf python-dotenv PyYAML mistune \
            requests markdownify beautifulsoup4

前提条件

必須

• Atlassian MCP サーバー（mcp__atlassian）と Confluence の認証情報

任意

• mark CLI：Git と Confluence の同期

  brew install kovetskiy/mark/mark
  

• Mermaid CLI：図のレンダリング

  npm install -g @mermaid-js/mermaid-cli
  

使用しない場合

• ページを単純に読み取る場合 → MCP を直接使用してください
• 画像や図がなく、コンテンツが少ない場合 → MCP で対応できる可能性があります
• Jira の課題 → Jira 専用ツールを使用してください

---

バージョン: 2.2.0 | 最終更新日: 2025-12-28