Pandoc PDF Generation

自己進化型スキル: このスキルは使用を通じて改善されます。指示が間違っている、パラメータがずれている、または回避策が必要だった場合 — このファイルを即座に修正してください。延期しないでください。実在して再現可能な問題についてのみ更新してください。

概要

Pandoc と XeLaTeX エンジンを使用して Markdown から専門的な PDF ドキュメントを生成します。このスキルは、自動セクション番号付け、目次、参考文献管理、LaTeX カスタマイズ、および本番運用を通じて学習した一般的なトラブルシューティングパターンをカバーしています。

このスキルを使用する場合

以下の場合にこのスキルを使用してください:

• 専門的な書式要件を伴う Markdown から PDF への変換
• 自動セクション番号付けと目次が必要な場合
• 引用文献と参考文献を手動で複製することなく管理する必要がある場合
• LaTeX 出力内の表の書式とページ区切りを制御する必要がある場合
• 自動化された PDF 生成ワークフローを構築する場合

クイックスタート: ユニバーサルビルドスクリプト

単一の情報源パターン

このスキルは ${CLAUDE_PLUGIN_ROOT}/skills/pandoc-pdf-generation/assets/ に本番で実証済みのアセットを提供しています:

• table-spacing-template.tex - 本番チューニング済み LaTeX プリアンブル (booktabs、colortbl、ToC 修正)
• build-pdf.sh - ユニバーサル自動検出ビルドスクリプト

任意のプロジェクトから

/usr/bin/env bash << 'DETECT_EOF'
# プロジェクトごとに一度シンボリックリンクを作成 (git フレンドリー)
ln -s ${CLAUDE_PLUGIN_ROOT}/skills/pandoc-pdf-generation/assets/build-pdf.sh build-pdf.sh

# ディレクトリ内の単一 .md ファイルを自動検出 (ランドスケープがデフォルト)
./build-pdf.sh

# ポートレートモード
./build-pdf.sh --portrait document.md

# ASCII 図用等幅フォント
./build-pdf.sh --monospace diagrams.md

# 入出力を明示的に指定
./build-pdf.sh input.md output.pdf
DETECT_EOF

オプション:

フラグ	説明
--landscape	ランドスケープ向き (デフォルト)
--portrait	ポートレート向き
--monospace	DejaVu Sans Mono を使用 - ASCII 図に最適
--hide-details	PDF から <details> ブロック を非表示
-h, --help	ヘルプメッセージを表示

機能:

• ✅ 入力ファイルを自動検出 (単一 .md が存在する場合)
• ✅ 参考文献 (references.bib) と CSL ファイルを自動検出
• ✅ スキルから本番で実証済みの LaTeX プリアンブルを常に使用
• ✅ 事前フライトチェック (pandoc、xelatex、ファイル存在確認)
• ✅ ビルド後検証 (ファイルサイズ、ページ数)
• ✅ コードブロックは同じページに留まる (ページをまたがない)
• ✅ <details> ブロックを PDF 出力から非表示にする Lua フィルタ

ランドスケープ 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 ${CLAUDE_PLUGIN_ROOT}/skills/pandoc-pdf-generation/assets/table-spacing-template.tex
SKILL_SCRIPT_EOF

---

ASCII 図: 常に graph-easy を使用

重要: ASCII 図を手動で入力しないでください。常に itp:graph-easy スキルを使用してください。

手動の ASCII アートは PDF でのアライメント問題を引き起こします。graph-easy スキルは以下を保証します:

• 適切な箱線文字のアライメント
• 一貫性のあるスペーシング
• 再現可能な出力

# 一般的な図のスキルを実行
Skill(itp:graph-easy)

# ADR アーキテクチャ図の場合
Skill(itp:adr-graph-easy-architect)

同様に重要: 注釈をコードブロックの外に保つ。# contains: file1, file2 のようなインライン コメントを図コードブロック内に追加しないでください - アライメントが壊れます。

---

PDF 出力用コンテンツの非表示

--hide-details を使用して <details> ブロックを PDF 出力から削除します。これは以下の場合に便利です:

• graph-easy ソースブロック: 図の再生成のため Markdown にソースを保持しますが、印刷 PDF からは非表示
• 技術実装ノート: Web/Markdown ビューで表示、印刷配布資料からは非表示
• 折りたたみセクション: HTML <details> タグは PDF で折りたたみ可能としてレンダリングされません

使用方法:

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

Markdown パターン:

## My Section

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

<details> <summary>graph-easy source</summary>

[Box] -> [Box]

</details> ```

--hide-details を使用すると、PDF 出力から <details> ブロック全体が削除されますが、Markdown/HTML では表示されたままです。

---

検証チェックリスト

PDF が「完成」したと見なされる前に、以下を確認してください:

生成前:

• Markdown に手動でセクション番号付けがない (--number-sections を使用)
• すべての ASCII 図が itp:graph-easy スキルを通じて生成されている
• 注釈がコードブロックの中ではなく外にある

生成後:

• PDF を開いて各ページを目視で確認
• 図がページをまたがらないことを確認
• セクション番号付けが正しいことを確認 (「1. 1. タイトル」の重複がない)
• 箇条書きが箇条書きとしてレンダリングされること、インラインダッシュではないことを確認

印刷前:

• ユーザーの承認を得てから印刷
• 向きの設定を確認 (ランドスケープ/ポートレート)
• 両面印刷設定を確認 (片面/両面)

---

印刷ワークフロー

ユーザーに PDF を確認させてから印刷します。

レビューのために開く:

open output.pdf

片面印刷:

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

両面印刷:

lpr -P "PRINTER_NAME" -o Duplex=DuplexNoTumble output.pdf  # 長辺綴じ
lpr -P "PRINTER_NAME" -o Duplex=DuplexTumble output.pdf    # 短辺綴じ

プリンタ名を探す:

lpstat -p -d

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

---

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

詳細については、以下を参照してください:

• Core Development Principles - ここから開始 - 本番環境での失敗から学んだユニバーサルな原則
• Markdown for PDF - クリーンなランドスケープ PDF 用の Markdown 構造パターン
• YAML Front Matter Structure - YAML メタデータパターン
• LaTeX Customization - プリアンブルと表の書式設定
• Bibliography & Citations - BibTeX と CSL スタイル
• Document Patterns - ドキュメントタイプテンプレート
• Troubleshooting - 一般的な問題と解決策

---

トラブルシューティング

問題	原因	解決策
フォントが見つからない	DejaVu Sans がインストールされていない	brew install font-dejavu
xelatex が見つからない	MacTeX がインストールされていない	brew install --cask mactex
表がページをまたがる	longtable パッケージが欠落	table-spacing-template.tex プリアンブルを含める
セクション番号が二重	Markdown の手動番号付け	手動番号を削除、--number-sections のみを使用
ASCII 図がアライメントされていない	手動 ASCII アート	すべての図に graph-easy スキルを使用
箇条書きがダッシュとしてレンダリング	Markdown 書式設定の問題	リストの前に適切な空行があるか確認
参考文献がレンダリングされない	references.bib がない	.bib ファイルを作成または --bibliography フラグを削除
PDF ファイルサイズが大きい	フォント埋め込み	--pdf-engine-opt=-dEmbedAllFonts=false を使用

実行後の振り返り

このスキルが完了した後、クローズする前に確認:

1. コマンドは成功しましたか? — 成功しなかった場合、失敗の原因となった指示またはエラーテーブルを修正してください。
2. パラメータまたは出力が変更されましたか? — 基盤となるツールのインターフェースがドリフトした場合、使用例とパラメータテーブルを更新して現在の状況に合わせてください。
3. 回避策が必要でしたか? — 独自の工夫が必要だった場合 (異なるフラグ、余分なステップ)、次の実行で同じ回避策が必要にならないようにこの SKILL.md を更新してください。

実問題で再現可能な場合のみ更新してください — 推測ではありません。