冊子PDF生成スキル

Markdown原稿を、選択したデザインテンプレートでPDF冊子に変換する。生成して終わりにせず、必ず主要ページを画像プレビューして崩れがないか確認してから確定する。

構成

Markdownの解釈(章扉・Q&A・POINT/HINT/COLUMNカード・表などへの変換)とページネーションは lib/engine.py が全テンプレート共通で担当する。テンプレートは templates/<名前>/ 配下に置き、次の3点だけを持つ:

• style.css — 見た目(デザイン定義)
• template.json — name(表示名)・description(概要)・palette(章カラー配列。省略時はデフォルト8色)・nombre(ページ番号の体裁。省略可)
  • nombre は font_size / color / font_family / align / format / skip_cover を指定できる。省略時は 7pt / #7A8194 / 'Noto Sans CJK JP' / right / {page} / {total} / false。ノンブルはPDFのフッター領域に描画されるため style.css からは変更できず、ここでしか指定できない
  • format は {page}(ページ番号)と {total}(総ページ数)を埋め込める。印刷物では "{page}" だけにすることが多い
  • skip_cover: true にすると1ページ目(表紙)にノンブルを入れない。Chromiumのフッターはページごとに出し分けられないため、内部では1ページ目と2ページ目以降を別々に書き出して pdfunite(poppler)で結合している。poppler が無い環境では警告を出して全ページに入った状態で出力される
• README.md — カスタマイズ方法や既知の注意点など、そのテンプレート固有の補足(任意)

0. 前提パッケージの確認

以下が無ければ、インストール前にユーザーに確認を取る(外部ネットワークアクセスのため無断で実行しない)。

• Python: markdown, beautifulsoup4, playwright(+ playwright install chromium)
• プレビュー用: pdftoppm(poppler。Homebrewなら brew install poppler)

確認コマンド例:

python3 -c "import markdown, bs4, playwright" 2>&1
which pdftoppm

1. テンプレートを選ぶ

1. templates/*/template.json を読み、name と description を一覧にしてユーザーに提示する
2. 原稿の内容やユーザーの過去の指定からテンプレートが明らかな場合は確認の上で決めてもよい

1.5 原稿を執筆ルールに照らして確認する

ビルド前に lib/WRITING_GUIDE.md を読み、原稿がルールに沿っているか確認する。レイアウトだけで直せそうなもの(章末まとめカード直前の短い段落など)であっても、著者の意図に関わるもの(見出しラベルの句点有無、極端に長いカード等)であっても、例外なく原稿を勝手に書き換えない。該当箇所と原因、推奨する直し方をユーザーに提示し、明示的な指示を得てから編集する。「既知のパターンだから」は自動修正してよい理由にはならない。

2. ビルドする

python3 lib/engine.py templates/<選ばれたテンプレート> <原稿.md> <一時出力.pdf>

出力は一旦、確認用の一時ファイル(scratchpadなど)に書き出す。ユーザーが確認するまで、既存の最終成果物ファイルを上書きしない。

open <一時出力.pdf> でmacOSの既定のPDFビューア(Preview.app等)を開き、ユーザー自身が実物のPDFを直接確認できるようにする(Claude側の画像プレビューだけに頼らない)。Previewは一度開いたファイルの変更を自動反映しないことがあるため、再ビルドして中身が変わった場合はユーザーに「Previewを閉じてから開き直す」よう伝える。

3. プレビューする(省略しない)

生成したPDFをReadツールでページ単位の画像として確認する。全ページではなく、崩れが起きやすい以下のページに絞る:

• 表紙(1ページ目)
• 各章扉(原稿の ## 第n章 等の見出しがある位置。grep -n "^## " 原稿.md で見出し一覧を出し、pdftotext -layout でおおよそのページ番号を特定してから該当ページだけ読む)
• 表・引用・POINT/HINT/COLUMNカードなど、装飾の多いページを1〜2枚

Readツールの pages パラメータは複数ページのカンマ区切り指定が安定しないことがあるため、1ページずつ個別に呼び出す。

加えて、h3見出し(### )が直後の内容と別ページに分かれていないかを機械的にスキャンする(全ページを目視するより速く、見落としも減る):

python3 lib/scan_h3_orphans.py <原稿.md> <確認したいPDF>

「要確認」と出た箇所は、検索の誤検出であることもあるため、該当ページを目視で確認してから対応する。「None」はコードブロック直後などテキスト一致に失敗しているだけのことが多く、必ずしも問題ではない。

改ページ・レイアウトの個別調整は、実行前に必ずユーザーに確認する。「◯◯を前ページに入れたい」「なぜここで改ページされるのか」といった指摘に対して、原因(実測データ)を示すのはよいが、直す・直さない・どう直すかの判断や実際の編集は、ユーザーの明示的な指示を待ってから行う。「既知のパターンに該当するから」であっても、修正案を先に短く提示して確認を取ってから編集する(1.5節の「機械的に直せるもの」の例外は、原稿を新規ビルドする際の最初の1回のみに適用し、それ以降ユーザーとのやり取りの中で個別ページについて質問された場合は都度確認する)。また、一箇所を直す変更が別の既存マーカー(前回までに追加したもの)と重複・干渉していないか、編集前にgrep等で確認する。

チェック観点:

• グラデーション文字やぼかし影が輪郭の崩れた四角形になっていないか(background-clip: text や box-shadow のブラー由来。下記「レンダリング上の既知の制約」を参照)
• 改ページ位置でカード・表が分断されていないか
• フォントが豆腐(□)化していないか

4. 確認とイテレーション

プレビュー画像をユーザーに見せて確認を取る。問題が指摘されたら、まず原因を実測・提示する。修正案が複数考えられる場合や、原稿・CSS・engine.pyのどれを直すかの判断が要る場合は、先に方針を提示してユーザーの指示を得てから編集する。指示を得た上で該当テンプレートの style.css を修正し(Markdown解釈自体の不具合なら lib/engine.py)、2に戻って再ビルド・再プレビューする。修正したファイルに直接書き戻す(次回以降の生成でも直る状態にする)。

改ページ位置がドキュメント全体に影響する仕組みのため、修正後は表紙・章扉だけでなく、崩れが指摘されたページの前後も含めて広めにプレビューし直す。

エンジン側の改善だけでは避けきれない崩れパターンもあるため、原稿の書き方自体で予防できる点は lib/WRITING_GUIDE.md にまとめている。原稿を新規作成・大幅改訂する際は先にこれを読んでおくと、後からの改ページ修正が減る。

見出しっぽい短い段落がページ末尾で孤立して大きな空白ができる、といった典型パターンは lib/engine.py のPAGINATE_JS側で自動的に防止しているが、それでも収まりが気に入らない箇所が残る場合は、原稿に手動マーカーを追記して個別対応できる(詳細は lib/HTML_CONTRACT.md の「手動レイアウト調整マーカー」を参照):

• <!-- page-break --> … その位置で強制改ページ
• <!-- space: 8mm --> … その位置に指定した余白を挿入

OKが出たら、一時出力をユーザーが指定した最終保存先にコピーする。

テンプレートが実装すべきHTML構造・CSSクラスの詳細な契約は lib/HTML_CONTRACT.md を参照。

Markdown自動変換ルール(全テンプレート共通)

原稿は下記の書式に沿って書くと、lib/engine.py が意味づけして各テンプレートの見た目に流し込む。

レンダリング上の既知の制約

グラデーション文字(background-clip: text)やぼかし付きbox-shadowは、ヘッドレスChromiumのPDF書き出しで輪郭の崩れた四角形になるアーティファクトが出ることが確認されている。新しいテンプレートのCSSを書く際は、単色文字+実線ボーダーなど、ぼかし・クリップに依存しない表現を使うこと。

テンプレートの追加方法

templates/ 直下に新しいフォルダを作り、style.css と template.json を置く(README.md は任意)。この規約さえ満たせば、SKILL.md側の手順は変更不要でテンプレートを追加・選択できる。実際の作成作業は pdf-booklet-template-designer スキルに任せてよい。