Vivliostyle CLIでKindle出版環境を作る — kdp-factoryリポジトリ立ち上げの記録

プログラミングコードでKindle出版する環境を、今日一日で立ち上げた。リポジトリ名は kdp-factory。Markdownで原稿を書き、CLIでEPUBを生成し、Kindle Previewer 3で確認するところまで一気通貫で動くようになった。

「ストーリーブックみたいな名前のやつ」の正体探しから始まった

発端は記憶の断片だった。「Kindleの出版に使えるオープンソースのライブラリがあったはず。確かストーリーブックみたいな名前の……」という曖昧な手がかりだけでClaude Codeに調査させたところ、最初に返ってきた答えは GitBook だった。たしかに名前は近い。でも開発停止済みで、後継はHonKitだという。

調査結果を眺めながら数分考えて、思い出した。私が探していたのは Vivliostyle CLI だ。日本発のCSS組版ツールチェーンで、VFM（Vivliostyle Flavored Markdown）で書いた原稿から EPUB と PDF を同時に出力できる。GitBookじゃなくてこっちを詳細に調べ直してもらい、調査ドキュメントを丸ごと書き換えてもらった。

調査で判明した要点はこうだった。

KDPに公式APIは存在しない。コードで自動化できるのはEPUB生成・検証まで
MOBI / kindlegen は完全廃止済み。今は EPUB 3 の直接アップロードが標準
Vivliostyle の EPUB 出力は CSS をそのまま素通しするので、Kindle 非対応の CSS（CSS変数・Flexbox・Grid・@page）を避けたEPUB専用テーマが要る

最後の1点が、午後の試行錯誤の伏線になった。

kdp-factory リポジトリの立ち上げ

~/Git_repo/ 直下に新規リポジトリ kdp-factory を作った。初期セットアップで指示したのは次の通り。

パッケージマネージャは npm ではなく pnpm に切り替えてもらった
pnpm build で PDF + EPUB の生成疎通を確認（PDF 142KB / EPUB 23KB）
ビルド中間生成物の .vivliostyle/ がコミットに混入したので、gitignoreに追加して直前コミットから除外してもらった
CLAUDE.md を作成。リポジトリの目的、pnpmコマンド、今日実証したハマりどころ（configの相対パスがcwd基準で解決される件、Kindle向けEPUBのCSS制約）、執筆ルール（ルビ記法・表の画像化・ページ参照禁止）まで書き込んでもらった
memo/ ディレクトリを作り、調査メモもそちらに保存

サンプルプロジェクトとして、会計学習書のコンテンツが1冊分入っている。これを実験台にして以降の検証を回した。

余白が大きすぎる — テーマのデフォルト値を疑う

pnpm preview でブラウザのライブプレビューを立ち上げて、最初に目についたのが余白だった。本文の周りに白い空間が広がりすぎていて、ページの半分くらいしか文字が載っていないように見える。「こんなもんですか？」とClaude Codeに聞いたら、使っていたテーマ（theme-techbook）のデフォルト余白の値を調べてくれた。

余白調整のCSSを追加してもらったが、ここで小さい事故が連発した。プレビューが作業ディレクトリを掴んだままでビルドが失敗し、13000番ポートの残骸プロセスの掃除が要った。さらにシェルに $ を食われてコマンドが化け、クォートの修正で再実行。一つずつ潰して、最終的に余白調整は反映された。

EPUBの実機確認用に Kindle Previewer 3 を使ったのだが、途中でアップデートのインストーラーが「ファイルを上書きできない」と止まった。スクリーンショットを貼って原因を調べさせたら、犯人はさっきEPUB確認用に起動したKindle Previewer本体だった。プロセス（PID 65304）が実行中のままファイルをロックしていた。プロセスを終了させ、Tempフォルダに残っていたインストーラーを再実行して、3.104.0へのアップデートを完了させた。

ついでに分かった仕様がもう一つ。Kindle PreviewerはGUIが起動中だと、CLIの変換を同時に走らせられない。CLIの品質チェックが失敗して初めて気づいた。

プレビューと実際の出力が違う — 原因は再レンダリングではなかった

新しいPreviewerでEPUBを開いて見比べたとき、手が止まった。ブラウザで見ていたVivliostyleのプレビューと、Kindle Previewerに映っている画面が、だいぶ違う。プレビューにあったサンプル章の表示が、Kindle側には入っていない。

最初は「アップデート後に再レンダリングしていないからでは」と疑った。でも調べさせると、再レンダリングの問題ではなく2つのフォーマットの仕様の違いで、これが正常な挙動だった。ブラウザプレビューはPDF用のレイアウトを描画していて、EPUBはリフロー型なので同じ見た目にはならない。

ここで引き下がらずに食い下がった。「自費出版している人たちは、EPUBでもっと見た目をコントロールできているはず」と。すると話が一段深くなった。「Kindleが解釈できない」のは今入っているPDF用テーマ（CSS変数だらけ）の話で、Kindle自体は普通のCSSをかなり解釈できる。見出しのデザイン、表の罫線・背景色、字下げ、フォント指定（埋め込みも可）、余白。きれいに出している自費出版本はまさにそこを作り込んでいる。今の見た目が素っ気なかったのは、単にEPUB用のCSSが1行も当たっていなかったからだった。

そこでEPUB用CSSを書いてもらい、Kindle Previewerで開き直した。見出しに装飾が入り、表に罫線が通った画面を見て、ようやく「これなら本になる」と思えた。

判明した内容をドキュメントに固定

「どこまでCSSを使っていいか、今回判明した内容をしっかりめに残しておいて」と指示して、EPUB用CSSのドキュメントを書かせた。doc-communicationスキルを参照させて構成を組み、READMEも今日の構成変更に合わせて更新してもらった。口頭のやり取りで分かったことは、その日のうちにリポジトリへ沈めておかないと消える。

既存サイトの章をKDP用に変換するテスト

環境ができたので、実戦テストとして eurekapu-nuxt4 リポジトリにある会計学習ノートのイントロダクション章を、KDP用に変換してもらった。

章内の図版7点をPNG化（フォントの描画崩れがないか1枚ずつ目視確認）
本文をVFM Markdownに変換して第1章として組み込み
Kindle変換チェックはエラー0で通過

Kindle PreviewerとブラウザのPDFプレビューを並べて見比べたが、これは率直に良かった。Webページとして書いたコンテンツが、ほぼそのまま本の章になる手応えを得た。

明日への積み残し

フェーズ1のイントロダクションが入ったので、フェーズ2以降の基本論点・決算・帳簿体系・演習も全部入れていきたい。ただしソース側のコンテンツを今まさに修正中で、内容が変わる可能性がある。その前提込みで計画メモを残してもらった。

フェーズ2〜5の全19章を順次変換する（進捗チェックリスト・行数・図版数の見積もり付きでメモ化済み）
着手前にソースの確定状況を確認し、章ごとにソースのコミットハッシュを記録する
演習章の特殊構造や、表のSVG化判断を個別に検討する

学び

曖昧な記憶でツールを探すと、名前が似た別物（GitBook）を掴まされる。実物（Vivliostyle CLI）に当たるまで疑うこと
EPUBはリフロー型なので、CSS組版のPDFプレビューと同じ見た目にはならない。「プレビューと違う＝バグ」と決めつけない
「Kindleでは凝ったレイアウトは無理」は半分嘘。CSS変数やGridを避ければ、見出し・表・フォントはかなり制御できる。素っ気ない見た目の原因は、たいてい「EPUB用CSSを当てていない」だけ
GUIアプリ起動中のファイルロックとCLI排他は、Windowsでの定番の罠。インストーラーが止まったら、まず実行中プロセスを疑う