AsciiDocでドキュメントや記事を書いていると、VS Codeのリアルタイムプレビューで綺麗にレイアウトが組めて感動しますよね。しかし、いざ「これをPDFに出力しよう」とした時、こんな疑問や違和感にぶつかったことはありませんか？
- 「あれ？VS Codeのプレビュー画面と、出力されたPDFで『見た目（デザイン）』が全然違う……」
- 「プレビューでは綺麗に収まっていた表やコードが、PDFにすると枠を突き破って消えてしまう……」
ネット上でも「AsciiDocはPDF化するとレイアウトが崩れる」という噂をよく耳にします。今回は、このPDF化にまつわる「見た目のギャップ」や「表の崩れ」の真相と、プレビュー通りの綺麗なPDFを作るための決定版ツールについて徹底解説します！
1. 百聞は一見に如かず！「プレビュー」と「PDF出力」で何が起きるのか
まずは、以下の「コードブロックや長い文字列を含む表」のサンプルコードを見てください。
【レイアウトが崩れやすい検証用サンプル】
[cols="1,2"]
|===
| 項目 | 詳細
| 日本語の長文
a| セルの中に長い日本語の文章を入力した場合のテストです。
プレビュー画面では適度な幅で折り返されますが、標準のPDFに出力するとA4用紙の幅やマージンの計算によって予期せぬ位置で改行されることがあります。
| コードブロック
a|
[source,bash]
----
# 長いコマンドやURLを入れると、標準のPDF化の際に右枠を突き破りやすくなります
aws ec2 run-instances --image-id ami-0abcdef1234567890 --count 1 --instance-type t2.micro --key-name MyKeyPair
----
|===これを実際に変換したときの様子を比べてみましょう。
① VS Codeのプレビュー画面の見た目
VS Codeのプレビューは「画面」で見ることを前提としているため、スクロールバーが出たり、画面幅に合わせて比較的きれいにレンダリングされます。
② 標準PDF出力の結果
一方、これを標準のPDFツールで出力すると、以下のようなギャップや崩れが発生しやすくなります。
【起きる問題の例】
- 見た目のギャップ：強制的にA4印刷用の書類風デザイン（白背景・標準フォント）に変わるため、雰囲気がガラリと変わる。
- 致命的な崩れ：長いコマンドの文字列などがPDFの右側枠を完全に突き破ってページ外へ消え去る。
2. なぜ「プレビュー」と「PDF」でこれほど差が出るのか？
原因はズバリ、「画面で見るためのプレビュー」と「紙に印刷するためのPDF」で、裏側で動いている仕組みやデザイン（CSS）が全く違うからです。
- VS Codeのプレビュー（画面用） エディタのテーマやブラウザの柔軟な処理が働くため、多少長めの文字列やコードがあっても画面幅に合わせてよしなに扱ってくれます。
- 標準のPDF出力結果（印刷・書類用） A4用紙という「決まった紙の幅」に収める必要があるため、文字の折り返し位置が厳密になり、設定や書き方が甘いとレイアウトが破綻しやすくなります。
3. 解決策：プレビューに一番近い見た目を再現できる「asciidoctor-web-pdf」
「標準のPDFツールだと崩れやすいし、見た目も変わりすぎて困る……」という場合に大活躍するのが、モダンな変換ツール asciidoctor-web-pdf です。
このツールは、原稿を一度HTMLに変換し、裏側でGoogle Chrome（Chromium）のエンジンを動かしてPDFを生成します。そのため、ブラウザ（プレビュー画面）に近い柔軟なレイアウトや折り返し処理を維持したままPDF化できるのが最大の強みです！
① インストール（ローカル環境）
ターミナル（VS Codeのターミナル等）で、対象のフォルダに移動してインストールします。
npm install @asciidoctor/core asciidoctor-pdf(※npmに登録されているパッケージ名は asciidoctor-pdf です)
② PDFへの変換コマンド
Windowsなどの環境でもパスエラーを出さずに確実に実行するため、先頭に npx を付けて実行します。
npx asciidoctor-web-pdf main.adocこれだけで、HTMLのレンダリングエンジンを通した「崩れにくい美しいPDF」が生成されます！
💡 注意：デザイン（色やフォント）は「書類用」に変わります！
`asciidoctor-web-pdf` を使うと、プレビューと同じ「崩れないHTML構造」で出力できますが、デザイン（見た目）はVS Codeのテーマではなく、A4印刷用のカッチリした書類フォーマット（白い背景、標準フォント）に自動で切り替わります。 「VS Codeのダークテーマのまま出力されるわけではない」点と、「画面幅ではなくA4用紙の幅に合わせて文字が折り返される」点には注意してください。
4. さらに表やコードを崩れにくくするAsciiDoc側の書き方のコツ
ツールを使いこなすだけでなく、原稿の書き方を少し工夫するだけで、PDF化の際の崩れを完全に防ぐことができます。
コツ1：長文やコードが入るセルには a| を使う
セル内にリストやコードブロック、複数行の文章を入れる場合は、セルを「ブロック要素」として扱う a| を必ず使いましょう。
[cols="1,2"]
|===
| 項目 | 詳細
| エラーログ
a|
[source,bash]
----
aws ec2 run-instances --image-id ami-0123456789
----
| 補足
| ここに通常のテキストを書きます
|===これを使うだけで、セル内がぐちゃぐちゃになるのを防げます。
コツ2：列の幅（比率）を明示する
cols 属性を使って、あらかじめ各列の幅の比率を指定しておくと、ツール側がレイアウトを計算しやすくなります。
[cols="1,3"]
|===
| 項目 | 内容
|===5. まとめ
- プレビューとPDFのギャップ：画面用と印刷用ではデザインや折り返し位置が異なる。
- 解決の切り札：ブラウザエンジンを使ってプレビューに近い綺麗なレイアウトを維持できる
asciidoctor-web-pdfがおすすめ！ - 崩れを防ぐ書き方：
a|や列幅指定（cols）を組み合わせて、より強固なドキュメントにする。
AsciiDocをPDFにする際は、ツールの特徴やレイアウトの癖を知っておくことで、無駄な試行錯誤の時間をグッと減らすことができます。ぜひ試してみてください！
コメント