A visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
EPUB ビルダースクリプト
Claude How-To の Markdown ファイル群から EPUB 形式の電子書籍をビルドするスクリプト。
特徴
- フォルダ構成(01-slash-commands、02-memory など)に沿って章を整理する
- Mermaid 図を Pele(Node.js で実行する固定バージョンのバンドル)で SVG 画像としてレンダリングする。CSS 変数は白背景上の通常の色に置き換えるため、どの EPUB リーダーでも表示できる
- 同一の図をキャッシュし、ユニークな図は一度だけレンダリングする
- プロジェクトロゴから表紙画像を生成する
- 内部 Markdown リンクを EPUB の章参照へ変換する
- 厳格モード — レンダリング不能な図があればビルドを失敗させる
必要環境
- Python 3.10+
- uv
- Mermaid 図レンダリング用に
PATH上の Node.js >= 20。固定バージョンの Pele バンドルは初回実行時にダウンロードされ(ネットワークが必要なのは一度だけ)、sha256 で検証してscripts/.vendor-cache/pele/にキャッシュされる
クイックスタート
# 最も簡単な方法 — uv がすべてを処理する
uv run scripts/build_epub.py
開発環境セットアップ
# 仮想環境を作成
uv venv
# 有効化して依存関係をインストール
source .venv/bin/activate
uv pip install -r requirements-dev.txt
# テストを実行
pytest scripts/tests/ -v
# スクリプトを実行
python scripts/build_epub.py
コマンドラインオプション
usage: build_epub.py [-h] [--root ROOT] [--output OUTPUT] [--verbose]
[--lang {en,vi,zh,ja}]
options:
-h, --help show this help message and exit
--root, -r ROOT Root directory (default: repo root)
--output, -o OUTPUT Output path (default: claude-howto-guide.epub)
--verbose, -v Enable verbose logging
--lang {en,vi,zh,ja} Language to build (default: en)
使用例
# 詳細ログ付きでビルド
uv run scripts/build_epub.py --verbose
# 出力先をカスタマイズ
uv run scripts/build_epub.py --output ~/Desktop/claude-guide.epub
# 日本語版をビルド
uv run scripts/build_epub.py --lang ja
出力
リポジトリのルートディレクトリに claude-howto-guide.epub を生成する。
EPUB には次が含まれる:
- プロジェクトロゴ付きの表紙画像
- ネストされた目次
- すべての Markdown コンテンツを EPUB 互換 HTML に変換したもの
- SVG 画像としてレンダリングされた Mermaid 図
テストの実行
# 仮想環境を使う場合
source .venv/bin/activate
pytest scripts/tests/ -v
# または uv で直接実行
uv run --with pytest --with pytest-asyncio \
--with ebooklib --with markdown --with beautifulsoup4 \
--with pillow \
pytest scripts/tests/ -v
依存関係
PEP 723 のインラインスクリプトメタデータで管理する:
| パッケージ | 用途 |
|---|---|
ebooklib |
EPUB 生成 |
markdown |
Markdown から HTML への変換 |
beautifulsoup4 |
HTML パース |
pillow |
表紙画像生成 |
トラブルシューティング
Pele is unavailable でビルドが失敗する: Node.js >= 20 をインストールし、node が PATH 上にあることを確認する(node --version)。
Pele バンドルのダウンロードまたはチェックサムの失敗: 初回ビルドは固定バージョンの Pele バンドルを cdn.jsdelivr.net からダウンロードし、各ファイルの sha256 を検証する。オフラインやプロキシ環境では、ネットワークに接続した状態で一度ビルドすれば、以降は scripts/.vendor-cache/pele/<version>/ のキャッシュを使う。チェックサムの不一致はダウンロードが改変または途中で切れたことを意味するので、そのフォルダを削除して再度ビルドする。
ロゴが見つからない: claude-howto-logo.png が見つからない場合、スクリプトはテキストのみの表紙を生成する。