Confluenceの「PDF出力」で絶望しないために。大規模ドキュメントを美しく魅せる極限のスタイリング術
こんにちは。アジャイルコーチとして数多くの現場を見てきましたが、いまだに「ConfluenceのPDF出力が汚いから」という理由で、わざわざWordにコピペして手動でレイアウト調整しているチームに出会います。
その作業、今すぐやめましょう。
Confluenceは本来、情報を「流動的」に扱うためのツールです。しかし、契約や納品、あるいはステークホルダーへの報告で「紙（PDF）」という形式を求められる瞬間は必ず訪れます。このとき、標準設定のまま出力して崩れたレイアウトを見て溜息をつくのは、プロのエンジニアの仕事ではありません。
今日は、Confluenceの標準機能を限界までハックし、大規模な仕様書すらも美しいドキュメントに変貌させる「CSSによるPDFスタイリングの真髄」を伝授します。
—
1. なぜ標準のPDF出力は「崩れる」のか？
Confluenceの標準エクスポート機能は、ブラウザ上のHTMLを印刷用PDFに変換します。しかし、ブラウザのレンダリングエンジンと印刷エンジンは別物です。特に「大きな表」「複雑な画像配置」「ネストされたリスト」は、CSSで明示的に印刷用の指示を出さない限り、容赦なく崩れます。
私たちがやるべきことは一つ。「ブラウザ用CSS」とは別に、「印刷専用のCSS（PDFスタイルシート）」を徹底的に定義することです。
—
2. 実践：PDFスタイルシートの神セットアップ
まずは、最も重要な「PDFスタイルシート」の設定場所を確認しましょう。
- 場所: `スペースツール` > `ルック＆フィール` > `PDFスタイルシート`
ここに以下のCSSを注入するだけで、ドキュメントの品格が劇的に変わります。
/ PDFスタイルの核となる設定 /
@page {
size: A4;
margin: 20mm;
}
/ 見出しの余白を制御し、ページまたぎを防止 /
h1 { page-break-before: always; font-size: 24pt; color: #2c3e50; }
h2 { page-break-after: avoid; font-size: 18pt; margin-top: 20px; }
/ 大規模な表の崩れを防ぐ魔法のコード /
table {
table-layout: fixed; / 列幅を固定して崩壊を防ぐ /
width: 100% !important;
word-wrap: break-word; / 長い文字列を強制改行 /
border-collapse: collapse;
}
/ 印刷時に不要な要素（ボタンやリンクなど）を隠す /
.noprint, .aui-button, .page-metadata {
display: none !important;
}
/ 画像がページからはみ出るのを防ぐ /
img {
max-width: 100% !important;
height: auto !important;
}
この設定のポイント
- `page-break-after: avoid`: 見出しの直後に本文が来るように制御し、見出しだけがページの最下部に残るという悲劇を防ぎます。
- `table-layout: fixed`: これが最も重要です。表の中の文字が長すぎてページ外へ突き抜ける現象をこれでシャットアウトします。
—
3. HelloWorld的な動作確認：まずはここから
いきなり数千ページの仕様書をいじってはいけません。まずは「テスト用ページ」を作成し、以下の手順で精度を確かめてください。
1. テスト用ページ作成: 複雑な表、画像、長いコードブロックを含むページを作成。
2. PDFエクスポート実行: 標準機能でPDFを出力。
3. スタイリング調整: 上記のCSSを適用し、再度出力。
4. 比較: 「文字が切れていないか」「余白は適切か」を確認。
もしコードブロックが崩れるなら、以下を追加してください。
pre, code {
font-family: ‘Courier New’, monospace;
white-space: pre-wrap; / 長いコードを折り返す /
background-color: #f4f4f4;
padding: 10px;
display: block;
}
—
4. 限界を超えるための「裏技」：外部ツール連携
Confluenceの標準機能では、どうしても限界（PDFの目次生成の柔軟性など）がある場合があります。その場合は、無理にツール内で完結させず、「Pandoc」 を使ったパイプラインを構築しましょう。
- Pandocとは: マークアップ言語を自在に変換する最強のドキュメント変換エンジンです。
- 手法:
1. Confluenceから「HTML」または「Markdown」でエクスポート。
2. GitHub ActionsやローカルスクリプトでPandocを呼び出す。
3. LaTeXテンプレートを適用し、最高品質のPDFを生成する。
Pandocを使った変換コマンド例
pandoc input.html -o output.pdf –pdf-engine=xelatex –template=my-template.tex
この方法なら、ロゴの配置からフォントの埋め込み、複雑な数式のレンダリングまで、印刷物レベルのクオリティを達成できます。
—
最後に：ツールに振り回されるな
多くの初心者は「Confluenceの機能が足りない」と嘆きますが、それはツールを「完成された箱」だと勘違いしているからです。
Confluenceは、CSSを当てることで「メディア（Web、紙、スライド）」を自在にスイッチできる「情報プラットフォーム」です。今回紹介したCSSをあなたのプロジェクトに組み込んでみてください。
「ドキュメント修正に追われる時間」が「チームでより良いプロダクトを議論する時間」に変わるはずです。それが、アジャイルなエンジニアの生き方ですよ。
もし設定で迷うことがあれば、いつでも聞いてくださいね。応援しています。