pandoc-pdf-generation

Pandoc による PDF 生成

進化するスキル：このスキルは使用を通じて改善されます。指示が誤っている、パラメーターが変化している、または回避策が必要になった場合は、先送りせずにこのファイルをすぐに修正してください。実際に再現できる問題がある場合に限り、更新してください。

概要

XeLaTeX エンジンを使用する Pandoc で、Markdown から高品質な PDF ドキュメントを生成します。このスキルでは、自動的なセクション番号付け、目次、参考文献の管理、LaTeX のカスタマイズ、および実運用で得られた一般的なトラブルシューティングのパターンを扱います。

このスキルを使う場面

次のような場合に、このスキルを使用してください。

• 高品質な書式が求められる Markdown から PDF への変換
• セクション番号と目次の自動生成
• 引用と参考文献の重複を手作業で管理せずに処理
• LaTeX 出力での表の書式設定と改ページの制御
• PDF 生成ワークフローの自動化

クイックスタート：汎用ビルドスクリプト

信頼できる唯一の情報源パターン

このスキルでは、実運用で検証済みのアセットを $(cc-plugin-root doc-tools)/skills/pandoc-pdf-generation/assets/ に用意しています。

• table-spacing-template.tex - 実運用向けに調整済みの LaTeX プリアンブル（booktabs、colortbl、目次の修正）
• build-pdf.sh - 入力を自動検出する汎用ビルドスクリプト

任意のプロジェクトから使う

/usr/bin/env bash << 'DETECT_EOF'
# Create symlink once per project (git-friendly)
ln -s "$(cc-plugin-root doc-tools)/skills/pandoc-pdf-generation/assets/build-pdf.sh" build-pdf.sh

# Auto-detect single .md file in directory (landscape default)
./build-pdf.sh

# Portrait mode
./build-pdf.sh --portrait document.md

# Monospace font for ASCII diagrams
./build-pdf.sh --monospace diagrams.md

# Explicit input/output
./build-pdf.sh input.md output.pdf
DETECT_EOF

オプション：

機能：

• ✅ 入力ファイルを自動検出します（.md ファイルが 1 つだけの場合）
• ✅ 参考文献ファイル（references.bib）と CSL ファイルを自動検出します
• ✅ 常にこのスキルの実運用で検証済みの LaTeX プリアンブルを使用します
• ✅ 実行前チェック（pandoc、xelatex、ファイルの存在確認）
• ✅ ビルド後の検証（ファイルサイズ、ページ数）
• ✅ コードブロックを同じページに保ちます（ページをまたいで分割しません）
• ✅ Lua フィルターで PDF 出力から <details> ブロックを非表示にします

横向き PDF（クイックコマンド）

青色のハイパーリンクを含む横向き PDF を生成する場合（build-pdf.sh への依存なし）：

pandoc file.md -o file.pdf \
  --pdf-engine=xelatex \
  -V geometry:a4paper,landscape \
  -V geometry:margin=1in \
  -V fontsize=11pt \
  -V mainfont="DejaVu Sans" \
  -V colorlinks=true \
  -V linkcolor=blue \
  -V urlcolor=blue \
  --toc --toc-depth=2 \
  --number-sections

横向きが適している用途：幅の広いデータテーブル、比較マトリックス、コードブロックを含む技術ドキュメント。

手動コマンド（LaTeX プリアンブルを使用）

/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
pandoc document.md \
  -o document.pdf \
  --pdf-engine=xelatex \
  --toc \
  --toc-depth=3 \
  --number-sections \
  -V geometry:margin=1in \
  -V mainfont="DejaVu Sans" \
  -H "$(cc-plugin-root doc-tools)/skills/pandoc-pdf-generation/assets/table-spacing-template.tex"
SKILL_SCRIPT_EOF

ASCII 図

ASCII 図を PDF に出力する際に文字の配置が崩れないよう、文字の配置を一貫させる必要があります。ボックス描画文字を一貫して使用し、各行の幅を同じにしてください。

これも重要です：注釈はコードブロックの外に置いてください。図のコードブロック内に # contains: file1, file2 のようなインラインコメントを追加しないでください。配置が崩れます。

PDF 出力でコンテンツを非表示にする

--hide-details を使用すると、PDF 出力から <details> ブロックを取り除けます。次のような場合に便利です。

• 図のソースブロック：図を再生成するためのソースを Markdown に残しつつ、印刷用 PDF では非表示にする
• 技術的な実装メモ：ウェブ／Markdown 表示では見せ、印刷用配布資料では非表示にする
• 折りたたみ可能なセクション：HTML の <details> タグは PDF では折りたたみ表示になりません

使用方法：

./build-pdf.sh --hide-details document.md

Markdown のパターン：

## My Section

```diagram
┌─────┐     ┌─────┐
│ Box │ ──> │ Box │
└─────┘     └─────┘
```

[Box] -> [Box]

With --hide-details, the entire <details> block is stripped from PDF output while remaining visible in markdown/HTML.

Verification Checklist

Before considering a PDF "done", verify:

Pre-Generation:

• No manual section numbering in markdown (use --number-sections)
• Annotations are outside code blocks, not inside

Post-Generation:

• Open PDF and visually inspect each page
• Verify diagrams don't break across pages
• Check section numbering is correct (no "1. 1. Title" duplication)
• Confirm bullet lists render as bullets, not inline dashes

Pre-Print:

• Get user approval before printing
• Confirm orientation preference (landscape/portrait)
• Confirm duplex preference (one-sided/two-sided)

Printing Workflow

Always let the user review the PDF before printing.

Open for review:

open output.pdf

片面印刷：

lpr -P "PRINTER_NAME" -o Duplex=None output.pdf

両面印刷：

lpr -P "PRINTER_NAME" -o Duplex=DuplexNoTumble output.pdf  # Long-edge binding
lpr -P "PRINTER_NAME" -o Duplex=DuplexTumble output.pdf    # Short-edge binding

プリンター名を確認する：

lpstat -p -d

ユーザーの承認なしに印刷しないでください。問題がある場合、用紙が無駄になります。

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

詳しい情報については、以下を参照してください。

• コア開発原則 - まずはこちら - 本番環境での障害から学んだ、普遍的な原則
• PDF 用 Markdown - 見やすい横向き PDF を作成するための Markdown 構造パターン
• YAML フロントマターの構造 - YAML メタデータのパターン
• LaTeX のカスタマイズ - プリアンブルと表の書式設定
• 参考文献と引用 - BibTeX と CSL のスタイル
• ドキュメントのパターン - ドキュメントの種類別テンプレート
• トラブルシューティング - よくある問題と解決方法

トラブルシューティング

実行後の振り返り

このスキルの実行が完了したら、終了する前に次の点を確認してください。

1. コマンドは成功しましたか？ — 失敗した場合は、失敗の原因となった指示またはエラー表を修正してください。
2. パラメーターや出力に変更がありましたか？ — 基盤となるツールのインターフェースに変更があった場合は、使用例とパラメーター表を合わせて更新してください。
3. 回避策が必要でしたか？ — 即興で対応した場合（別のフラグや追加手順など）は、次回同じ回避策が不要になるよう、この SKILL.md を更新してください。

問題が実際に発生し、再現可能な場合にのみ更新してください。推測に基づいて更新しないでください。