studiogadget Notion → PDF 変換スキル
NotionページをNotion MCPで取得し、スタイリングされたPDFに変換する。
前提条件
- Notion MCP が接続されていること（
mcp_notion_API-*ツールが使用可能） - Node.js がインストールされていること
- Chrome/Chromium が環境にあること（自動検出される）
ワークフロー
ステップ1: 対象ページの特定
ユーザーからNotionページの情報を受け取る。
- URLが提供された場合: URLからページIDを抽出する
- 形式:
https://www.notion.so/.../<title>-<page-id>またはhttps://www.notion.so/<page-id> - URLの末尾32文字（ハイフンなし16進数）がページID
- ハイフン付きUUID形式（
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx）はそのまま使用可能
- 形式:
- IDが提供された場合: そのまま使用
- タイトルが提供された場合:
mcp_notion_API-post-searchで検索し、候補をユーザーに提示して選んでもらう - 曖昧な場合: どのページか確認する
ステップ2: ページ内容の取得（インクリメンタル処理）
コンテキスト制限に対応するため、ブロック取得とHTML変換をバッチ単位で交互に行う。全ブロックのJSONをメモリに保持しない。
mcp_notion_API-retrieve-a-pageでページメタデータ（タイトル、プロパティ）を取得- HTMLファイルを作成し、テンプレートの
<head>〜<article class="markdown-body">+<h1>タイトル</h1>を書き込む mcp_notion_API-get-block-childrenで子ブロックを1ページ分取得- 取得したブロックを即座にHTMLに変換し、ファイルに追記する
has_children: trueのブロックは子ブロックを取得して変換（再帰の深さ上限: 5階層）- レスポンスに
has_more: trueがある場合はstart_cursorで次ページを取得し、手順4〜5を繰り返す - 全ブロック処理後、
</article>+ スクリプトタグ +</body></html>を書き込んで閉じる
リストのグルーピング: 連続するリストアイテムの <ul> / <ol> ラッパーの開閉は、前回バッチの末尾ブロックタイプを記憶して管理する。
子ページを含める場合は、child_page タイプのブロックIDで再帰的にステップ2を実行する。
ステップ3: HTML生成
取得したブロックデータをもとにHTMLを生成する。
- HTMLテンプレートは
references/html-template.mdを参照 - ブロック → HTML変換ルールは
references/block-to-html.mdを参照
重要なポイント:
data-color-mode="light"属性が必須（Primer CSSのテーマ変数を有効化）- mermaid コードブロックがある場合のみ mermaid
<script>タグを挿入（CDN非対応環境でのタイムアウト防止） - 数式（
equationブロック /rich_text内のtype: "equation"）がある場合のみ KaTeX の CSS +<script>タグを挿入 - 画像は
<img src="url">としてそのまま含める（PDF変換スクリプトがダウンロード・Base64埋め込みを処理する） - トグルは
<details open>で常に展開状態にする（PDFでは折りたたみ不可） - テーブルは
<table>+<thead>/<tbody>で構成
生成したHTMLを作業ディレクトリに保存する。ファイル名: {ページタイトル}.html
ステップ4: PDF変換
スキルディレクトリの scripts/html-to-pdf.mjs を使用してPDFに変換する。puppeteer-core で HTML を開き、CSS読み込みと mermaid 図・KaTeX 数式のレンダリングを待ってからPDF化するスクリプト。
Chrome/Chromium バイナリは環境から自動検出される（CHROME_PATH 環境変数でも指定可能）。HTML内の CDN URL は、scripts/vendor/ にローカルファイルがあれば自動的にローカルパスに置換される（Primer CSS は vendor/primer.css に同梱済み）。
スキルディレクトリのパスは、このファイル（SKILL.md）が存在するディレクトリ。
# 依存パッケージのインストール（node_modules が存在しない場合のみ）
npm install --prefix <skill-dir>/scripts
# PDF生成
node <skill-dir>/scripts/html-to-pdf.mjs <input.html> <output.pdf> [--format=A4]
オプション:
--format=A4（デフォルト）/--format=Letter等--margin=20mm（デフォルト）
ステップ5: 完了
- 生成されたPDFのパスをユーザーに報告
- 一時HTMLファイルを削除
- 追加ページの変換が必要か確認
オプション
ユーザーが指定可能。指定がなければデフォルトを使用し、事前に聞かない。
| オプション | デフォルト | 説明 |
|---|---|---|
| 出力ファイル名 | ページタイトル.pdf | PDFのファイル名 |
| 用紙サイズ | A4 | A4, Letter 等 |
| 子ページ含む | false | サブページも含めるか |
エラーハンドリング
- Notion MCPが未接続:
mcp_notion_API-*ツールが使えない場合、MCP接続設定を確認するよう案内する - ページが見つからない: URL/ID/タイトルの再確認を促す。検索結果が複数ある場合は候補を提示
- puppeteer-core未インストール:
npm install --prefix <skill-dir>/scriptsの実行を提案 - Chrome が見つからない:
CHROME_PATH環境変数の設定か Chrome/Chromium のインストールを案内 - 画像取得失敗: PDF変換スクリプトが画像ダウンロードに失敗した場合、その画像は空白になるがPDF生成は続行。ログの Warning をユーザーに報告
- ブロック取得のページネーション: 100ブロック超のページでは
has_moreを確認し、全ブロック取得するまで繰り返す - 再帰の深さ超過: ネスト5階層を超えた場合はそれ以上の子ブロック取得をスキップし、「（省略）」と表示する